Sign-in and sessions – passwords, sign-in protection and session lifetime¶
This chapter describes the rules that apply when users sign in to nexxcite with a user name and password: the password policy, the protection against password guessing, two-factor authentication, how long a sign-in lasts, how users reset or change their password, and how an administrator ends the sessions of other users.
It is intended for administrators and operators. The settings described here are found in the
Admin Studio under System → Settings and – for a few operating values – in the configuration file
appsettings.json.
1. Sign-in and sessions at a glance¶
When a user signs in, nexxcite starts a session for them. The browser keeps it in a cookie; every tab of the same browser shares it. The session ends when the user signs out, when it expires, or when an administrator ends it.
The settings are grouped into categories in Admin Studio → System → Settings:
| Category | Content | Section |
|---|---|---|
| Login | Whether users may reset and change their password, external login registration | 7, and Authentication providers |
| Password policy | How a password has to look and how long it stays valid | 3 |
| Login protection | Two-factor authentication, temporary lock after failed attempts | 4, 5 |
| Login session | Session lifetime, "Remember me", re-check of signed-in users | 6 |
| The mail account nexxcite sends password reset links from | 7 |
Changes to these settings take effect with the next sign-in or the next request – no restart is needed.
The sign-in page¶
| Element | Shown when |
|---|---|
| "Username", "Password", "Sign in" | Always |
| "Remember me?" | "Offer "Remember me"" is on |
| "Forgot password?" | "Enable reset password" is on |
| "Sign in using …" | One button per enabled authentication provider |
A wrong user name and a wrong password lead to the same message, "Invalid login attempt." The page does not reveal whether a user name exists.
2. Signing in step by step¶
- The user enters user name and password.
- If the password is wrong, the attempt counts towards the temporary lock (section 4).
- If the user has set up two-factor authentication, nexxcite asks for a code (section 5).
- If the password has expired, the user has to set a new one first (see Users, section 6). This applies after the code of the second factor as well.
- If two-factor authentication is enforced and the user has not set it up yet, the setup opens.
- If all licenses are in use, the waiting screen appears (see Licensing).
3. Password policy¶
The password policy applies wherever a password is set: in the user editor, when a user changes or resets their password, and when an expired password is replaced. Every broken rule is reported, all at once.
| Setting | Default | Meaning |
|---|---|---|
| "Password minimum length" | 6 | Minimum number of characters |
| "Password different characters" | 1 | Minimum number of different characters. 1 means the rule is not applied. |
| "Password requires a digit" | On | At least one digit |
| "Password requires a lower case letter" | On | At least one lower case letter |
| "Password requires an upper case letter" | On | At least one upper case letter |
| "Password requires a special character" | On | At least one character that is neither a letter nor a digit |
| "Password expires after (days)" | 0 | How long a password stays valid after the user changed it. Only for users whose password expires; 0 means such a password has to be changed once and then stays valid. |
Example: With minimum length 10 and 5 different characters, Aaaaaaaaa1! is rejected (only four
different characters: A, a, 1, !), Garden-2026 is accepted.
A changed policy applies to the next password that is set. Existing passwords stay valid, even if they do not meet the new rules.
4. Protection against password guessing¶
nexxcite protects the sign-in in two independent ways.
Summary¶
- After 5 wrong passwords in a row, an account is locked for 15 minutes. The lock ends on its own.
- Independently of the account, one address may make at most 20 requests to the sign-in pages per 60 seconds.
- The first protects a single account; the second also stops one common password from being tried against many user names.
Temporary lock of an account¶
| Setting | Default | Meaning |
|---|---|---|
| "Lock account after failed attempts" | 5 | Wrong passwords in a row that lock the account. 0 switches the lock off. |
| "Lock account for (minutes)" | 15 | How long the lock lasts. 0 or less uses 15 minutes. |
- Wrong two-factor codes and wrong current passwords on the page for an expired password count as well.
- A successful sign-in sets the counter back to zero.
- During the lock, every sign-in attempt – even with the correct password – leads to the page "This account is locked", which names the duration of the lock. The page does not say which account is locked.
- The lock cannot be lifted early. A permanent lock set by an administrator is a different thing, see Users, section 5.
Example: With the defaults, a user mistypes their password five times between 9:00 and 9:02. The account is locked until about 9:17. At 9:10 the correct password is refused as well; at 9:17 it works again.
Limit per caller¶
The limit counts requests per remote address, whatever user name is entered. It applies to the sign-in page, the two-factor and recovery code pages, "Forgot password?", the page for setting a new password and both pages for changing a password. Opening one of these pages counts as a request, too.
When the limit is exceeded, the server answers with the HTTP status 429 (Too Many Requests) until the window is over; the browser shows an error page.
The limit is set in appsettings.json, see section 10.
For operators
- Behind a reverse proxy, nexxcite sees the address of the proxy unless the section
ForwardedHeadersis configured. All users then share one limit, and 20 requests per minute can be reached quickly. ConfigureForwardedHeaders, or raise the limit. - Many users behind one address (for example one office behind one gateway) share a limit as
well. Raise
LoginProtection:MaxAttemptsPerWindowaccordingly.
5. Two-factor authentication¶
With two-factor authentication, users enter a six-digit code from an authenticator app on their phone (for example Microsoft Authenticator or Google Authenticator) in addition to their password.
Modes¶
The setting "Two-factor authentication" (category "Login protection") has three modes:
| Mode | Effect |
|---|---|
| "Disabled" (default) | Nobody is asked for a code – also users who have already set up an app. |
| "Optional" | Every user decides for themselves in the user menu. Users who have set it up are asked at every sign-in. |
| "Enforced" | Every user has to set up an app. A user who has not done so is taken to the setup directly after signing in and cannot reach anything else until it is finished. |
The mode affects the internal sign-in only. Users who sign in through an external identity provider are never asked by nexxcite, and neither are applications that use the REST API.
Before switching to "Enforced", tell your users: at their next sign-in they need their phone with an authenticator app.
Setting up an app¶
The user opens "Two-factor authentication" in the user menu (only shown when the mode is not "Disabled") and clicks "Set up an authenticator app". Under "Enforced", the setup opens on its own.
- Scan the QR code with the app, or type in the key shown below it.
- Enter the code the app shows under "Verification code" and click "Turn on two-factor authentication".
- nexxcite shows ten recovery codes – only this one time. Each signs the user in once without the app. Save them and click "I have saved them, continue".
The app shows the account under the "Company Name" of the global settings, or under "nexxcite" if none is set.
Signing in with a code¶
After the password, the page asks for the "Authenticator code". Codes change about every 30 seconds; if a code is refused, the clock of the phone may be wrong.
"Don't ask again on this device for N days" skips the code on this browser for the number of days set in "Remember a device for (days)" (default 14). With 0, the checkbox is not offered.
Without the phone, the user signs in with one of their recovery codes on the page "Use a recovery code".
What users can do afterwards¶
In the user menu under "Two-factor authentication":
| Action | Available |
|---|---|
| See how many recovery codes are left | Always |
| "Generate new recovery codes" – replaces all previous ones | Always |
| "Set up a new authenticator app" – for a new phone | Always |
| "Turn two-factor authentication off" | Only in mode "Optional" |
A user who has lost both their phone and their recovery codes needs an administrator, who resets the second factor with "Reset 2FA" (see Users, section 8).
6. How long a sign-in lasts¶
Summary¶
- By default, a sign-in ends after 8 hours without a request to the server.
- With "Remember me?", it survives closing the browser and lasts 14 days.
- An optional cap ends every session after a fixed number of hours, however active the user is.
- Changes to a user – above all a new password – reach sessions that are already open within 30 minutes.
How it works¶
Three things bound a session:
| What | Setting | Ends the session |
|---|---|---|
| Lifetime | "Session lifetime (minutes)", "Extend the session while it is used" | When the lifetime has run out |
| Cap | "Sign out at the latest after (hours)" | When the cap is reached, however active the user is |
| Re-check | "Re-check the user every (minutes)" | When the user was deleted or their password changed since the sign-in |
"Extend the session while it is used" decides what the lifetime means:
- On (default): the lifetime is an idle timeout. Requests to the server push the end out again. Without a cap, a user who works every day never has to sign in again.
- Off: the lifetime is a fixed term from the sign-in.
If both a fixed term and a cap apply, the earlier one ends the session.
Example: Lifetime 480 minutes, extension on, cap 12 hours. A user signs in at 7:00 and works all day. The extension would keep the session alive, but the cap ends it at 19:00. If the user stops working at 11:00 instead, the session ends at about 19:00 as well (11:00 plus 8 hours).
What counts as a request¶
nexxcite checks and extends the session when the browser sends a request to the server: loading or reloading a page, opening nexxcite in a new tab, reconnecting after an interruption. Working inside a page that is already open runs over a permanent connection and is not such a request.
As a consequence:
- An open tab is not closed at the moment the session expires. The expiry is noticed at the next page load or reconnect; the user then sees the sign-in page.
- In our assessment, a user who works for many hours in one tab without ever reloading can find themselves signed out at the next page load, although they were active.
"Remember me"¶
Without the checkbox, the session ends at the latest when the browser is closed. With it, the session also survives closing the browser and lasts "Remember me" lifetime (days). The cap applies to such a session as well. With "Offer "Remember me"" off, the checkbox is not shown, and every session ends with the browser.
Server restarts¶
The session cookie is encrypted with keys of the application. Unless a shared key directory is
configured with DataProtection:KeyRingPath, these keys are created anew at every start: a restart
then signs out every user, whatever the settings above say. Installations with several servers must
configure the directory; they do not start without it.
7. Forgotten and expired passwords¶
There are three ways for users to set a new password themselves.
| Way | Where | Requires |
|---|---|---|
| Forgot password | "Forgot password?" on the sign-in page | "Enable reset password" on, a mail account under "Mail", a mail address in the user's profile |
| Change password | "Change password" in the user menu | "Enable change password" on, the current password |
| Expired password | Automatically after signing in with an expired password – also after the second factor | User name and current password; works with "Enable change password" off as well |
All three apply the password policy and restart the expiry period of the user (see Users, section 6).
Forgot password¶
- The user enters their user name and clicks "Send the link".
- The page always answers "Check your mail" – whether or not the account exists. This way, nobody can find out which user names exist.
- The mail goes to the address in the user's profile, never to an address entered in the form.
- The link opens "Set a new password". It works once and for a limited time (in the current version about one day). A used or expired link shows "This link cannot be used."
A user who signs in only through an external provider receives a mail that names the provider instead of a link.
If "Enable reset password" is on but no mail can be sent, the page says so instead of offering the form: "This installation cannot send mail yet, so a reset link cannot be sent. Please contact your administrator." nexxcite also writes a warning to its console output at start-up.
The mail account¶
The mail account is set in Admin Studio → System → Settings, category "Mail":
| Setting | Meaning |
|---|---|
| "Mail provider" | "SMTP" or "Exchange Online". Empty: nexxcite sends no mails of its own. |
| "Mail account" | The credentials of the account – SMTP credentials for SMTP, Exchange Online credentials for Exchange Online |
| "Sender address" | Required for SMTP. For Exchange Online, the mailbox of the credentials is used when it is empty. |
| "Sender name" | Optional, shown next to the address |
Change password¶
The page asks for the "Current password", so that a session somebody left open is not enough to take an account over. After the change:
- all other sessions of the user end (open tabs at the latest after the re-check interval),
- the user receives a notice by mail, if their profile has a mail address.
For users who sign in only externally, the menu entry is not shown.
With "Enable change password" off, users cannot change their password on their own – neither from the user menu nor from the sign-in page. The page for an expired password is the one exception: that change is required by the installation, not chosen by the user.
8. Ending the sessions of other users¶
Admin Studio → Access → Authenticated Users lists every user who is signed in, with the number of their sessions and the time of the sign-in. Tags show "API" for users with API sessions and "License free" for users who do not take a license.
Select a user and click "User Sessions" to see each session:
| Column | Content |
|---|---|
| Type | "Browser" or "API"; "Your session" marks your own |
| Signed in at | Start of the session; for API sessions also the expiry of the token |
| IP address, Client, Server | Where the session comes from and which server it runs on |
| Button | Effect |
|---|---|
| "Sign out" (browser session) | The browser of this session is signed out immediately |
| "Revoke" (API session) | The access token stops working immediately, on every server |
| "Sign out user" | Ends all sessions of the user |
Ending a session releases its license (see Licensing). It does not prevent the user from signing in again – lock the account for that (see Users, section 5).
| Permission | Allows |
|---|---|
| "Open Authenticated Users Manager" | Seeing the list |
| "View User Sessions" | The button "User Sessions" |
| "Sign Out User Sessions" | Ending sessions |
With several servers: a browser session that runs on another server than yours is marked "Runs on another server instance and can only be removed from this list, not signed out from here." Removing it releases the license, but the browser keeps working until it reloads. Open the Admin Studio on that server to sign the session out directly.
9. Timing at a glance¶
| Situation | Effect | Remark |
|---|---|---|
| A setting in this chapter is changed | From the next sign-in or request | No restart needed |
| A user has no request to the server for the session lifetime | The session ends | Default 8 hours; only with "Extend the session while it is used" on |
| The cap is reached | The session ends | Off by default |
| The browser is closed | The session ends | Unless "Remember me?" was ticked |
| An administrator sets a new password, or the user changes it | Other sessions of the user end | Open tabs at the latest after the re-check interval (default 30 minutes) |
| An administrator locks the user | New sign-ins are refused; open browser sessions end at their next re-check, API tokens stop working immediately | Default 30 minutes; end browser sessions sooner under User Sessions |
| An administrator signs a session out | Immediately | Only for sessions on the same server |
| Roles or permissions of a user change | See Roles and permissions, section 9 | – |
| The server restarts | All users are signed out | Unless DataProtection:KeyRingPath is configured |
| A user mistypes the password too often | Account locked for 15 minutes | Default values |
10. Settings for operation¶
Global settings¶
All settings of sections 3 to 7 with their defaults:
| Setting | Category | Default |
|---|---|---|
| "Enable external login registration" | Login | On |
| "Enable reset password" | Login | On |
| "Enable change password" | Login | On |
| "Session lifetime (minutes)" | Login session | 480 (0 uses 480) |
| "Extend the session while it is used" | Login session | On |
| "Sign out at the latest after (hours)" | Login session | 0 = no cap |
| "Offer "Remember me"" | Login session | On |
| "Remember me" lifetime (days) | Login session | 14 (0 uses 14) |
| "Re-check the user every (minutes)" | Login session | 30 (0 uses 30) |
| "Two-factor authentication" | Login protection | Disabled |
| "Lock account after failed attempts" | Login protection | 5 (0 = no lock) |
| "Lock account for (minutes)" | Login protection | 15 |
| "Remember a device for (days)" | Login protection | 14 (0 = checkbox not offered) |
| "Record sign in attempts" | Login protection | Off – see Authentication log |
| "Keep sign in attempts for (days)" | Login protection | 90 (0 = keep every entry) |
| Password policy | Password policy | see section 3 |
appsettings.json¶
The rules for users are set in the global settings, not here. The following values concern the operation of the server.
| Setting | Default | Meaning |
|---|---|---|
LoginProtection:MaxAttemptsPerWindow |
20 | Requests to the sign-in pages one address may make per window |
LoginProtection:WindowInSeconds |
60 | Length of the window |
ForwardedHeaders:Enabled |
false | Trusts the client address forwarded by a reverse proxy – needed for a meaningful limit per caller behind a proxy |
DataProtection:KeyRingPath |
empty | Directory for the keys the session cookie is encrypted with. Empty: keys live in the process, a restart signs everybody out. Required with several servers. |
11. Limitations¶
- An open browser tab notices an expired session only at the next page load or reconnect (section 6).
- Locking an account ends open browser sessions only at their next re-check (default 30 minutes).
- A browser session on another server can only be removed from the list, not signed out (section 8).
- The temporary lock cannot be lifted early by an administrator.
- Two-factor authentication supports authenticator apps only – no codes by mail or text message.
- The limit per caller counts addresses, not users. Behind a proxy without
ForwardedHeaders, all users share one limit.
12. Frequently asked questions¶
Users are signed out after every update of nexxcite. Why?
Most likely no DataProtection:KeyRingPath is configured. The keys of the session cookies are then
lost at every restart (section 6).
Can I make sure that nobody stays signed in for more than one working day? Yes. Set "Sign out at the latest after (hours)", for example to 10. It also caps "Remember me" sessions.
I switched two-factor authentication to "Disabled". Are users who set up an app still asked? No. "Disabled" applies to everybody. Their app stays set up and is used again when you switch to "Optional" or "Enforced".
A user is locked after wrong attempts. Can I unlock them? No. The temporary lock ends on its own after "Lock account for (minutes)". Setting a new password does not end it.
Can users reset their password without a mail account? No. Without a configured mail account, the reset is not available, and the page says so. An administrator can set a new password in the user editor.
Does "Remember me" bypass two-factor authentication? No. It keeps the session alive. Skipping the code on a device is the separate checkbox "Don't ask again on this device".