Tenants

FusionAuth is fundamentally a single tenant solution, so you may be surprised to learn that we support multiple tenants.

FusionAuth will always be a single tenant solution, this means that your instance of FusionAuth is your own and even when FusionAuth is hosting, we do not co-mingle your data with other clients. FusionAuth was built as a single tenant solution, and we have no plans to change anytime soon.

It is entirely likely that our clients may wish to be multi-tenant or offer their services to more than one client. In these scenarios it may be useful to separate Users, Applications and Groups for each of your clients.

For example, let's assume you are building a payroll offering using a SaaS model. In this case it is possible that monica@piedpiper.com works for two of your clients, Acme Corp and The Umbrella Company. Because Monica is not aware that Acme Corp and The Umbrella Company both are buying their Payroll software from the same vendor it would be surprising for Monica to share the same password and account details between these two companies. In this scenario you would likely want to utilize the FusionAuth Tenant to ensure that monica@piedpiper.com exists once for each instance of your Payroll offering.

See Tenant API Authentication for more details about making API requests in a multi-tenant configuration.

Here's a brief video covering some aspects of tenants:

Play

Core Concepts Relationships#

Below is a visual reminder of the relationships between FusionAuth's primary core concepts.

Diagram showing Tenants used within FusionAuth.

Diagram showing Tenants used within FusionAuth.

Admin UI#

This page describes the admin UI for creating and configuring a Tenant.

List of Tenants#

To display a list of tenants, navigate to Tenants .

List of Tenants

List of Tenants

Using the icons on this screen, you can:

  • Create a new tenant
  • Delete the tenant configuration
  • Duplicate the tenant configuration
  • Edit the tenant configuration
  • View the tenant configuration

Create a Tenant#

To create a new tenant, navigate to Tenants .

Create a Tenant.

Create a Tenant.

Tenant Configuration#

A majority of your FusionAuth configuration is managed at the Tenant-level. Some of these configuration options act as defaults and can be overridden by the Application.

General#

Tenant Configuration - General

Tenant Configuration - General

Form Fields#

Issuerrequired

The named issuer used to sign tokens. This is generally your public fully qualified domain with the https:// protocol prefix. For example, https://example.com.

Base URLoptionalAvailable since 1.68.0

The default base URL used when rendering links in templates for this Tenant. This value is used when an application-specific base URL is not defined.

Login Themeoptional

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

Form Settings#

Admin user formoptionalAvailable since 1.20.0

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

This feature is only available in paid plans. To learn more, see our pricing page.

Username settings#

Enable Unique usernames to allow multiple users suggest the same username. If there are any collisions, FusionAuth will transparently create a unique username by appending a suffix. The user will continue to use the username without the suffix.

Unique usernamesoptionalDefaults to falseAvailable since 1.27.0

When true, FusionAuth will handle username collisions.

This feature is only available in paid plans. To learn more, see our pricing page.

Number of digitsoptionalDefaults to 5Available since 1.27.0

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.

Separator characteroptionalAvailable since 1.27.0

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.

Connectors#

Connectors can be enabled on a per tenant basis with a Connector policy.

The Tenant Connector policy configuration tab.

The Tenant Connector policy configuration tab.

You can find details on adding a connector below. Full documentation on Connectors and Connector Policies can be found here.

Add Connector Policy Dialog#

If you click on the Add policy button on this page you will be presented with the following dialog.

Add Connector Policy

Add Connector Policy

Form Fields#
Connectorrequired

The Connector to be used for this policy.

DomainsoptionalDefaults to ["*"]

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.

Migrate useroptional

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

Identities#

Control Email and Phone Number identity verification and template settings from one place.

Tenant Configuration - Identities settings

Tenant Configuration - Identities settings

Messaging Settings#

MessengerrequiredAvailable since 1.59.0

The messenger used to deliver messages for phone number verification, passwordless login, two-factor authentication, and event notifications.

Required when the Verify identity toggle is enabled for phone numbers or when any phone templates are configured in Template Settings .

Identity Verification Settings#

Verify identityoptional

When enabled, users will be required to verify their email address or phone number identity.

Allow implicit verificationoptional

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.

Verify identity when changedoptional

When enabled, users will be required to verify their email address upon update. Phone number identities are always verified after a change.

Verification templaterequired

The email or message template to use when accounts are created to verify the User's email address or phone number.

Required when the associated Verify identity toggle is enabled.

Verification complete templateoptionalAvailable since 1.30.0

The email or message template to use when notifying a user that their email address or phone number has been verified.

Verification strategyoptionalAvailable since 1.27.0

