Limitations

Overview

FusionAuth has the following known limits.

• User Identifiers

• User Searches

• Field Lengths

• API Keys

• Minimum Key Lengths

• Updating Keys

• Default Configuration

• OAuth Logout Behavior

• SAML

• Identifiers

• Data Type Changes In 'data' Fields

• TOTP Algorithm Implementation

• Multi-Tenancy

• System Upgrade Downtime

• Database Configuration

• Password Hashes

• SCIM

• Email Templates

• What’s Not Limited

User Identifiers

Each account must have a user identifier, either an email address or a username. Users may not have multiple email addresses. See this issue for more information.

User Searches

You cannot filter search results in FusionAuth to only return certain fields. Instead you must do this through post-processing. So if you want to retrieve only the firstName and birthDate fields of a set of users, the results will give you each entire user object and you must select desired fields. You can use the JSON processing facilities in your chosen language to do so, or use a tool such as jq.

When using the Elasticsearch search engine, the maximum number of users returned for any search is 10000 users. There is an open bug tracking this issue.

Field Lengths

FusionAuth stores most data in a database. Lengths of specific fields are documented in the database schema for your database type. Please download the database schema for your version of FusionAuth to review length limits for a particular column.

Many varchar columns have a length of 191. Why 191? In MySQL when using a utf8mb4 (4 byte character set) on an indexed column, MySQL limits the usable characters to 191 to account for the overhead of the 4 byte addressing. The InnoDB MySQL engine has a max index length of 767 bytes (for mysql 5.7.9, the earliest version of MySQL which Fusionauth supports). Because we are using utf8mb4 which allows up to 4 bytes per character, we end up with 767/4 ~ 191, so we set the column length to that.

API Keys

FusionAuth is API first and everything can be managed by an API. You can create an API key in the following ways:

• Using the API Key API, if you are using version 1.26 or greater.

• Use the administrative user interface.

• Kickstart which only works on fresh installations.

Minimum Key Lengths

You can use FusionAuth to manage your cryptographic keys. Due to security considerations, FusionAuth won’t import keys below a certain length.

For RSA keys used to verify signatures, the minimum length is 1024. This key length is allowed as of FusionAuth 1.23.4 and supports external systems that rely upon this weak key length.

For RSA keys used for signing or any other purpose, the minimum length is 2048.

For ECC keys, the minimum length is 256.

See the Keys API for more, including supported algorithms and lengths.

Updating Keys

FusionAuth can manage keys, secrets, and certificates, using Key Master. You can update a Key managed by FusionAuth, with some limits.

Only the name of the Key may be changed; all other fields will remain the same. If you need to update a Key with a new certificate, algorithm or other attributes, please Import a Key.

For example, if you have a Key with an associated expiring certificate, you’ll need to follow the steps similar to those outlined in the JWT signing key rotation documentation:

• Import this key, keypair or certificate into FusionAuth. This will create a new Key entity in FusionAuth.

• Update the appropriate configuration with this new Key (JWT signing configuration, SAML validation configuration, etc).

• Once the new Key is configured for use, remove the expired, previous Key.

Note that validation rules will prevent you from removing an in-use key.

Default Configuration

There are a number of items in FusionAuth created by default and which cannot be removed. Additionally, there are sometimes limits to modifying them. These defaults include:

• The Default tenant, which will always exist.

• The FusionAuth application, which resides in the Default tenant. This will always have the Id 3c219e58-ed0e-4b18-ad48-f4f92793ae32.

• The Default theme, which is always read only. This will always have the Id 75a068fd-e94b-451a-9aeb-3ddb9a3b5987.

• The FusionAuth application roles, which may be assigned to users, but are read only. View the roles documentation for the immutable Ids of each role.

• Three OpenID Connect shadow keys. These may not be modified or removed. When any of these keys are selected as the signing key for the Id Token, the Client Secret defined by the FusionAuth application will be used to sign the token. This is per section 10.1 of the OIDC specification.

  • SHA-256. This will always have the Id 092dbedc-30af-4149-9c61-b578f2c72f59.

  • SHA-384. This will always have the Id 4b8f1c06-518e-45bd-9ac5-d549686ae02a.

  • SHA-512. This will always have the Id c753a44d-7f2e-48d3-bc4e-c2c16488a23b.

• The FusionAuth connector. This will always have the Id e3306678-a53a-4964-9040-1c96f36dda72.

OAuth Logout Behavior

An Application’s OAuth configuration allows you to specify the logout behavior of an application as either "All applications" or "Redirect only." Specifying the default value of "All applications" will call the configured logout URL for each application in the Tenant except for the FusionAuth admin application.

As of version 1.37, this is no longer a limitation. See the GitHub issue for more information.

SAML

Identifiers

Identifiers (Ids) in FusionAuth are UUIDs.

If you are creating an object, such as an application, with the FusionAuth API, you can specify this Id, as long as it is a valid UUID. This works for users, applications, and tenants, among others, and makes it possible to avoid breaking external systems dependent on existing identifiers.

Data Type Changes In 'data' Fields

FusionAuth provides data fields on many types of objects:

• Applications

• Tenants

• Groups

• Users

• Registrations

• Consent

If you are using the Elasticsearch search engine, the user.data, registration.data, and entity.data fields are indexed by Elasticsearch.

For example, you could create a field contained in user.data called migrated and store a boolean value. If you later set that field to an object value for any user, you won’t be able to search for that user. Other users added after this user will be found, however, as long as they have the correct boolean value for user.data.migrated (or no value).

