Tenants

Overview

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.

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

Create a Tenant

To create a new tenant, navigate to Tenants.

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
Table 1. Form Fields

Issuer Required

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

Login Theme Optional

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

Email

Tenant Configuration - SMTP settings
Table 2. SMTP settings

Host Required

The IP address of the outgoing SMTP mail server.

Port Required

The port of the outgoing SMTP mail server.

Username Optional

The username of the outgoing SMTP mail server authentication.

Change password Optional

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

Password Required

The new password to use for the outgoing SMTP mail server authentication.

Security Optional

The preferred encryption protocol used by your SMTP server, this is generally documented by your SMTP service provider.

Tenant Configuration - Email verification settings
Table 3. Email verification settings

Verify email Optional

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

Verify email when changed Optional

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

Verification template Required

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

Required when the Verify email toggle is enabled.

Delete unverified users Optional

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

Delete after Required

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.

Tenant Configuration - Email template settings
Table 4. Template settings

Setup password Optional

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

Forgot password Optional

The template to use for the forgot password workflow that uses emails.

Passwordless login Optional

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

Family

Tenant Configuration - Family
Table 5. Form Fields

Enabled Optional

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

Maximum child age Required

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

Minimum owner age Required

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

Allow child registrations Required

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

Family request template Optional

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 template Optional

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 template Optional

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 registration Optional

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

Delete unverified children Optional

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

Delete after Required

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.

OAuth

Tenant Configuration - OAuth
Table 6. Form Fields

Session timeout Optional

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

Logout URL Optional

The URL the user is redirected to upon logout.

JWT

Tenant Configuration - JWT
Table 7. Form Fields

Refresh token duration Required

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

JWT Duration Required

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

Access token signing key Optional

The key used to sign the access token JWT.

Id token signing key Optional

The key used to sign the Id token JWT.

Password

Tenant Configuration - JWT
Table 8. Failed authentication settings

User action Optional

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

Failed attempts Required

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

Time period Required

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 duration Required

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 unit Optional

The time unit the Action duration is measured in.

Tenant Configuration - JWT
Table 9. Breach detection settings

Enabled Optional

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 Edition is required to enable this feature.

Match mode Optional

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

On login Optional

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
Table 10. Password settings

Minimum length Required

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

Maximum length Required

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

Uppercase & lowercase Optional

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

Special character Optional

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

Number Optional

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 previous passwords Optional

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

Number of passwords Required

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 login Optional

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
Table 11. Cryptographic hash settings

Scheme Optional

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

Factor Required

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 login Optional

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

Webhooks

Tenant Configuration - JWT
Table 12. Table columns

Event type

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

Enabled Optional

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 Optional

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

 
 

Value Description

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.

Advanced

Tenant Configuration - External Identifier Durations
Table 13. External identifier durations Form Fields

Authorization Code Required

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

Change Password Required

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

Email Verification Required

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

External Authentication Required

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

One Time Password Required

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

Passwordless Login Required

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

Registration Verification Required

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

Setup Password Required

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

Two Factor Login Required

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

Two Factor Trust Required

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

Device Grant Codes Required

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

Tenant Configuration - External Identifier Generation
Table 14. External identifier generation Form Fields

Change Password Required

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

Email Verification Required

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

Passwordless Login Required

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

Registration Verification Required

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

Setup Password Required

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

Device Grant User Code Required

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

Table 15. SMTP Settings Form Fields

Additional properties Optional

The custom SMTP configuration properties that may be necessary in some cases.