The process by which the user will verify their email address or phone number. Using the Form Field method works only when the associated Unverified behavior is Gated.

Unverified behavioroptionalAvailable since 1.27.0

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

Allow change when gatedoptionalAvailable since 1.27.0

When enabled, the user is allowed to change their email address or phone number when they are gated because they haven't verified their identity.

Delete unverified usersoptional

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

Delete afterrequired

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

Required when the Delete unverified users toggle is enabled.

Tenant Configuration - Template settings

Tenant Configuration - Template settings

Template settings#

Admin two-factor method removaloptionalAvailable since 1.68.0

The email or message template to use when notifying a user that an administrator removed one of their two-factor methods.

Forgot passwordoptional

The email or message template to use for the forgot password workflow.

Identity updateoptionalAvailable since 1.30.0

The email or message template to use when notifying a user that their identity has been updated.

Note: To use this feature, you'll need an Enterprise plan.

Login Id duplicate on createoptionalAvailable since 1.30.0

The email or message template to use when notifying a user that another user has attempted to register an account with the same email address, phone number, or username 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: To use this feature, you'll need an Enterprise plan.

Login Id duplicate on updateoptionalAvailable since 1.30.0

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

Note: To use Login Id duplicate on update, you'll need an Enterprise plan.

Login with new deviceoptionalAvailable since 1.30.0

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

Note: To use Login with new device, you'll need an Enterprise plan.

Suspicious loginoptionalAvailable since 1.30.0

The email or message 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: To use Suspicious login, you'll need an Enterprise plan.

Password reset successoptionalAvailable since 1.30.0

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

Note: To use Password reset success, you'll need an Enterprise plan.

Password updateoptionalAvailable since 1.30.0

The email or message 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: To use Password update, you'll need an Enterprise plan.

Passwordless loginoptional

The email or message template to use to send the link or one-time code for passwordless login requests.

Set up passwordoptional

The email or message template to use when accounts are created and the user needs to set up their password.

Two-factor method addedoptionalAvailable since 1.30.0

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

Note: To use Two-factor method added, you'll need an Enterprise plan.

Two-factor method removedoptionalAvailable since 1.30.0

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

Note: To use Two-factor method removed, you'll need an Enterprise plan.

Email#

Once you have configured your email settings, you may test your configuration with the Send test email button.

Tenant Configuration - SMTP settings

Tenant Configuration - SMTP settings

SMTP settings#

HostoptionalDefaults to localhost

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

PortoptionalDefaults to 25

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.

Usernameoptional

The username of the outgoing SMTP mail server authentication.

Change passwordoptional

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

Passwordrequired

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.

SecurityoptionalDefaults to None

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
Default from addressoptional

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).

Default from nameoptional

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).

Additional HeadersoptionalAvailable since 1.32.0

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).

Debug enabledoptionalAvailable since 1.37.0

When enabled SMTP and JavaMail debug information will be output to the Event Log.

Family#

Tenant Configuration - Family

Tenant Configuration - Family

Form Fields#

Enabledoptional

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

Maximum child agerequired

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

Required when the Enabled toggle is enabled.

Minimum owner agerequired

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

Required when the Enabled toggle is enabled.

Allow child registrationsrequired

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

Family request templateoptional

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

Confirm child account templateoptional

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

Parent registration request templateoptional

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

Parent email required during registrationoptional

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

Delete unverified childrenoptional

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

Delete afterrequired

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.

Multi-Factor#

This feature is only available in paid plans. To learn more, see our pricing page.

Note: The Authenticator/TOTP implementation is not a premium feature, and is included in the Community version. Email, SMS, and Voice require the Advanced Multi-Factor feature available when purchasing a paid plan.

Policies#

Tenant Configuration - MFA policy settings

Tenant Configuration - MFA policy settings

On loginoptional

If a policy requires a two-factor challenge on login and the user has not already configured a two-factor method, then they will be required to configure one.

Risk-based policies use FusionAuth's Intelligent MFA, which combines multiple signals to decide when to issue an MFA challenge.

Supported values include:

  • Disabled: Never challenge during login, even if a user has configured a two-factor method
  • Enabled: Only challenge if user has configured an eligible MFA method
  • Challenge On Medium Risk: Only challenge on medium or high login risk   Available since 1.68.0
  • Challenge On High Risk: Only challenge on high login risk   Available since 1.68.0
  • Required: Always challenge during login   Available since 1.42.0

Note: To use an Intelligent MFA Policy, you'll need a paid plan.

MFA requirement lambdaoptional

