Tenants

The named issuer used to sign tokens. Typically a fully-qualified domain name.

The Theme associated with this Tenant; determines which templates to render for interactive work-flows.

The form that will be used in the FusionAuth UI for adding and editing users.

This feature is only available in paid plans. Please visit our pricing page to learn more.

When true, FusionAuth will handle username collisions.

This feature is only available in paid plans. Please visit our pricing page to learn more.

The maximum number of digits to use when building a unique suffix for a username. A number will be randomly selected and may be 1 or more digits up to this configured value. The value of this field must be greater than or equal to 3 and less than or equal to 10.

A single character to use as a separator from the requested username and a unique suffix that is added when a duplicate username is detected. This value can be a single non alphanumeric ASCII character.

The hostname of the SMTP server. This will be provided by your SMTP provider.

The port of the SMTP server. This will be provided by your SMTP provider. Ports 25, 465 and 587 are the well known ports used by SMTP, it is possible your provider will utilize a different port.

In most cases you will be using TLS to connect to your SMTP server, and the port will generally be 587 or 465.

The username of the outgoing SMTP mail server authentication.

When enabled, you may modify the SMTP password, when the Password field is not displayed the current password will not be modified.

The new password to use for the outgoing SMTP mail server authentication. This field is only required when Change password is checked.

When using duplicating Tenants, the SMTP password is not copied. You will have to enter this manually before sending emails.

The security type when using an SSL connection to the SMTP server. This value should be provided by your SMTP provider.

Generally speaking, if using port 25 you will select None, if using port of 465 you will select SSL and if using port 587 you will select TLS. It is possible your provider will be different, follow your providers instruction.

• None
• SSL
• TLS

The default email address that emails will be sent from when a from address is not provided on an individual email template. This is the address part email address (i.e. Jared Dunn jared@piedpiper.com).

The default From Name used in sending emails when a from name is not provided on an individual email template. This is the display name part of the email address ( i.e. Jared Dunn jared@piedpiper.com).

One or more line separated SMTP headers to be added to each outgoing email. The header name and value should be separated by an equals sign. ( i.e. X-SES-CONFIGURATION-SET=Value).

When enabled, users will be required to verify their email address.

When enabled, this allows a user’s email address to be verified as a result of completing a similar based email workflow such as change password.

When enabled, users will be required to verify their email address upon update.

The email template to use when accounts are created to verify the User’s email address.

Required when the Verify email toggle is enabled.

The email template to use when notifying a user that email address has been verified.

The process by which the user will verify their email address. Using the “Form Field” method works only when the Unverified behavior is Gated.

The way a user is handled during the login process when they do not have a verified email address.

When enabled, the user is allowed to change their email address when they are gated because they haven’t verified their email address.

When enabled, users who have not verified their email address after a configurable duration since being created will be permanently deleted.

The duration since creation that a user must exist before being deleted for having an unverified email address.

Required when the Delete unverified users toggle is enabled.

The email template to use when notifying a user that their email address has been updated.

Note: An Enterprise plan is required to utilize this feature.

The email template to use when notifying a user that email address has been verified.

Note: An Enterprise plan is required to utilize this feature.

The email template to use for the forgot password workflow.

The email template to use when notifying a user that another user has attempted to register an account with the same username or email address as they have. If user Richard has an email richard@piedpiper.com and a new user tries to register with the email address richard@piedpiper.com, then user Richard will be notified.

Note: An Enterprise plan is required to utilize this feature.

The email template to use when notifying a user that another user has attempted to change their own email or username to a value in-use by the user.

Note: An Enterprise plan is required to utilize Login Id duplicate on update.

The email template to use when notifying a user that a new device was used to login.

Note: An Enterprise plan is required to utilize Login with new device.

The email template to use when notifying a user that a login occurred and it was determined to be of interest or suspect due to the location, IP address or other factors.

Note: An Enterprise plan is required to utilize Suspicious login.

The email template to use when notifying a user that their password has been successfully updated using the reset workflow.

Note: An Enterprise plan is required to utilize Password reset success.

The email template to use when notifying a user that their password has been successfully updated. This is different from Password reset success in that this event occurs outside of the reset workflow.

Note: An Enterprise plan is required to utilize Password update.

The template to use to send the link for passwordless login requests.

The email template to use when accounts are created and the user needs to setup their password.

The email template to use when notifying a user that a new two-factor method has been successfully added.

Note: An Enterprise plan is required to utilize Two-factor method added.