Elasticsearch requires fields to have the same data type across all indexed objects. In the example above, once Elasticsearch "knows" that user.data.migrated is a boolean, it expects this field, if present, to be a boolean for all users.

Therefore, you should not change the data type of fields stored in these fields across entities.

Other object data fields may in the future be indexed by Elasticsearch. Therefore, it is recommended to maintain a consistent schema for all data contained in data fields.

This limitation applies only to installations using the Elasticsearch search engine. However, if you start with the database search engine and eventually need to switch to the Elasticsearch search engine because the database search engine no longer meets your needs, if you have not enforced consistency in the data field types, you will not be able to do so.

TOTP Algorithm Implementation

While there is underlying support for different code lengths, algorithms and time steps, at the current time the system only allows for the following TOTP settings:

Any attempt to change these configuration values will currently be ignored. If you need different configuration settings, please file a GitHub issue detailing your use case.

Multi-Tenancy

The main limits on tenants in FusionAuth are resources of the underlying server. The tenants are lightweight, but do take some resources. There are FusionAuth instances supporting thousands of FusionAuth tenants. At this scale the FusionAuth administrative user interface runs into some issues, so use one of the client libraries to manage the FusionAuth tenant and application configuration. There’s a GitHub issue to resolve these limits in the administrative user interface.

Another current limitation of FusionAuth with respect to tenants is the ability to limit users who log into the administrative user interface to a single tenant. This is not currently supported. There are tracking issues for this functionality. Both GitHub issue #91 and GitHub issue #1524 offer different ways to add support for this feature.

Login records, audit logs and other log files are not separated by tenant. You may be able to query based on FusionAuth tenant or application Ids, but if you need true isolation of log files, you should run separate instances. There’s a GitHub issue to address this.

CORS settings are not configurable by tenant, nor are other settings configured by navigating to Settings → System.

FusionAuth application objects and other FusionAuth tenant scoped entities cannot be shared across tenants. If you need to keep such entities in sync, you can write scripts to sync up the configuration of multiple FusionAuth applications across tenants. For users, you may be able to have users federate to an external identity provider, and enable that provider for FusionAuth applications across tenants. This will allow your external identity provider to be the system of record for your users.

The default FusionAuth tenant, in which the FusionAuth administrative user interface application resides, cannot be removed.

System Upgrade Downtime

System upgrades require downtime. This is typically on the order of seconds to minutes.

In general, the process for upgrading from version 1.x-1 to version 1.x is:

• Take down all nodes running 1.x-1.

• Upgrade the database schema by running the migrations, bringing the database to version 1.x.

• Upgrade the FusionAuth application and (if required) Elasticsearch packages, bringing your nodes to 1.x.

• Start all FusionAuth nodes.

The recommendation is that you automate the process and minimize downtime. For FusionAuth Cloud we use a configuration management tool and see downtime on the order of seconds for multi-node instances.

You may also, if you are in an environment with a load balancer and creating nodes is easy, follow this process:

• Stand up a node and install FusionAuth 1.x on it.

• Replace a node running 1.x-1 out of the load balancer with the new node running 1.x.

• Upgrade the database schema by running the migrations, bringing the database to version 1.x. If you are running in production and silent mode, FusionAuth will apply the changes, otherwise you must apply them out of band (by running the SQL scripts). Read more about silent mode.

• Stand up another node and install FusionAuth 1.x on it.

• Replace another node running 1.x-1 out of the load balancer with the new node running 1.x.

• Repeat until you have updated all the nodes.

There’s an open issue for n-1 version compatibility. Please vote that up if this is important to you.

Database Configuration

Database configuration is limited to a single host. Using a valid JDBC URL with multiple hosts is not currently supported.

There’s a tracking issue to support more database configuration options.

The format of the database username has some limitations as well. In particular, the username cannot contain an @ symbol. Please review the tracking issue for more information.

Password Hashes

There is no FusionAuth API allowing user password hashes to be exported.

If you need to migrate hashes from FusionAuth to any other system, use a database export.

SCIM

The current SCIM implementation does not support:

• Bulk operations

Bulk API operations are available via FusionAuth APIs, but are not currently supported via SCIM compatible endpoints. If this functionality is required, please file a GitHub issue explaining your use case.

The list operation is limited to 10,000 users if you are using the Elasticsearch search engine. This GitHub issue discusses this limitation.

You cannot create a FusionAuth Registration for a user provisioned with SCIM. If you need to register the user for one or more Applications, you have a few options. You may:

• use the SCIM User Request Converter Lambda.

• use the user.create.complete webhook.

Either works. The correct choice depends on if you want to do the processing within FusionAuth using a lambda or using an external server.

While it is not enforced, or a hard limitation, it is recommended to configure at most one SCIM server per tenant.

While you can have multiple SCIM servers per configured within one tenant, at the end of the day you only have one user data store per tenant.

Conflicts with creation, updates and deletion could happen; they won’t be automatically resolved by FusionAuth. If you need to use multiple SCIM servers, ensure your clients can handle such conflicts.

Email Templates

There are no FusionAuth enforced limits on the content of HTML or text email templates. You can store whatever HTML or text you’d like.

The only validation performed ensures that non-null strings are provided for each template.

The maximum length of an email template is 65,535 bytes due to the database column used.

What’s Not Limited

All other objects and configuration, including but not limited to the following, are limited only by the resources of your system:

• Users

• Applications

• Tenants

• Roles

• Groups

• Identity Providers such as SAML or OIDC connections

• API keys to allow for programmatic configuration of and interaction with FusionAuth

• The number of email templates

• Supported languages/locales

• Signing and verifying keys

• MFA methods per user