Documentation

# Login Sessions — Consultant Guide

This guide describes how ContactManager keeps track of who is signed in, how long people stay signed in, and the settings that control it. It is written for technical and functional consultants configuring an installation or answering questions from a customer's security team.

# Contents

# How signing in and out works

When someone signs in — through the login screen, through Microsoft 365, through Windows authentication, or from the Outlook add-in — ContactManager records that sign-in on the server and gives the browser a session cookie that points at it.

Every request is then checked against that record. If the record is gone, the cookie is refused and the user is sent back to the login screen, no matter how valid the cookie itself looks.

This is what makes Log out meaningful. Previously, signing out only cleared the cookie in the browser doing the signing out; a copy of that cookie taken beforehand kept working until it expired. Now signing out removes the server-side record, so any copy of the cookie stops working immediately.

On installations spread across several web servers. Each web server remembers for up to a minute that a session was valid, so it does not have to re-check on every single request. Signing out takes effect at once on the server handling the request, and within a minute on the others. Installations running on a single web server — which is the usual arrangement — are unaffected: there, signing out takes effect at once. The same applies to changing a password and to disabling an account, both of which also end sessions.

# How long a session lasts

A session lasts 180 minutes (3 hours) by default, counted from the last time the user did something. Working in ContactManager continually pushes the expiry forward, so an ordinary working day never requires signing in again. Three hours of genuine inactivity ends the session.

The Remember me tickbox on the login screen decides whether the session survives the browser being closed. Left unticked, closing the browser ends the session — which is what someone on a shared or public machine expects. Ticked, the session lasts until the three hours run out.

Note for existing installations: this tickbox previously had no effect at all — every sign-in behaved as though it were ticked. Users who close their browser and expect to still be signed in will now need to tick it.

This value was reduced from 10 days. Ten days meant a cookie taken from a laptop stayed usable for a week and a half; three hours limits the damage while comfortably covering meetings and lunch breaks.

The value is set in the application's Web.config, in the timeout attribute of the forms authentication settings, and is expressed in minutes. Changing it requires an application restart. Discuss any increase with the customer's security officer — it directly widens the window in which a stolen cookie is usable.

# What ends a session

Event Effect
The user chooses Log out Ends that session only.
180 minutes of inactivity Ends that session.
Closing the browser, when Remember me was not ticked Ends that session.
The user changes their own password Ends all of that user's other sessions. The one used to change the password continues.
An administrator sets or clears a user's password Ends all of that user's sessions.
An administrator ticks Disabled on a user Ends all of that user's sessions immediately, rather than only preventing the next sign-in.

Expired session records are tidied up automatically by the nightly maintenance run, and again whenever the user next signs in. No manual housekeeping is needed.

# Using ContactManager in more than one place at once

Sessions are tracked individually, so a user can be signed in from the web application, the Outlook add-in and an integration at the same time. Signing out in one place does not sign the user out of the others. Only the password and account changes listed in the table above affect every session at once.

# The Administrator password on a new installation

A new installation creates an Administrator account with a fixed starting password. That password is the same in every installation and is documented publicly, so it has to be replaced before the installation is handed over. The same applies to an existing installation that never replaced it — see What changes when you upgrade.

ContactManager now enforces this rather than trusting it to be remembered:

  • In the web application, signing in as Administrator with the starting password goes straight to the change-password screen. Nothing else can be reached until a new password is set.
  • From the Outlook add-in and the API, signing in with the starting password is refused outright. It is not enough to prompt an integration to change its password — it has no screen to do that on — so the sign-in simply fails until the password has been changed in the web application.

Once the password has been changed, by the administrator or by someone editing the account, both restrictions lift immediately and permanently.

Setting up a new installation. Sign in to the web application as Administrator first and set a real password there. Configuring an integration against the starting password will not work, and the failure looks like a wrong password rather than anything more specific.

This applies only to an account still holding that starting password. It is deliberately separate from the Reset password tickbox on a user, which asks someone to choose a new password the next time they sign in: users flagged that way are prompted in the web application as before and keep working from the Outlook add-in and integrations in the meantime.

Resetting the Administrator password with the sql/Reset Password.sql utility script also lifts the restriction: that script generates a new random password, applies it, and prints it once for you to copy into the customer's password vault. Because you have seen that password, the script treats it as temporary — the account is asked to choose a new one at its next sign-in to the web application, exactly as the Reset password tickbox does. The Outlook add-in and integrations keep working with the password from the script in the meantime.