The email template to use when notifying a user that a previously configured two-factor method has been successfully removed.

Note: An Enterprise plan is required to utilize Two-factor method removed.

When enabled, you may model parent-child user relationships, and observe parental approval and age validation on user creation.

The maximum age a user can be to be considered a child.

Required when the Enabled toggle is enabled.

The minimum age a user must be to create a family.

Required when the Enabled toggle is enabled.

When enabled, allow children to register themselves without requiring a parent to create their account for them.

The email template used when children are not able to register themselves and they are asking their parent to create them an account.

The email template used when a parent needs to confirm a child account before it is activated as part of their family.

The email template used when a child is requesting that their parent create an account (because it is not created automatically).

When enabled, child users must provide their parent’s email address during the registration process.

When enabled, child user accounts that have not been verified by a parent after a configured period will be automatically deleted.

The number of days before a child account that has not yet been verified by a parent is automatically deleted.

Required when the Delete unverified children toggle is enabled.

When set to Enabled, a two-factor challenge will be required during login when a user has configured one or more two-factor methods. When set to Disabled, even when a user has one or more two-factor methods configured, a two-factor challenge will not be required during login. When set to Required, a two-factor challenge will be required during login. If a user does not have configured two-factor methods, they will not be able to log in.

Supported values include:

• Enabled. A challenge will be required during login when an eligible method is available.
• Disabled. A challenge will not be required during login.
• Required. A challenge will be required during login.   Available since 1.42.0

When enabled, users may use an authenticator application to complete a multi-factor authentication request.

When enabled, users may use an email address to complete a multi-factor authentication request.

The email template to use when a multi-factor authentication request is sent to the User’s email address.

Required when the Enabled toggle is enabled.

When enabled, users may use a mobile phone number to complete a multi-factor authentication request.

The Messenger used to deliver the template.

Required when the Enabled toggle is enabled.

The SMS template to use when a multi-factor authentication request is sent to the User’s mobile phone number.

Required when the Enabled toggle is enabled.

The length of time an SSO session can be inactive before it is closed.

The URL the user is redirected to upon logout.

The lambda that will be called to populate the JWT during a client credentials grant.

The length of time the issued token (access token and Id token) is valid. JWT tokens are typically short lived.

The key used to sign the access token JWT.

The key used to sign the Id token JWT.

The length of time the refresh token is valid. Refresh tokens are typically long lived.

The Refresh token expiration may be either a fixed window, sliding window, or sliding window with a maximum lifetime. By default, the expiration of a refresh token is a fixed length of time from when it was originally issued. With a sliding window expiration, the expiration is calculated from the last time the refresh token was used. However with a sliding window with a maximum lifetime, the expiration is calculated from the last time the refresh token was used until a maximum lifetime value is reached.

For instance, consider the following scenarios given the above configuration. If a refresh token is issued at 1:00pm and has a duration of 60 minutes, if the expiration is fixed, the token will expire at 2:00pm. If, instead, the expiration is a sliding window, then if the refresh token is used at 1:55pm, it would then expire at 2:55pm. If it were then used at 2:50pm, it would expire at 3:50 pm. Lastly if the expiration is a sliding window with a maximum lifetime of 24 hours, then the token could be refreshed every hour (in the same sliding manner as outlined above) up to 23 times. For instance, if a token was issued at 1:55pm on Monday and refreshed every hour, the 23th refresh it would be the last valid refresh request (12:55pm Tuesday would be the last valid refresh event).

The Refresh token usage may be reusable or one time use. By default, a token is reusable and the token does not change after it was issued. With a one time use token, the token value will be changed each time the token is used to refresh a JWT. This means the client must store the new value after each use.

The event or events that will cause refresh tokens to be revoked.

The user action must be ‘time-based’ and must have ‘prevent login’ enabled. This actions is applied after multiple failed login attempts.

The number of failed attempts allowed during the specified time period before the selected action is applied.

The window of time in seconds for which the failed authentication attempts are counted. If no further failed attempts occur the failure count will be reset after this time period starting at the time of the last failed login.

The length of time the selected action is applied to the user before the action expires at which point the user will be allowed to attempt log in again.

The time unit the Action duration is measured in.

Indicates whether you want the user to be able to self-service unlock their account prior to the action duration by completing a password reset workflow.

Indicates you would like to email the user when the user’s account is locked due to this action being taken. This requires the User Action specified by the User action to also be configured for email. If the User Action is not configured to be able to email the user, this configuration will be ignored.

