Overview

FusionAuth is all about users, and it is helpful to fully understand how FusionAuth understands users to fully leverage all of the features FusionAuth offers.

The user itself is easy enough to understand; it represents your end user, your employee, or your client.

Here’s a brief video covering some aspects of users:

Core Concepts Relationships

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

Belongs To
Belongs To
Belongs To
Assigned
Defined In
Is In
Joins
Joins
Assigned
User
Tenant
Application
Group
Role
Registration

Admin UI

This page describes the admin UI for creating and managing users.

List of Users

To display a list of users, navigate to Users.

List of Users

Using the icons on this screen, you can:

  • Manage the user’s profile
  • Lock the user
  • Unlock the user

If you have user selected, you can also:

  • Add the users to a group
  • Remove the users from a group

You can search for users using the search field. Learn more about User Search .

Add a User

To add a new user, navigate to Users.

Form Fields

These are the default fields that are available when creating a user. You can add additional fields by creating custom forms and fields. See the Editing User Data In the admin UI documentation for more information.

Tenantrequired

The tenant to which this user belongs. This field is only displayed once multiple tenants exist in FusionAuth. When only a single tenant exists, the user will always be created in the default tenant.

Skip email verification

If this is checked, FusionAuth will not send an email asking the user to verify their email address. This is only available if Email verification in the tenant is set up.

Email

The email address of the user. This is a required field if Send email to set up password is enabled. It must be unique across all users in the tenant.

Username

The username of the user. The username is stored and returned as a case-sensitive value, however, a username is considered unique regardless of the case. This is a required field if no Email is provided.

Mobile phone

The mobile phone number of the user. This is useful for sending push notifications or SMS messages to the user.

Send email to set up password

If this is checked, FusionAuth will send an email asking them to set their password. If you also have email verification enabled and do not skip verification with Skip email verification setting, only the setup password email will be sent to the user. Setting up the password using the email sent during this user create operation will verify the user’s email if it is not already verified. This is only available if the Setup password option in the tenant Template settings is set up.

Passwordrequired

The password of the user. This field is only displayed if Send email to set up password is not enabled.

Confirm passwordrequired

Password confirmation field. You must enter the same value in both Password and Confirm password . This field is only displayed if Send email to set up password is not enabled.

Options
Birthdate

The birthdate of the user.

First name

The first name of the user.

Middle name

The middle name of the user.

Last name

The last name of the user.

Full name

The full name of the user as a separate field that is not calculated from firstName and lastName .

Languages

The preferred languages of the user. These are important for email templates and other localizable text. See Locales for the list and Localization and Internationalization for more on how they are used.

Timezone

The preferred timezone of the user.

Image URL

The URL that points to an image file that is the user’s profile image.

Edit a User

To edit a user, navigate to Users and click the Manage button next to the user you wish to edit.

In the top right corner of the page, you will see a dropdown menu with the following options:

  • Edit user Edit the user’s profile information.
  • Add a comment Add a comment to the user’s profile. This will be visible in the user’s History .
  • Action User Perform a user action on the user. See Current actions for more information.
  • Delete user Delete the user. You will have to confirm this action, because it is permanent and cannot be undone.
  • Lock account Lock the user’s account. Only available if the user is not already locked.
  • Unlock account Unlock the user’s account. Only available if the user is locked.
  • Send password reset Send a password reset email to the user. Only available if the user has an email address.
  • Require password change The user will be required to change their password the next time they log in.
User edit dropdown in the administrative user interface.

Additionally, a lock icon is displayed in the top right corner of the profile. If the user is unlocked, the icon will be green. If the user is locked, the icon and the top border of the profile will be red. Clicking on the icon will lock or unlock the user.

Locked user in the administrative user interface.

Registrations

Applications in FusionAuth represent something you can log in to. They are tenant scoped. You associate a user with an application via a registration. You may also optionally associate one or more roles with each user’s registration.

An example use case is a single company, where you have a forum, a todo application, and an accounting application. If you have three users, Richard, Monica, and Jared, you can grant Richard access to all three applications, Monica access to the forum and todo applications, and Jared access to the accounting application.