The MFA requirement lambda that will be invoked during logins, password changes, and MFA Status API calls. FusionAuth uses this lambda to determine whether to challenge the user with MFA. Will be overridden by any MFA requirement lambda provided by the application.

You can customize this logic to:

  • Change FusionAuth’s MFA decision for a user.
  • Trigger a suspicious login event based on your criteria.   Available since 1.62.0

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

Debug Enabled

When enabled, writes debug information to the event log during login for multi-factor authentication decisions.

Authenticator settings#

Tenant Configuration - MFA authenticator settings

Tenant Configuration - MFA authenticator settings

Enabledoptional

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

Email settings#

Tenant Configuration - MFA email settings

Tenant Configuration - MFA email settings

Enabledoptional

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

Templaterequired

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.

Phone settings#

Tenant Configuration - MFA Phone settings

Tenant Configuration - MFA Phone settings

Enabling either or both of the SMS enabled or Voice enabled toggles in this section allows users to use a mobile phone number to complete a multi-factor authentication request.

SMS enabledoptional

When enabled, users can receive two-factor codes on their mobile phone via SMS.

SMS messengerrequired

The Messenger used to send codes via SMS.

Required when the SMS enabled toggle is enabled.

SMS templaterequired

The SMS template to use.

Required when the SMS enabled toggle is enabled.

Voice enabledoptional

When enabled, users can receive two-factor codes on their mobile phone via voice message.

Voice messengerrequired

The Messenger used to send codes via voice.

Required when the Voice enabled toggle is enabled.

Voice templaterequired

The voice template to use.

Required when the Voice enabled toggle is enabled.

WebAuthn#

This feature is available to licensed FusionAuth instances as of version 1.52.0. To register for a free license, visit the Plan tab in the account portal.

Tenant Configuration - WebAuthn

Tenant Configuration - WebAuthn

Form Fields#

Enabledoptional

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

Relying party Idoptional

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.

Relying party nameoptional

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.

Debug enabledoptional

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

Tenant Configuration - WebAuthn Bootstrap settings

Tenant Configuration - WebAuthn Bootstrap settings

Bootstrap settings#

The settings in this section affect the availability and behavior of the WebAuthn bootstrap workflow. The bootstrap workflow is used when the user must "bootstrap" the authentication process by identifying themselves prior to the WebAuthn ceremony and can be used to authenticate from a new device using WebAuthn.

Enabledoptional

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.

Authenticator attachmentoptional

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: To use WebAuthn cross-platform authenticators, you'll need an Enterprise plan.

User verificationoptional

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.

Tenant Configuration - WebAuthn Re-authentication settings

Tenant Configuration - WebAuthn Re-authentication settings

Re-authentication settings#

The settings in this section affect the availability and behavior of the WebAuthn re-authentication workflow. The re-authentication workflow is meant to provide a streamlined user experience when logging in from a frequently used device.

Enabledoptional

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.

Authenticator attachmentoptional

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: To use WebAuthn cross-platform authenticators, you'll need an Enterprise plan.

User verificationoptional

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.

OAuth#

Tenant Configuration - OAuth

Tenant Configuration - OAuth

Form Fields#

Session timeoutoptional

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

Logout URLoptional

The URL the user is redirected to upon logout.

Client credentials populate lambdaoptionalAvailable since 1.28.0

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

Allow access token bootstrapAvailable since 1.56.0

When enabled, an SSO session can be created after login by providing an access token as a bearer token in a request to the OAuth2 Authorize endpoint.

JWT#

Tenant Configuration - JWT

Tenant Configuration - JWT

JSON Web Token settings#

JWT durationrequired

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

Access token signing keyoptional

The key used to sign the access token JWT.

Id token signing keyoptional

The key used to sign the Id token JWT.

Refresh Token settings#

Refresh token durationrequiredDefaults to 43,200

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

Refresh token expirationoptionalDefaults to Fixed

The Refresh token expiration may be one of the following:

  • fixed window (Fixed): expires a configurable time-to-live after initial issuing
  • sliding window (SlidingWindow): expires a configurable time-to-live after the last time the refresh token was used
  • sliding window with a maximum lifetime (SlidingWindowWithMaximumLifetime): combines the previous two options like an OR operator: expires a configurable time-to-live after the last time the refresh token was used, as long as it does not exceed a maximum lifetime after initial issuing

To configure the time-to-live, use refreshTokenTimeToLiveInMinutes; to configure the maximum lifetime, use maximumTimeToLiveInMinutes.