The email template configuration will be in the User Action.

When enabled, users’ login Id and password will be checked against public breached password databases on user creation, password change, and (optionally) on login. Purchase of a FusionAuth plan is required to enable this feature.

The login Id and password match constraints to qualify as a breach match.

The action to perform during login for breach detection. Performing breach detection during login may increase the time it takes to complete authentication.

The minimum length a password may be to qualify as a valid password.

The maximum length a password may be to qualify as a valid password.

When enabled, force the user to use at least one uppercase and one lowercase character.

When enabled, force the user to use at least one non-alphanumeric character.

When enabled, force the user to use at least one number.

When enabled, users must wait a configurable duration before changing their password after the previous change.

The minimum age (in seconds) users must wait before changing their password after the previous change.

Required when the Minimum age toggle is enabled.

When enabled, user passwords will expire after a configurable duration, at which point the user will be forced to change their password on login.

The duration (in days) the password expire after since the previous change.

Required when the Expiration toggle is enabled.

When enabled, prevent users from using a configurable number of their previous passwords.

The number of previous password to retain, to prevent users from password reuse.

Required when the Reject previous passwords toggle is enabled.

When enabled the user’s password will be validated during login. If the password does not meet the currently configured validation rules the user will be required to change their password.

The password encryption scheme used when creating new users and when changing a password.

A non-zero number that provides an iteration count to the hashing scheme. A higher number will make the password hash more difficult to reverse engineer but will take more CPU time during login. Be careful as a high factor may cause logins to become very slow.

When enabled the user’s password hash will be modified if it does not match the configured values during next login.

When enabled, WebAuthn is available for the tenant, and additional configuration options will be available.

The Relying Party Id is used to scope WebAuthn passkeys to the site where they were registered. As part of WebAuthn’s security requirements, this value must be either:

• The browser request origin’s effective domain
• A registrable domain suffix of the effective domain

For example, if the login page is at auth.piedpiper.com, then the following are valid Relying Party Ids:

• auth.piedpiper.com - matches the effective domain
• piedpiper.com - a registrable suffix of the effective domain

But the following values are not valid:

• m.auth.piedpiper.com - a subdomain of the effective domain
• com - this is a suffix of the effective domain but not registrable

It is important that this is configured according to the URL that a user would see in their browser while on the FusionAuth login page. See the WebAuthn Admin Guide for more details on how to select the appropriate value.

Leaving this value empty will cause the WebAuthn JavaScript API to use the browser’s current request origin.

The Relying Party name for WebAuthn ceremonies. This value may be displayed to the user by the browser or OS during WebAuthn registration and authentication ceremonies.

If this value is left blank, the Issuer value will be used.

Enable debug to create an event log to assist you in debugging integration errors.

When enabled, the WebAuthn bootstrap workflow can be used to authenticate users via WebAuthn from new or repeat devices.

The availability of the bootstrap workflow can be overridden at the application level on the WebAuthn Tab of the Application settings.

The authenticator attachment preference for the bootstrap workflow on this tenant. This value controls the attachment requirement for authenticators during the bootstrap workflow registration ceremony. Authenticators that do not meet the requirement are not considered during passkey registration. The possible values are:

• Any - any authenticator attachment is allowed
• Platform only - only authenticators integrated with the client device are allowed
• Cross-platform only - only authenticators that are usable across multiple client devices are allowed

The recommended value for the bootstrap workflow is Any when the option is available.

Note: An Enterprise plan is required to utilize WebAuthn cross-platform authenticators.

The user verification requirement for the bootstrap workflow on this tenant. This value controls whether user verification is required for registration and authentication ceremonies during the bootstrap workflow. Authenticators that do not meet the requirement are not considered during passkey registration or authentication. The possible values are:

• Required - user verification is required to complete the WebAuthn ceremony
• Preferred - the Relying Party prefers user verification is provided but will not fail the WebAuthn ceremony without it
• Discouraged - the Relying Party does not want user verification for the WebAuthn ceremony

Because the bootstrap workflow is used to authenticate a user, it is highly recommended to set this value to Required.

When enabled, the WebAuthn re-authentication workflow can be used to streamline the login experience when authenticating from a previously used device.

The availability of the re-authentication workflow can be overridden at the application level on the WebAuthn Tab of the Application settings.