Prohibit a user from logging into an application for which they are not registered by checking the claims in the token or enabling the Require registration setting for the application.

Applications also may have associated identity providers, such as Google or OIDC providers. When so configured, a user may log in to an application with the identity provider.

Every user object contains an array of application registrations. You can search for all users with a given registration.

Learn more about Applications.

User registrations in the administrative user interface.

Table Columns

Applicationrequired

The application to which this registration belongs.

Username

The username of the user for this application. This username cannot be used to log in. It is for display purposes only.

Roles

The roles assigned to the user on the application.

Created

The date and time this registration was created.

Last updated

The date and time this registration was last updated.

Last login

The date and time that the user last logged into the application for this registration.

Action

The action to take on this registration. The available actions are:

  • Edit the registration
  • View the registration
  • Delete the registration

Multi-Factor

The multi-factor tab allows you to view and remove the multi-factor authentication settings for a user.

Learn more about Multi-Factor Authentication (MFA).

User multi-factor screen in the administrative user interface.

Table Columns

Methodrequired

The method of multi-factor authentication:

  • Authenticator App
  • Email
  • SMS
Transport

The receiver address used for the multi-factor authentication method. This address does not have to be the same as the Email or Mobile phone of the user. The value depends on the Method :

  • Email address
  • Phone number
Identifier

The Id of the multi-factor authentication method.

Last used

Indicates which multi-factor authentication method was last used.

Action

You can disable multi-factor authentication for a user by clicking the button.

Passkeys

The passkeys tab allows you to manage the registered passkeys for a user.

Learn more about WebAuthn and passkeys.

User passkeys screen in the administrative user interface.

Table Columns

Display namerequired

The display name for the passkey selected during registration. The user should have selected this value.

Namerequired

A unique name meant to disambiguate passkeys with the same Display name .

Idrequired

The unique Id of the passkey.

Created

The date and time when the passkey was created.

Last used

The date and time when the passkey was last used.

Action

You can view and delete a passkey by clicking the or buttons.

Families

The families tab allows you to view the families to which a user belongs.

A family is a collection of users that are related to each other. For example, a family may consist of a parent and their children.

User families screen in the administrative user interface.

Table Columns

Namerequired

The avatar and name of the user in the family.

Role

The roles assigned to the user on the family. Possible values are:

  • Adult
  • Child
  • Teen
Agerequired

The age of the user. This is calculated from the Birthdate .

Family

The family Id to which this relationship belongs.

Added on

The date and time when the user was added to the family.

Action

You can navigate to the user’s profile by clicking the button.

Linked accounts

The linked accounts tab allows you to manage the Identity Provider accounts which have been linked for this user.

Learn more about Identity Providers and Identity Provider links.

User identity providers screen in the administrative user interface.

Table Columns

Display namerequired

The display name of the linked account.

Identity Providerrequired

The identity provider to which this linked account belongs.

Created

The date and time this linked account was created.

Last login

The date and time this linked account was last used to log in.

Action

You can view and delete a linked account by clicking the or buttons.

Groups

The groups tab allows you to manage the groups for a user.

Groups are a way to group users in FusionAuth. They are tenant scoped. They may have application roles associated with them. Users with a registration for an application as well as a group membership will assume those roles upon login.

Group membership is boolean in nature. A user is either in a group or out of a group.

An example use case is a forum moderators group. The forum application can get the group memberships of any user. If the user is a member of the moderators group, the application can provide a ‘flag’ button on the forum software.

Every user object contains an array of group memberships. You can search for all users with a given group membership.

To get the group names of memberships for a user, you must use FusionAuth’s proprietary APIs. Group names are not included in the user object.

Learn more about Groups.

User groups screen in the administrative user interface.

Table Columns

Grouprequired

The group to which the user belongs.

Member Id

The unique Id of this group member. This is not the user Id, but a unique Id for the membership.

Createdrequired

The date and time this membership was created.

Action

You can view and delete a group membership by clicking the or buttons.

Entity grants

The entity grants tab allows you to manage the entity grants for a user.

Entities and grants allow you to model fine-grained permissions in a flexible manner. Entities are things, while grants are expressions of permissions granted to a user or thing to another thing. Entities have configurable permissions. Entities are a good fit when you have users that may need access to different assets which can’t be easily modeled as applications.

