fusionauth logo
search-interface-symbol
Quickstarts
API Docs
SDK
search-interface-symbol
talk to an expert
Log In
talk to an expert
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
      • Ruby on Rails
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    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.

    Maximum Users Returned Workarounds

    You can work around the user search limit by writing one or more search queries to return less than 10000 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.

    • 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

    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.

    Prior to version 1.28.0, FusionAuth supported two NameIDPolicy values, both of which result in user.email being used for the name Id:

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

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

    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.

    Prior to version 1.28.0, FusionAuth only supported using the name Id for the user’s email address.

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

    Configuration setting Currently allowed value

    authenticator.algorithm

    HmacSHA1

    authenticator.codeLength

    6

    authenticator.timeStep

    30

    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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Blog
    Expert Advice
    Download
    Subscribe for developer updates