The authenticator attachment preference for the re-authentication workflow on this tenant. This value controls the attachment requirement for authenticators during the re-authentication workflow registration ceremony. Authenticators that do not meet the requirement are not considered during passkey registration. The possible values are:

• Any - any authenticator attachment is allowed
• Platform only - only authenticators integrated with the client device are allowed
• Cross-platform only - only authenticators that are usable across multiple client devices are allowed

The recommended value for the re-authentication workflow is Platform only to ensure the user has access to that authenticator when logging from the device in the future.

Note: An Enterprise plan is required to utilize WebAuthn cross-platform authenticators.

The user verification requirement for the re-authentication workflow on this tenant. This value controls whether user verification is required for registration and authentication ceremonies during the re-authentication workflow. Authenticators that do not meet the requirement are not considered during passkey registration or authentication. The possible values are:

• Required - user verification is required to complete the WebAuthn ceremony
• Preferred - the Relying Party prefers user verification is provided but will not fail the WebAuthn ceremony without it
• Discouraged - the Relying Party does not want user verification for the WebAuthn ceremony

Because the re-authentication workflow is used to authenticate a user, it is highly recommended to set this value to Required.

The event type, this value will be present in the JSON request to identify the message.

The description of the event.

When enabled this event can be sent by one or more webhook. You will also need to enable the event for a specific webhook to receive the event.

This toggle allows you to optionally disable an event for all webhooks all at once.

The transaction setting for this event. This setting will apply to all webhooks consuming this event type.

No Webhooks are required to succeed: The event will succeed regardless of the webhook response status code. Use this setting when it is not important for a webhook to succeed or provide confirmation that the event has been received and processed successfully.

Any single Webhook must succeed: The event will succeed as long as one or more of the webhooks respond with a status code between 200 and 299 (inclusive).

A simple majority of Webhooks must succeed: The event will succeed if at least half of the webhooks respond with a status code between 200 and 299 (inclusive). This means 50% or more of the webhooks must respond successfully.

A two-thirds majority of Webhooks must succeed: The event will succeed if a super majority of the webhooks respond with a status code between 200 and 299 (inclusive). A super majority is two-thirds (66.7%) or more of the configured webhooks.

All of the Webhooks must succeed: The event will succeed if every configured webhook responds with a status code between 200 and 299 (inclusive). Use this setting when it is critical for every configured webhook to receive and process the event before considering it complete.

When enabled, FusionAuth will act as a SCIM server and the SCIM API endpoints will be functional.

The Entity Type defined for the SCIM client. If there are no Entity Types available in the list then navigate to Entity > Types and create a new one using the template button for SCIM client.

The Entity Type defined for the SCIM server. If there are no Entity Types available in the list then navigate to Entity > Types and create a new one using the template button for SCIM server.

The lambda that will be invoked on every incoming request to the SCIM User API endpoints. This maps the incoming SCIM User JSON to the User object.

The lambda that will be invoked on every outgoing response from the SCIM User API endpoints. This maps the outgoing User object to the JSON for a SCIM User.

The lambda that will be invoked on every incoming request to the SCIM Enterprise User API endpoints. This maps the incoming SCIM Enterprise User JSON to the User object.

The lambda that will be invoked on every outgoing response from the SCIM Enterprise User API endpoints. This maps the outgoing User object to the JSON for a SCIM Enterprise User.

The lambda that will be invoked on every incoming request to the SCIM Group API endpoints. This maps the incoming SCIM Group JSON to the Group object.

The lambda that will be invoked on every outgoing response from the SCIM Group API endpoints. This maps the outgoing Group object to the JSON for a SCIM Group.

The JSON response sent from the Schemas endpoint. This can be customized however you like, but by default the response body will contain the JSON for the core SCIM schemas for SCIM Group, SCIM User, and SCIM EnterpriseUser.

This indicates how to authenticate the Login API when an applicationId is not provided.

When an applicationId is provided, the application configuration will take precedence. In almost all cases you will want to leave this enabled to require the use of an API key.

The lambda assigned to perform extended validation during login requests.

The IP access control list that will be used to restrict or allow access to hosted login pages in FusionAuth. For example, it may be configured to only allow specific IP addresses to access authentication pages (login, forgot password, etc) for all applications on that tenant.

When Access control list is configured on an application within the tenant, the application value will override the tenant value for that application.

When enabled, CAPTCHA is used to help increase security of a form submission on the FusionAuth themed pages.

The type of CAPTCHA to use. FusionAuth supports Google reCAPTCHA v2, Google reCAPTCHA v3, hCaptcha, and hCaptcha Enterprise.