Consider a scenario where a refresh token is issued at 1:00, has an time-to-live of 60 minutes, and a maximum lifetime of 6 hours:

  • If the expiration is fixed, the token will expire at 2:00.
  • If the expiration is a sliding window, then if the refresh token is used at 1:55, it would then expire at 2:55. If it were then used at 2:50, it would expire at 3:50. This can continue forever, as long as the client always refreshes the token before 60 minutes have elapsed (good luck with daylight savings!).
  • If the expiration is a sliding window with a maximum lifetime, then if the refresh token is used at 1:55, it would then expire at 2:55. If it were then used at 2:50, it would expire at 3:50. This can continue until 7:00, when the refresh token passes the maximum lifetime and expires.
Refresh token usageoptionalDefaults to Reusable

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.

One-time use grace periodoptionalDefaults to 0

When Refresh token usage is set to One-time use, you may optionally set the grace period to something greater than 0 seconds.

The grace period is the length of time specified in seconds that a one time use token can be reused.

This value must be greater than 0 and less than 86400 which is equal to 24 hours. Setting this value to 0 effectively disables the grace period which means a one-time token may not be reused. For security reasons, you should keep this value as small as possible, and only increase past 0 to improve reliability for an asynchronous or clustered integration that may require a brief grace period.

Note that one-time use tokens refreshed within a grace period are not considered for revocation when the Tenant Refresh Token Revocation Policy is configured to revoke a one-time use refresh token on reuse. When a token is reused within the grace period the current token will be returned on the API response and the token will not be rotated.

Refresh token revocationoptional

The events that cause refresh tokens to be revoked. The possible values are:

  • On action preventing login revokes all of a user's refresh tokens when a user action prevents login.
  • On multi-factor enable revokes all of a user's refresh tokens when a user enables multi-factor authentication for the first time.
  • On password change revokes all of a user's refresh tokens when a user changes their password.
  • On reuse of a one-time use token which revokes the token, if and when a one-time use refresh token is reused outside of any configured grace period. Only the reused token is revoked; the rest of the user's tokens remain valid.

Password#

Tenant Configuration - JWT

Tenant Configuration - JWT

Failed authentication settings#

User actionoptional

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

Failed attemptsrequired

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

Time periodrequired

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.

Action durationrequired

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.

Time unitoptional

The time unit the Action duration is measured in.

Cancel action on password resetAvailable since 1.42.0

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.

Email userAvailable since 1.42.0

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.

Tenant Configuration - JWT

Tenant Configuration - JWT

Breach detection settings#

Enabledoptional

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.

Match modeoptional

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

On loginoptional

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

Tenant Configuration - JWT

Tenant Configuration - JWT

Password settings#

Password enabledoptionalDefaults to enabledAvailable since 1.59.0

When enabled, users will be required to set a password during registration and can later change it. When disabled, applications must be configured to allow passwordless login or have an IdP configured to allow login.

Minimum lengthrequired

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

Maximum lengthrequired

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

Uppercase & lowercaseoptional

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

Special characteroptional

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

Numberoptional

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

Minimum age (toggle)optional

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

Minimum age (value)required

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

Required when the Minimum age toggle is enabled.

Expiration (toggle)optional

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

Expiration (value)required

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

Required when the Expiration toggle is enabled.

Reject passwords containing user login IdoptionalAvailable since 1.63.0

When enabled, prevent users from including their login Id in their password.

Reject previous passwordsoptional

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

Number of passwordsrequired

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

Required when the Reject previous passwords toggle is enabled.

Re-validate on loginoptional

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.

Tenant Configuration - JWT

Tenant Configuration - JWT

Cryptographic hash settings#

Schemeoptional

The password hashing scheme used when creating new users and when changing a password. View hashing algorithms that ship with FusionAuth or learn how to create your own hashing algorithm.

Factorrequired

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.

Re-hash on loginoptional

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

Webhooks#

Tenant Configuration - Webhooks

Tenant Configuration - Webhooks

Webhooks#

Enable the webhooks you wish to receive events from this tenant. All webhooks will be shown, but if the webhook is a global webhook then you will not be able to unselect it here. That must be done in the Tenants Tab of the Webhook Settings.

Event Settings#

Event

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

Description

The description of the event.

Enabled

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.

Transaction setting

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.

SCIM#

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

Tenant Configuration - SCIM

Tenant Configuration - SCIM

Read more about setting up and using SCIM in the full SCIM documentation.

The SCIM server configuration to enable incoming SCIM client provisioning requests.

SCIM server settings#

Enabledoptional

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

Client entity typerequired

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.

Server entity typerequired

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.

User request lambdarequired

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.

User response lambdarequired

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.

Enterprise User request lambdarequired

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.

Enterprise User response lambdarequired

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.

Group request lambdarequired

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.

