Users

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.

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.

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.

Options

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.

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.

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.

Table Columns

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

Table Columns

Passkeys

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

Learn more about WebAuthn and passkeys.

Table Columns

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.

Table Columns

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.

Table Columns

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.

Table Columns

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.

Table Columns

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.

Table Columns

Consent

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.

Table Columns

Sessions

Users have sessions in FusionAuth. Sessions are represented by 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):

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 sessions button, you can revoke all sessions for a user. This is useful if you want to force a user to log in again.

Learn more about sessions and logging out.

Table Columns

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.

Table Columns

History

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

Table Columns

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.

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

If you have admin users which need cross-tenant access, it can be a challenge to keep their accounts in sync. You can use the API to sync up profile attributes, but some user fields like passwords cannot be retrieved via the API. This can be a challenge for cross-tenant admin users like customer support representatives.

In this situation, you can:

• Have users reset their password every time they need access to a different tenant.
• Use a passwordless login option like a magic link or passkey.
• Set up or use an administrative identity server, such as a second instance of FusionAuth, Google GSuite, or Azure AD/Microsoft Entra, and have these users log in using that.
• Put all admin users in one FusionAuth tenant, create an application in that tenant, and set up an OIDC Identity Provider for applications in other tenants to delegate to that application.

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.

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.

User Search

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

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

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:

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

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.

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.

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

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 tradeoffs. Here’s a table with the strengths and challenges of each option.

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 account. They can have different passwords, identity provider links and profile attributes. You can search for users across tenants using the [User Search API)(/docs/apis/users#search-for-users).

An example use case is a private label SaaS application for managing todos and tasks. You want a user to sign up for two or more different instances of your SaaS and never 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.

If you have admin users which need cross-tenant access, it can be a challenge to keep their accounts in sync. You can use the API to sync up profile attributes, but some user fields like passwords cannot be retrieved via the API. This can be a challenge for cross-tenant admin users like customer support representatives.

In this situation, you can:

• Have users reset their password every time they need access to a different tenant.
• Use a passwordless login option like a magic link or passkey.
• Set up or use an administrative identity server, such as a second instance of FusionAuth, Google GSuite, or Azure AD/Microsoft Entra, and have these users log in using that.
• Put all admin users in one FusionAuth tenant, create an application in that tenant, and set up an OIDC Identity Provider for applications in other tenants to delegate to that application.

Learn more about Tenants.

Applications and Registrations

Applications in FusionAuth are anything a user can log in to: mobile applications, webapps, COTS applications, APIs and desktop applications. Applications are tenant scoped. You associate a user with an application using 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.

Prevent a user from logging into an application for which they are not registered by checking the claims in the token and 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 interacts with the permissions they have been granted to 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.

Entities Compared to Applications

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

Entities may also be useful if you have two or more applications in FusionAuth, but you want to control 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.

To solve this, 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.

With entities, you can give users different levels of access in different stores. The scheduling software can query the FusionAuth API or examine the token and allow Richard 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 need twenty applications in FusionAuth (two for each store). Keeping those configurations synchronized might be difficult. And if you added more applications, you’d face a combinatorial explosion of applications.

The user.data Field

You can add arbitrary JSON to the user.data field. You can do this using the User API, in the admin UI with custom admin forms or allow users to do so using self-service account management. The user.data fields can be read in a JWT Populate Lambda and pushed into the tokens generated during authentication.

The downstream application can examine the tokens and determine access.

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. This has the advantage of avoiding synchronization at the cost of increased latency during the authentication event. The exact amount of latency depends on API responsiveness.

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

An example use case for user.data is if you have custom authorization logic in your application based on user profile data such as org_id and org_type. At authentication time, push these attributes into your token using a JWT populate lambda. Then pass the token to your client, and have the client present the token to your application. The application can then examine the org_id and org_type profile attributes and make an authorization decision based on that custom logic.

Learn more about Searching user data and the JWT Populate Lambda.

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.