An example use case which could be modeled using entities is GitHub organizations. A user can belong to zero or more GitHub organizations and have different access levels in each one. But a user logs in to GitHub, not to a GitHub organization. Additionally, permissions will vary between organizations. A user may be an admin in one GitHub organization and have read-only access in another one. To implement this, you’d represent each GitHub organization as an entity in FusionAuth, and grant users permissions to each organization of which they are a member.

It is very common to have an interstitial page when using entities. (This page is custom-built and is not provided by FusionAuth.) The user logs in to an application, and is then presented with a list of entities to which they’ve been granted permissions. The user selects an entity and then acts within the confines of that entity.

You can search for all users granted access to a given entity. You can search for all entities for which a user has a grant.

To search for grants on a user, you must use FusionAuth’s proprietary APIs. Additionally, since entities cannot be ‘logged into’, they don’t have any relationship with external identity providers.

Learn more about Entities and Grants.

User entity grants screen in the administrative user interface.

Table Columns

Idrequired

The Id of the grant.

Namerequired

The name of the entity.

Typerequired

The type of the entity.

Entity Idrequired

The Id of the target entity.

Permissionsrequired

The set of permissions of this grant.

Created

The date and time the grant was created.

Action

You can edit and delete a grant by clicking the or buttons.

Entities Compared to Applications

Entities, grants, and permissions are analogous to applications, registrations, and roles, but you can’t log into an entity.

Entities may also be useful if you have two or more applications in FusionAuth, but you want to group access in an orthogonal way while still allowing users to assume different roles.

Suppose you have a point of sales application and a scheduling application for your retail chain. You have ten stores. You want to allow employees to log in to each of these applications, but you want to limit them to access only stores where they are currently working. But if they move between stores to cover for a shift or because of a transfer, you want to handle that use case as well. This means you can’t use tenants to model stores.

You could model the point of sales and scheduling applications as applications. Each store would be an entity, and after the user has logged into an application, you’d show them the stores to which they’d have access.

You could also provide different roles in different stores. The scheduling software could know that Richard would have access to the scheduling application as a manager for store A, but only as an employee for store B.

If you were to model this using only applications, you’d have to have twenty applications in FusionAuth (two for each store) and keeping those configurations synchronized might be difficult. And if you added more applications or stores, you’d face a combinatorial explosion of applications.

Recent logins

The recent logins tab allows you to view the recent logins for a user. This includes when the user logged in, the IP address, and the application.

User recent logins screen in the administrative user interface.

Table Columns

Applicationrequired

The application the user logged in to. If -, the user logged in to the tenant, but not to a specific application. This can occur when no application Id is provided, or if the user is not registered for the application.

Time

The date and time when the login occurred.

IP Addressrequired

The recorded IP address for this login record.

The consent tab allows you to manage the consent for a user.

A FusionAuth consent is a definition of a permission that can be given to a user. At a minimum a consent has a name, and defines the minimum age of self-consent. A consent can then be granted to a user from a family member, or optionally, a user may self-consent if they meet the minimum age defined by the consent.

Learn more about Family API with Consents.

User consents screen in the administrative user interface.

Table Columns

Namerequired

The name of the consent.

Valuesrequired

The values of the consent.

Statusrequired

The status of the consent.

Given on

The date and time this consent was given.

Given byrequired

The Id of the user who gave this consent.

Action

You can edit and revoke a consent by clicking the or buttons.

Sessions

Users have sessions in FusionAuth. Sessions are equivalent to refresh tokens. Their lifetime is controlled by the tenant or application refresh token settings.

These appear in the administrative user interface under the Sessions tab (you may need to scroll if your screen is small):

User session screen in the administrative user interface.

There are two primary types of sessions/tokens shown in this table:

  • Normal refresh tokens.
  • SSO token. While technically a refresh token, it is special and fully managed by FusionAuth. You may safely ignore this.

With Delete all session button, you can revoke all sessions for a user. This is useful if you want to force a user to log in again.

Session Details