Group response lambdarequired

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.

Schemasoptional

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.

Security#

Tenant Configuration - Security: ACL and CAPTCHA

Tenant Configuration - Security: ACL and CAPTCHA

Login API settings#

Require an API keyoptional

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.

Login validation lambdaoptionalAvailable since 1.53.0

The lambda assigned to perform extended validation during login requests.

Access control lists settings#

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

Access control listoptional

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.

CAPTCHA settings#

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

CAPTCHA is supported on multiple theme templates, when enabled. You can further control display on a template by template basis with the specific theme template variables.

See invisible reCAPTCHA for information on enabling an invisible reCAPTCHA badge on the page.

Enabledoptional

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

Methodrequired

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.

Secret keyrequired

The secret key for this CAPTCHA service.

Required when enabled is set to true.

Site keyrequired

The site key for this CAPTCHA service.

Required when enabled is set to true.

Threat score thresholdoptional

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.

Tenant Configuration - Security: Blocked domains

Tenant Configuration - Security: Blocked domains

Blocked domain settings#

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

Blocked domainsoptional

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.

Tenant Configuration - Security: Client risk configuration and rate limiting

Tenant Configuration - Security: Client risk configuration and rate limiting

Client risk configuration#

Available since 1.68.0

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

Enabledoptional

When enabled, allows configuration of which risk signals are included in the composite risk score. The score is available to MFA policies, and the MFA requirement lambda. Disabled signals are excluded from all risk calculations. Disabling all signals sets the risk score to HIGH.

Blocklisted IPBooleanoptionalDefaults to true

Checks whether the client's IP address appears on a blocklist.

Bot detectedBooleanoptionalDefaults to true

Detects bot interactions with the browser window.

Dormant accountBooleanoptionalDefaults to true

Checks if the user has not logged in for a long period of time.

Dormant passwordBooleanoptionalDefaults to true

Checks if the user's password has not been changed for a long period of time.

Impossible travelBooleanoptionalDefaults to true

Tracks geographic locations for login attempts. Flags a login as high risk if it occurs sooner than it would take to physically travel from the previous location to the current location.

Recent identity changeBooleanoptionalDefaults to true

Checks if the user's login ID has been changed recently.

Recent password changeBooleanoptionalDefaults to true

Checks if the user's password has been changed recently.

Suspicious user agentBooleanoptionalDefaults to true

Checks whether the client's user agent has been flagged as suspicious.

Unrecognized deviceBooleanoptionalDefaults to true

Checks whether the request originates from an unrecognized device.

Untrusted deviceBooleanoptionalDefaults to true

Checks if the request originates from a device that is not in the user's trusted device list.

Rate limit settings#

This feature is only available in the Enterprise plan. To learn more, see our pricing page.

The Rate limit settings allow you to set a number of times an action can be attempted within a specific time frame. When the limit is exceeded, that action is unavailable until the configured time frame elapses without a failed attempt. The settings are evaluated and enforced per user.

Action

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.

Enabled

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

Limit

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.

Time period

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

Advanced#

Tenant Configuration - External Identifier Durations

Tenant Configuration - External Identifier Durations

External identifier durations Form Fields#

Authorization Coderequired

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

Change Passwordrequired

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

Device Grant Codesrequired

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

Email Verificationrequired

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

External Authenticationrequired

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

Login timeoutrequired

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

One Time Passwordrequired

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

Passwordless Loginrequired

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

Pending account linkrequired

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

Phone verificationrequired

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

Registration Verificationrequired

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

Remember scope consent choicerequired

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

SAMLv2 AuthN requestrequired

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

Setup Passwordrequired

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

Two-Factor Loginrequired

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

Two-Factor one-time coderequired

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

Two-Factor Trustrequired

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

WebAuthn authenticationrequired

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

WebAuthn registrationrequired

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

Tenant Configuration - External Identifier Generation

Tenant Configuration - External Identifier Generation

External identifier generation Form Fields#

Change Passwordrequired

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

Email Verificationrequired

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

Email Verification one-time coderequired

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.

Passwordless Loginrequired

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

Passwordless Login one-time coderequiredAvailable since 1.59.0

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

The one-time code for passwordless logins is only used when sending SMS messages to phone numbers, or when using an explicit loginStrategy value of FormField on the Start Passwordless Login API.

Phone verificationrequired

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

Phone verification one-time coderequired

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

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

Registration Verificationrequired

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

Registration Verification one-time coderequired

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.

Setup Passwordrequired

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

Device grant user coderequired

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

Two-Factor one-time coderequired

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

SMTP Settings Form Fields#

Additional propertiesoptional

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