# Settings reference

Setting Location Default Description
Session timeout Web.config, forms authentication timeout 180 (minutes) How long a session survives without activity.
Remember me Login screen, per user per sign-in Unticked Whether the session survives the browser closing.
Bind session to User-Agent General configuration Off See below.
Outlook impersonation pass phrase General configuration Empty (disabled) See below.

# Bind session to User-Agent

When switched on, a session is tied to the browser that created it, and a cookie replayed from a different browser or device is refused even before the user signs out.

It is off by default, deliberately. Browsers change their identification string whenever they update themselves, which happens roughly monthly for Chrome and Edge — and when that happens the user is signed out and has to sign in again. Only switch it on where the customer accepts that trade-off.

Switching it on does not disturb people who are already signed in; it starts applying to sessions created after it is enabled.

# Outlook impersonation pass phrase

The Outlook web service has a method that signs in as a named user without that user's password, intended for the Outlook integration. It previously accepted a fixed pass phrase that was the same in every installation.

It now requires this setting, and refuses all impersonation while the setting is empty, which is the default. If a customer relies on this integration, set the pass phrase to a value unique to that installation and configure the integration to match. If nobody uses it, leave it empty.

The value is stored encrypted, so it cannot be read back out of the configuration once saved. Keep a record of it wherever the customer keeps their other installation secrets.

# What changes when you upgrade

Everyone is signed out once when the upgrade is installed and has to sign in again. Sessions created before the upgrade have no server-side record behind them, and accepting them anyway would leave exactly the weakness this change closes. Plan the upgrade outside working hours, or warn users to expect one extra sign-in.

# One database script has to be run first

Run sql/Update/AddMustReplaceSeededPassword.sql against the ContactManager database before starting the upgraded application. It adds a column the new version expects.

This is required because release builds ship with the database update mode set to PerformSafe, and that mode refuses to alter a table that already exists. The application therefore cannot add the column itself: without the script it fails to start, and every page returns an error reading "Cannot change table doCmsUser schema in PerformSafe update mode". If an upgrade produces that message, this script is what was missed — run it and restart the application.

Notes on the script:

  • It can be run more than once; a second run reports that there is nothing to do.
  • Installations running in Perform mode still need it for the second thing it does, below.
  • Users already flagged with Reset password are untouched, and keep working from the Outlook add-in and their integrations exactly as before.

# It also closes the default password on existing installations

The script does one more thing, and it is the part to warn a customer about. If the Administrator account still has the password a new installation creates, the script flags that account too. From then on the web application requires a new password, and the Outlook add-in and the API refuse that account until the password has been changed.

This is deliberate. Without it only brand-new installations would be protected, leaving the installations most likely to still be on the default password exactly as exposed as before — while the release notes would read as though the problem were solved everywhere.

What to check before upgrading. If the customer has an integration, a scheduled task or an Outlook installation signing in as Administrator with the original password, it will stop working the moment the upgrade is in place. Sign in to the web application, set a real Administrator password, and give the integration that password instead. Doing this before the upgrade avoids any interruption at all.

An Administrator password that has already been changed is left completely untouched, so an installation that was set up properly notices nothing.

Apart from the above, no data is affected — only the requirement to sign in again.

# Things to watch out for

  • Confirm the Outlook add-in signs back in. Every other client falls back to a login screen. If a customer uses the add-in, check it recovers cleanly after the shorter timeout, both after the upgrade and after three hours of inactivity.
  • The impersonation pass phrase is disabled by default. If a customer's Outlook integration stops working after the upgrade, this is the first thing to check.
  • Do not raise the session timeout without asking. It is the main control over how long a stolen cookie remains useful.
  • Remember me now does something. Users who never ticked it and relied on staying signed in across browser restarts will notice the change. Worth mentioning in release notes.
  • Sessions still end when the application restarts for reasons unrelated to this change, such as a deployment or an application pool recycle.
  • Run the database script before starting the upgraded application. It is the one preparation step this upgrade needs, and skipping it stops the application from starting at all. See What changes when you upgrade.
  • Set the Administrator password in the web application before configuring any integration against that account — on a new installation, and on an existing one that never changed it. Integrations are refused while the account still has its starting password, and the refusal looks like an ordinary wrong-password failure. On an upgrade this is the change most likely to interrupt a customer, so check it beforehand.
Last Updated: 9/9/2026, 11:36:43 AM