A session can be created by using the Login API, as long as Generate refresh tokens is enabled, or by completing the OAuth Authorization Code grant when the offline_access scope is requested.

A session will end when:

  • It expires.
  • It is deleted using the JWT APIs.
  • Optionally, as a result of a user changing their password or having their account locked.

These can be configured in the Tenant Refresh Token settings or the Application Refresh Token settings.

An SSO session will end if you log out of SSO.

Normal sessions are not ended, nor are associated refresh tokens revoked, by front channel logout.

When a session is no longer valid, the associated refresh token can’t be used to create new JWTs.

The JWTs themselves are valid until they expire.

Table Columns

Namerequired

The name of the session.

Typerequired

The type of the session.

IP addressrequired

The IP address of the client that initiated this session.

Applicationrequired

The application to which this session belongs.

Created

The date and time this session was created.

Last Accessed

The date and time this session was last accessed.

Expirationrequired

The date and time this session will expire.

Action

You can revoke a session by clicking the button.

Current actions

The current actions tab allows you to view user actions that are currently in effect for this user. User actions can be used to flag a user, send emails and webhook notifications when they buy temporary access to a resource, or when they are temporarily locked out of their account.

See Using FusionAuth User Actions for more information about user Actions.

User current actions screen in the administrative user interface.

Table Columns

Actionrequired

The action that is currently taken on the user. If a reason was provided, it will be appended to the action name.

Commentrequired

The comment left by the actioner.

Startrequired

The date and time this action was started.

Expirationrequired

The date and time this action will expire.

Actioning userrequired

The user that is taking the action on the user.

Actioning user idrequired

The Id of the user that is taking the action on the user.

Action

You can modify and cancel an action by clicking the or buttons.

History

The history tab allows you to view expired user actions. Comments are also displayed here.

User history screen in the administrative user interface.

Table Columns

Actionrequired

The action that was taken on the user. If a reason was provided, it will be appended to the action name.

Commentrequired

The comment left by the actioner.

Startrequired

The date and time this action was started.

Expirationrequired

The date and time this action expired.

Actioning userrequired

The user that was taking the action on the user.

Actioning user idrequired

The Id of the user that was taking the action on the user.

User data

The user data tab allows you to view the user data for a user.

User data is a key value store that allows you to store arbitrary data about a user. This data is not used by FusionAuth, it is simply stored and returned when the user is retrieved. FusionAuth does not provide a UI for managing user data. It is intended to be used by your application utilizing the API.

User data screen in the administrative user interface.

Source

The source tab allows you to view the user account as read-only JSON. This is equivalent to retrieving the user via the User API. This is useful for debugging and troubleshooting.

User source screen in the administrative user interface.

User Scope

A user is scoped to a tenant.

Each FusionAuth tenant is a logical grouping of users, configurations, and applications. This means a user with the same identifier (email, username, etc.) in two different tenants is a different user. They can have different passwords, different identity provider links, and different attributes. You can search for users across tenants using the User Search API.

An example use case is a private label todo SaaS application, where you want a user to sign up for two or more different instances of your SaaS and not know that there is a shared identity store behind them. For example, richard@piedpiper.com can sign up for the Pied Piper Todo application and the Hooli Todo Application with the same email address, but different passwords, MFA methods, and more.

One issue is that if you have admin users, such as customer support representatives, which need cross-tenant access, you can’t keep their accounts in sync. One option is to set up an administrative identity server, whether that is a second instance of FusionAuth, Google GSuite, or Azure AD/Microsoft Entra ID. Have the customer service representatives authenticate with it.

Learn more about Tenants.

What Makes a User Active

FusionAuth includes reporting on the number of daily and monthly active users. What makes a user active during a time period is any of these events:

  • A user is created.
  • A user logs in.
  • The Login Ping API is used.
  • A JWT is refreshed using a refresh token.
  • A user is registered for an application.
  • SSO is used; this calls the login ping.

Users imported with the User Import API do not count as a monthly active user (MAU).

Users whose profile data is updated via the User Update API do not count as an MAU either.

There are many different ways to log in using FusionAuth, but all of the below trigger a login event:

  • A login is completed using any Login API (normal, one-time, passwordless, Identity Provider, Connector).
  • A User is created with a password, whether self service or using the Registration API.
  • A Refresh Token is exchanged for a JWT.
  • A 2FA login is completed.

