> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/19.latest/develop-with-umbraco/configuration/securitysettings.md). # Security Settings Information on the security settings section The options in the security section allow you to configure all things security, whether to keep users logged in, password rules and more. A full configuration with all default values can be seen here: {% code title="appsettings.json" %} ```json "Umbraco": { "CMS": { "Security": { "KeepUserLoggedIn": false, "HideDisabledUsersInBackOffice": false, "AllowPasswordReset": true, "AuthCookieName": "UMB_UCONTEXT", "AuthCookieDomain": "", "AuthCookieSameSite": "Strict", "UsernameIsEmail": true, "MemberRequireUniqueEmail": true, "AllowedUserNameCharacters": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._@+\\", "UserBypassTwoFactorForExternalLogins": true, "MemberBypassTwoFactorForExternalLogins": true, "BackOfficeHost": "http://your-domain.com", "CallbackPathName": "/umbraco", "UserPassword": { "RequiredLength": 10, "RequireNonLetterOrDigit": false, "RequireDigit": false, "RequireLowercase": false, "RequireUppercase": false, "HashAlgorithmType": "PBKDF2.ASPNETCORE.V3", "MaxFailedAccessAttemptsBeforeLockout": 5 }, "MemberPassword": { "RequiredLength": 10, "RequireNonLetterOrDigit": false, "RequireDigit": false, "RequireLowercase": false, "RequireUppercase": false, "HashAlgorithmType": "PBKDF2.ASPNETCORE.V3", "MaxFailedAccessAttemptsBeforeLockout": 5 }, "UserDefaultLockoutTimeInMinutes": 43200, "MemberDefaultLockoutTimeInMinutes": 43200, "AllowConcurrentLogins": false, "UserAllowConcurrentLogins": null, "MemberAllowConcurrentLogins": null, "UserDefaultFailedLoginDurationInMilliseconds": 1000, "UserMinimumFailedLoginDurationInMilliseconds": 250, "PasswordResetEmailExpiry": "01:00:00", "UserInviteEmailExpiry": "3.00:00:00" } } } ``` {% endcode %} ## Root level settings At the root level of security you can configure the following ### Keep user logged in When set to false a user will be logged out after a specific amount of time has passed with no activity. You can specify this time span in the [global settings](/umbraco-cms/19.latest/develop-with-umbraco/configuration/globalsettings.md) with the `TimeOut` key. ### Hide disabled users in backoffice When this is set to "true" it's not possible to see disabled users. This means it's not possible to re-enable their access to the backoffice again. It also means you can't create an identical username if the user was disabled by a mistake. ### Allow password reset This feature allows users to reset their passwords if they have forgotten them. By default, this is enabled. It can be disabled at both the UI and API level by setting this value to "false". ### Auth cookie name The name of the authentication cookie that Umbraco sets in the browser when a backoffice user logs in. The default is `UMB_UCONTEXT`. The authentication cookie holds the backoffice session. The browser sends it with every request the backoffice makes to the server. Set this to a unique value per site when you run more than one Umbraco site on the same hostname. This includes sites running on `localhost` during local development. See [Run more than one site on the same hostname](#run-more-than-one-site-on-the-same-hostname) for an example. ### Auth cookie domain The authentication cookie which is set in the browser when a backoffice user logs in is automatically set to the current domain. ### Auth cookie SameSite Sets the `SameSite` attribute of the authentication cookie. Valid values are "Strict" (default), "Lax", "None", and "Unspecified". Keep the default in production. The `SameSite` attribute stops cross-site requests from carrying the authentication cookie. The Management API has no antiforgery tokens, so the attribute is its protection against cross-site request forgery. Only set the value to "None" when the backoffice runs on a different origin than the Umbraco server. For example, when you develop against a local dev server configured as the [BackOffice Host](#backoffice-host). Browsers accept a `SameSite=None` cookie only with the `Secure` attribute, which requires HTTPS. If a proxy terminates HTTPS in front of Umbraco, make sure `UseHttps` is `true` in the [global settings](/umbraco-cms/19.latest/develop-with-umbraco/configuration/globalsettings.md). Umbraco logs a warning at startup when the value is "None" outside the `Development` environment, or while `UseHttps` is `false`. Umbraco does not replace an unrecognized value with the default. It reports a configuration error at startup, and the site does not start. ### Username is email This setting specifies whether the username and email address are separate fields in the backoffice editor. When set to "false", you can specify an email address and username, only the username can be used to log on. When set to "true" (the default value) the username is hidden and always the same as the email address. ### Member require unique email By default Umbraco will not allow creation of more than one member account with the same email address. If you wish to allow this, set this value to `false`. ### Allowed user name characters Defines the allowed characters for a username. ### User bypass two-factor for external logins Key: `UserBypassTwoFactorForExternalLogins` Type: `bool` (default: `true`) When `true`, a backoffice user who signs in with an [external login provider](/umbraco-cms/19.latest/run-in-production/security/external-login-providers.md) is not asked for Umbraco's [two-factor authentication](/umbraco-cms/19.latest/run-in-production/security/two-factor-authentication.md). Umbraco relies on the external provider instead, including any two-factor check the provider enforces. Set it to `false` to also ask users who have two-factor authentication enabled in Umbraco for their code after an external login. ### Member bypass two-factor for external logins Key: `MemberBypassTwoFactorForExternalLogins` Type: `bool` (default: `true`) The same setting for members who sign in to the website with an external login provider. Members who sign in through the Delivery API with an external login provider always skip Umbraco's two-factor authentication, regardless of this setting. ### BackOffice Host Use this setting to override the Backoffice host URL. This is useful when the Backoffice client runs from a different origin than the Umbraco server. For example, in proxied, cloud-hosted setups, or when developing locally using Vite or another dev server. When the Backoffice client runs on a separate host, also configure the [callback path name](#callback-path-name) and the [auth cookie SameSite](#auth-cookie-samesite) setting. The following example runs the client on a local Vite dev server: {% code title="appsettings.Development.json" %} ```json "Umbraco": { "CMS": { "Security": { "BackOfficeHost": "http://localhost:5173", "CallbackPathName": "/", "AuthCookieSameSite": "None" } } } ``` {% endcode %} ### Callback path name Key: `CallbackPathName` Type: `string` The path where Umbraco serves the Backoffice client. The default is `/umbraco`. Umbraco sends users to this path after they log in, unless they were on their way to another page in the Backoffice. Umbraco also derives the logout path (`/umbraco/logout`) and the error path (`/umbraco/error`) from it. When you configure a [BackOffice Host](#backoffice-host), Umbraco appends the path to that host. Change the value when the client runs at another path on that host. For example, set it to `/` when a dev server serves the client at its root. {% hint style="info" %} `CallbackPathName` replaces the `AuthorizeCallbackPathName`, `AuthorizeCallbackLogoutPathName`, and `AuthorizeCallbackErrorPathName` settings from earlier versions. The old settings were full paths to individual routes, such as the OAuth callback at `/umbraco/oauth_complete`. `CallbackPathName` is the path of the Backoffice itself, so set the new value instead of renaming the old keys. Umbraco ignores the old keys and logs a warning at startup while they are present. {% endhint %} ### User default lockout time Use this setting to configure how long time a User is locked out of the Umbraco backoffice when a lockout occurs. The setting accepts an integer which defines the lockout in minutes. The default lockout time for users is 30 days (43200 minutes). ### Member default lockout time Use this setting to configure how long time a Member is locked out of the Umbraco website when a lockout occurs. The setting accepts an integer which defines the lockout in minutes. The default lockout time for members is 30 days (43200 minutes). ### Allow concurrent logins Key: `AllowConcurrentLogins` Type: `bool` (default: `false`) When set to `false`, each account is limited to one active session at a time. A new login invalidates any existing session for the same account. This applies to both backoffice users and members unless overridden by the settings below. ### User allow concurrent logins Key: `UserAllowConcurrentLogins` Type: `bool?` (default: `null`) Controls concurrent login behavior for backoffice users only. When `null`, the value falls back to `AllowConcurrentLogins`. Set to `true` or `false` to override the global setting for backoffice users. ### Member allow concurrent logins Key: `MemberAllowConcurrentLogins` Type: `bool?` (default: `null`) Controls concurrent login behavior for members only. When `null`, the value falls back to `AllowConcurrentLogins`. Set to `true` or `false` to override the global setting for members. #### Configuration examples Allow concurrent logins for members but not backoffice users: {% code title="appsettings.json" %} ```json "Security": { "AllowConcurrentLogins": false, "MemberAllowConcurrentLogins": true } ``` {% endcode %} Disable concurrent logins for backoffice users while keeping them enabled globally: {% code title="appsettings.json" %} ```json "Security": { "AllowConcurrentLogins": true, "UserAllowConcurrentLogins": false } ``` {% endcode %} ### User login duration Umbraco provides protection from user enumeration attacks looking to identify valid backoffice login accounts. It does this by attempting to equalize the time taken for successful and failed logins. The `UserDefaultFailedLoginDurationInMilliseconds` can be used to provide a more realistic expected time for a successful login if the default isn't appropriate. This will be used before actual successful logins are detected. `UserMinimumFailedLoginDurationInMilliseconds` provides a minimum duration for a failed login. ### Password reset email expiry Defines the expiry for the password reset email. When the email is sent, an `Expiry` header will be added that uses the value configured here. The default value is 1 hour. ### User invite email expiry Defines the expiry for the user invite email. When the email is sent, an `Expiry` header will be added that uses the value configured here. The default value is 3 days. ## User password settings This section lets you define the password rules for users. ### Required length Specifies the minimum length a user password is allowed to be. ### Require non letter or digit Requires a users password to contain at least one character which is not a letter or a digit if enabled. ### Require digit Requires a users password to contain at least one digit if enabled. ### Require lowercase Requires a users password to contain at least one lowercase letter if enabled. ### Require uppercase Requires a users password to contain at least one uppercase letter if enabled. ### Max failed access attempts before lockout Specifies the max amount of failed password attempts is allowed before the user is locked out of the site. ### Hash algorithm type Allows you to specify what hashing algorithm should be used to store the users password. Options are: * `"PBKDF2.ASPNETCORE.V3"` * `"PBKDF2.ASPNETCORE.V2"` * `"HMACSHA256"` * `"HMACSHA1"` ## Member password settings This section allows you to define the password rules for members. This section is identical to the one for users. ## Run more than one site on the same hostname Browsers scope cookies to the hostname and ignore the port number. Two sites running on `https://localhost:44301` and `https://localhost:44302` share the same cookies. With the default settings, both sites use the `UMB_UCONTEXT` authentication cookie. Signing in to one site then signs you out of the other. Configure a unique [auth cookie name](#auth-cookie-name) for each site to stay signed in to both sites at the same time: {% code title="appsettings.json" %} ```json "Umbraco": { "CMS": { "Security": { "AuthCookieName": "UMB_UCONTEXT_SITEA" } } } ``` {% endcode %} The value must be valid in a cookie name, so avoid spaces and the characters `=`, `;`, and `,`. As an alternative to configuring cookie names, give each site its own hostname. For example, map `sitea.localtest.me` and `siteb.localtest.me` to your local sites. {% hint style="info" %} Umbraco 17 and 18 also stored the backoffice tokens in cookies, configured in a `BackOfficeTokenCookie` section. Umbraco 19 authenticates the backoffice with the authentication cookie alone, and removes the token cookies along with that section. Umbraco ignores the section and logs a warning at startup while it is present. Replace `BackOfficeTokenCookie:SiteName` with a unique `AuthCookieName`, and `BackOfficeTokenCookie:SameSite` with `AuthCookieSameSite`. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.umbraco.com/umbraco-cms/19.latest/develop-with-umbraco/configuration/securitysettings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.