Limitations

Overview

FusionAuth has the following known limits:

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.

Prior to version 1.48.0, when using the Elasticsearch search engine, the maximum number of users returned for any search is 10,000 users. For versions 1.48.0 and later, there is no limit on the number of users which can be returned if you paginate through the results.

There are no latency guarantees around the indexing of user data in Elasticsearch after the user has been updated using the API. The Elasticsearch index is eventually consistent.

The duration between an Update User API call and the changed attributes appearing in a search request would be the time it takes FusionAuth to make the request to Elasticsearch added to the time for Elasticsearch to refresh the index and make it visible to search.

The time it takes to expose index changes to searches in Elasticsearch is called the refresh_interval. This value defaults to one second, so that is the minimum practical delay.

Maximum Users Returned Workarounds

You can work around the user search limit by writing one or more search queries to return less than 10,000 users. You can know if the query returns more than that limit by using the accurateTotal request parameter. The User Search API contains more information about the accurateTotal parameter and its effect.

For example, if you needed to download all users, you could query for users with an email address starting with A, then starting with B, and so on. Here’s a sample shell script which retrieves all users using this strategy.

If you have access to the Elasticsearch server, you may also run your query directly against it. The Elasticsearch query result will return Elasticsearch document Ids. Each document Id corresponds to a FusionAuth user Id. To retrieve user data, which is most likely what you are after, use the User Search API with one or more user Ids.

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. This is also known as the administrative user interface or admin UI.
• 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.

Login API and OAuth Scopes

The login API does not accept the OAuth scope parameter as it is not part of an OAuth workflow. If your application requires the OAuth scope parameter to be present in the JWT, it can be added with the JWT Populate lambda.

You’re responsible for building the user interface to prompt users for consent to the requested scopes and capturing their response.

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.

UserInfo Authorization Header

The UserInfo endpoint takes access tokens and returns claims about the user.

In version 1.50.0 and later, the aud claim is required for all tokens. The aud claim value, or the first value in the case where the claim contains a list, must correspond to an active Application.

If you have a token that was not obtained from an OAuth flow and does not contain the aud claim, consider adding the claim or using the JWT Validate API instead.

SAML

IdP Limitations

FusionAuth supports SAML both as a SAML Identity Provider (IdP) and as a Service Provider (SP). The IdP implementation has certain limitations.

Version 2.0 is supported; other SAML versions are unsupported.

FusionAuth supports only the following NameIDPolicy values:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

To determine the correct value for NameIDPolicy, please examine the supported values of the software package for which you are configuring FusionAuth as the IdP.

FusionAuth won’t fail validation on any NameIDPolicy value. If the requested NameIDPolicy is persistent, FusionAuth will use that and return the User’s unique id (user.id). In all other cases, the User’s email address (user.email) will be used for the name Id.

FusionAuth supports the following SAMLv2 bindings:

• HTTP Redirect
• HTTP POST

Other bindings are not supported.

As of version 1.30.2, if the NameIdFormat is omitted by an SP, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress will be used.

SP Limitations

FusionAuth supports SAML both as a SAML Identity Provider (IdP) and as a Service Provider (SP). The SP implementation has certain limitations.

Version 2.0 is supported; other SAML versions are unsupported.

FusionAuth supports the following NameID format values by default:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

You may also provide your own format name. To determine the correct value, please examine the supported values of the software package for which you are configuring FusionAuth as the SP.

Map between SAML claims and user claims using a reconcile lambda or FusionAuth SAMLv2 Identity Provider configuration.

FusionAuth supports the following SAMLv2 bindings:

• HTTP Redirect
• HTTP POST

Other bindings are not supported.

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. The ability to choose specific Ids exists for Users, Applications, and Tenants, among others, and allows you to avoid breaking external systems dependent on existing identifiers.

Ids cannot be modified after the object is created. If you need to change an identifier, delete the object and recreate it with the correct Id.

User Identifiers

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

An account may have both a username and an email address.

Client Ids

OAuth has the concept of a client_id. In FusionAuth, client_ids cannot be modified after creation. During creation, an Id can be set to any valid UUID value. The Id must be unique across all Tenants.

The client_id is always the same as either the Application Id or Entity Id, depending on the grant you are using.

Data Type Changes In ‘data’ Fields

FusionAuth provides data fields on many types of objects:

• Applications
• Tenants
• Groups
• Users
• Registrations
• Consents

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. This must be enforced by any software that updates these fields. There’s an open GitHub issue to allow FusionAuth to enforce the Elasticsearch schema.

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.

Dates that are stored in the data field must be valid. Dates such as “0000-00-00” will fail to parse, for example. Some databases will return that value for invalid timestamps. When setting data values, invalid dates should be set to null to keep the schema valid.

If you do not enforce the schema, objects will be mysteriously hidden from searches. It can also result in a MapperParsingException.

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 using SCIM. Bulk operations on users, such as addition and deletion, 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. See Limitations for more information.

You cannot create a FusionAuth Registration for a user provisioned with SCIM directly during the provisioning process. See Adding Registrations for workarounds.

While it is not enforced, or a hard limitation, it is recommended to configure at most one SCIM client per tenant. While you can have multiple SCIM clients configured to provision users in one FusionAuth tenant, at the end of the day you only have one user data store in each tenant. Conflicts with creation, updates and deletion could happen; they won’t be automatically resolved by FusionAuth. If you need multiple SCIM clients provisioning users into a single tenant, ensure you handle conflicts.

Okay, okay, you want multiple SCIM clients to provision users into a single FusionAuth tenant. Let’s talk about the complexities. Imagine you have an Okta SCIM client provisioning users into a FusionAuth tenant and an Azure AD/Microsoft Entra ID SCIM client provisioning users into the same tenant.

Issues with this approach include:

• The user and group lambdas would have to include logic to differentiate between a user from Okta and a user from Azure AD/Microsoft Entra ID and handle the fields differently. The incoming SCIM request does not include information about the source, but you might be able to examine an email domain or a marker attribute to determine where the user was coming from.
• User collisions are not handled by FusionAuth. If the Okta SCIM client created an account for a user with the email address richard@example.com in the tenant, then later the Azure AD SCIM client tried to create an account for a user with the email address richard@example.com, the second account creation would fail. One workaround would be for the lambda to resolve the collision, for example by adding a suffix or prefix to make the email address unique.
• Update or deletion requests from the Okta SCIM client could modify users created by the Azure AD SCIM client and vice versa.
• The bearer access token used to authenticate each SCIM client can be different, but they must have the same lifetime, since that is configured at the Entity Type level. You couldn’t have Okta’s credentials be valid for a year but Azure AD’s credentials be valid for six months.

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.

Terraform Limitations

You must create an API key either manually or via Kickstart. There is no way to create the initial API key using Terraform.

The Terraform implementation is not currently at parity with the client libraries and the REST API. If you run into any discrepancies that affect your usages, please open a GitHub issue.

Identity Provider Limitations

Some Identity Providers, such as the Google and OIDC Identity Providers, request access tokens from a configured remote URL. Remote servers must respond within a certain time frame or the login workflow will fail.

The limit is currently 10 seconds. It is not configurable.

Group Limitations

Groups can only contain Users, not other Groups.

Groups are always contained within a Tenant, and cannot span Tenants.

Admin Custom Forms

You cannot display different forms to different types of users. If required, the best option is to use the various APIs and build your own forms. You can use the Form Field and Form APIs to manage the fields and forms.

Custom field labels in the admin UI, like other parts of it, cannot be localized.

All custom fields are always viewable in the User data tab. Encrypt any data stored in a custom data field that should not be viewable to an admin user.

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