Required when enabled is set to true.

The secret key for this CAPTCHA service.

Required when enabled is set to true.

The site key for this CAPTCHA service.

Required when enabled is set to true.

The threat score threshold for this CAPTCHA service if required. If it is not used by this CAPTCHA service then the value will be ignored.

One or more newline separated email domains for which self service registration will be prohibited. For example, enter your company email domain (piedpiper.com) to prevent employees from using the self-service registration form, or to prevent end users from attempting to create an account using a company email address.

This configuration is applied to all registration API requests and self-service registration pages for all applications in this tenant.

The action to be rate limited.

Note: For the Failed login action, rate limiting can be used in combination with Failed authentication settings . When enabled, and rate limiting conditions have been exceeded, login requests will be denied and bypass the login flow until conditions are no longer exceeded. Failed attempts will only be incremented when requests are not being rate limited.

When enabled, the corresponding action will be rate limited when the limit value has been exceeded within the specified time period .

The number of allowed attempts within the time period before an action will be rate limited. When an action is rate limited, it will not succeed.

The window of time that the limit is evaluated against when determining if an action should be rate limited.

The number of seconds before the OAuth2 Authorization Code is no longer valid to be used to complete a Token request.

The number of seconds before the Change Password identifier is no longer valid to complete the Change Password request.

The number of seconds before the device_code and user_code are no longer valid to be used to complete the Device Code grant.

The number of seconds before the Email Verification identifier is no longer valid to complete the Email Verification request.

The number of seconds before the External Authentication identifier is no longer valid to complete the Authentication request.

The number of seconds before the Login Timeout identifier is no longer valid to complete post-authentication steps in the OAuth workflow.

The number of seconds before the One Time Password identifier is no longer valid to complete a Login request.

The number of seconds before the Passwordless Login identifier is no longer valid to complete a Login request.

The number of seconds before the Pending account link is no longer valid to complete an account link request.

The number of seconds before the Registration Verification identifier is no longer valid to complete the Registration Verification request.

The number of seconds before a remembered consent choice, used to bypass the OAuth scope consent prompt, expires.

The number of seconds before the SAMLv2 AuthN request is no longer valid to complete the SAMLv2 login request.

The number of seconds before the Setup Password identifier is no longer valid to complete the Change Password request.

The number of seconds before the Two Factor identifier is no longer valid to complete a Two Factor login request.

The number of seconds before the Two Factor one-time code used to enable or disable a two-factor method is no longer valid.

The number of seconds before the Two Factor Trust is no longer valid and the user will be prompted for Two Factor during login.

The number of seconds before the WebAuthn authentication challenge is no longer valid and the user will need to restart the authentication workflow.

The number of seconds before the WebAuthn registration challenge is no longer valid and the user will need to restart the credential registration workflow.

The length and type of characters of the generated code used in the Change Password flow.

The length and type of characters of the generated code used in the Email Verification flow.

The length and type of characters of the generated code used for Email Verification one-time codes.

The one-time code for email verification is only used with email verification gating and when using a form field configuration instead of the clickable link.

The length and type of characters of the generated code used in the Passwordless Login flow.

The length and type of characters of the generated code used in the Registration Verification flow.

The length and type of characters of the generated code used for Registration Verification one-time codes.

The one-time code for registration verification is only used with registration verification gating and when using a form field configuration instead of the clickable link.

The length and type of characters of the generated code used in the Setup Password flow.

The length and type of characters of the generated user code used in the Device Authorization Grant flow.

The length and type of characters of the generated code used for Two-Factor one-time codes.

Custom SMTP configuration properties. This field can contain any Java mail property. Any value here will override the default values FusionAuth sets.

The following property has a default value:

• mail.smtp.ssl.protocols has a default value of TLSv1 TLSv1.1 TLSv1.2.

Since version 1.44.0, the following two properties have default values:

• mail.smtp.timeout has a default value of 2000.
• mail.smtp.connectiontimeout has a default value of 2000.

Here’s example syntax for overriding these properties, in this case setting both timeout defaults to 5 seconds.

mail.smtp.timeout=5000
mail.smtp.connectiontimeout=5000

The Connector to be used for this policy.

One or more line separated domains to be used to filter incoming authentication requests. To match all incoming email addresses, a single entry using an asterisk * can be used.

When selected, migrate the user from the Connector into FusionAuth so that future authentications will use FusionAuth and not the Connector.