As of version 1.16.0, FusionAuth ships with a database search engine as the default.

By selecting the appropriate installation guide, one can easily create a configuration with Elasticsearch pre-enabled.

You can read more about the database and other search engines in the search core concepts section.

User search requests may be made through the User Search API or within the FusionAuth admin UI under Users.

Configuration

Please see our search core concepts section for additional information on basic configuration. The remainder of this section will cover specifics as it relates to users and search.

Database Search Engine

This configuration is lightweight, simplifies installation and system complexity, but comes with the tradeoffs of limited search capabilities and performance implications.

The database search engine enables fuzzy search against the following fields of the user:

  • firstName
  • lastName
  • fullName
  • email
  • username
User Search with Database Search Engine

To learn more about the database search engine in general, view the search core concepts section.

Elasticsearch Search Engine

Leveraging Elasticsearch for the user search engine enables advanced search capabilities on more numerous and granular data and a performance improvement for user search.

Advanced Search UI

FusionAuth provides an advanced user search interface that reveals how you may construct queryString and query parameters for the User Search API and [User Bulk Delete API] with desired results. Navigate to Users from the left navigation and click on the Advanced link below the Search input field to begin. The uielement#Advanced# portion of this UI is available when the search engine type is configured to elasticsearch.

We provide selectors for common search fields, as well as a free-form search field for constructing complex search queries. By selecting the Show Elasticsearch query toggle, you will see either the Elasticsearch query string or JSON search query that can be used as queryString and query parameters for the User Search API and User Bulk Delete API.

Additionally, you may enter Elasticsearch query strings or raw JSON queries into the search field for testing purposes.

The following screenshot shows a query string being constructed to search for users that belong to the Moderators group and are in the Default tenant:

User Search by Query String

When searching for users by application or any fields on an application, it is necessary to construct a JSON query due to the way the Elasticsearch mapping is defined.

The following screenshot shows an Elasticsearch JSON query being constructed to search for users that match the email pattern *@fusionauth.io, are registered to the Pied Piper application, and are assigned the dev role:

User Search with JSON Query.

To learn more about the Elasticsearch search engine in general, view the Elasticsearch search guide.

Prior to version 1.48.0 if you attempted to page past 10,000 results in the admin UI you would encounter an error.

Starting in version 1.48.0 you are able to page past the 10,000 results limit one page at a time.

When there are more than 10,000 results when using the Elasticsearch engine you have the option to navigate past the limit, however you may only do so one page at a time.

User Search with over 10,000 results first page.

Clicking on the Last pagination button will take you to the page with the 10,000th result. You will then have the option to click on the Next button to continue paging forward.

User Search with over 10,000 results paged to 10,000.

You may continue to page forward using Next until you reach the last of the search results.

User Search with over 10,000 results paged to end.

For more information see Extended Pagination

Limitations On Changing Data Field Types

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.

Segmenting Users

Often you want to segment or separate your users. You have options to do so in FusionAuth. They each have different tradeoffs. The options are:

Tenants

Each FusionAuth tenant is a logical grouping of users, configuration and applications. Users are tenant scoped. This means a user with the same identifier (email, username, etc) in two different tenants is a different user. They can have different passwords, different identity provider links and different attributes. You can search for users across tenants using the User Search API.

An example use case is a private label todo SaaS application, where you want a user to sign up for two or more different instances of your SaaS and not know that there is a shared identity store behind them. For example, richard@piedpiper.com can sign up for the Pied Piper Todo application and the Hooli Todo Application with the same email address, but different passwords, MFA methods and more.

One issue is that if you have admin users, such as customer support representatives, which need cross-tenant access, you can’t keep their accounts in sync. One option is to set up an administrative identity server, whether that is a second instance of FusionAuth, Google GSuite, or Azure AD/Microsoft Entra ID. Have the customer service representatives authenticate with it.

Learn more about Tenants.

Applications and Registrations

Applications in FusionAuth represent something you can log in to. They are tenant scoped. You associate a user with an application via a registration. You may also optionally associate one or more roles with each user’s registration.

An example use case is a single company, where you have a forum, a todo application and an accounting application. If you have three users, Richard, Monica and Jared, you can grant Richard access to all three applications, Monica access to the forum and todo applications, and Jared access to the accounting application.

Prohibit a user from logging into an application for which they are not registered by checking the claims in the token or enabling the Require registration setting for the application.

Applications also may have associated Identity Providers, such as Google or OIDC providers. When so configured, a user may log in to an application with the Identity Provider.

Every user object contains an array of application registrations. You can search for all users with a given registration.

Learn more about Applications.

Groups

Groups are a way to group users in FusionAuth. They are tenant scoped. They may have application roles associated with them. Users with a registration for an application as well as a group membership will assume those roles upon login.

Group membership is boolean in nature. A user is either in a group or out of a group.

An example use case is a forum moderators group. The forum application can get the group memberships of any user. If the user is a member of the moderators group, the application can provide a ‘flag’ button on the forum software.

Every user object contains an array of group memberships. You can search for all users with a given group memberships.

One issue is that to get the group names of memberships for a user, you must use FusionAuth’s proprietary APIs. Group names are not included in the user object.

Learn more about Groups.

Entities and Grants

Entities and grants allow you to model fine grained permissions in a flexible manner. Entities are things, while grants are expressions of permissions granted to a user or thing to another thing. Entities have configurable permissions. Entities are a good fit when you have users that may need access to different assets which can’t be easily modeled as applications.

An example use case which could be modeled using entities is GitHub organizations. A user can belong to zero or more GitHub organizations and have different access levels in each one. But a user logs in to GitHub, not to a GitHub organization. Additionally, permissions will vary between organizations. A user may be an admin in one GitHub organization and have read-only access in another one. To implement this, you’d represent each GitHub organization as an entity in FusionAuth, and grant users permissions to each organization of which they are a member.

It is very common to have an interstitial page when using entities. (This page is custom built and is not provided by FusionAuth.) The user logs in to an application, and is then presented with a list of entities to which they’ve been granted permissions. The user selects an entity and then acts within the confines of that entity.

You can search for all users granted access to a given entity. You can search for all entities for which a user has a grant.

One issue is that to search for grants on a user, you must use FusionAuth’s proprietary APIs. Additionally, since entities cannot be ‘logged into’, they don’t have any relationship with external Identity Providers.

Learn more about Entities and Grants.

Entities Compared to Applications

Entities, grants and permissions are analogous to applications, registrations and roles, but you can’t log into an entity.

Entities may also be useful if you have two or more applications in FusionAuth, but you want to group access in an orthogonal way while still allowing users to assume different roles.

Suppose you have a point of sales application and a scheduling application for your retail chain. You have ten stores. You want to allow employees to log in to each of these applications, but you want to limit them to access only stores where they are currently working. But if they move between stores to cover for a shift or because of a transfer, you want to handle that use case as well. This means you can’t use tenants to model stores.

You could model the point of sales and scheduling applications as applications. Each store would be an entity, and after the user has logged into an application, you’d show them the stores to which they’d have access.

You could also provide different roles in different stores. The scheduling software could know that Richard would have access to the scheduling application as a manager for store A but only as an employee for store B.

If you were to model this using only applications, you’d have to have twenty applications in FusionAuth (two for each store) and keeping those configurations synchronized might be difficult. And if you added more applications or stores, you’d face a combinatorial explosion of applications.

The user.data Field

You can add arbitrary JSON to the user.data field, such as org_type and org_id fields. You can do this using the User API on user creation.

The user.data fields can then be read in a JWT Populate Lambda and pushed into the tokens generated during authentication.

The downstream application can examine the tokens and determine which organizations a user has access to.

A variant of this is using Lambda HTTP Connect which can pass a user Id to an external service during authentication and retrieve user attributes such as an org_id. This has the advantage of avoiding synchronization at the cost of requiring a paid plan and increased latency during the authentication event. The exact amount of latency depends on the responsiveness of the called API.

This approach works well when you want FusionAuth to handle authentication but keep all user segmentation logic in your application.

The user.data Schema

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.