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:

    User Scope

    A User is scoped to a Tenant. A User existing within a Tenant can be registered to, and use the same credentials to authenticate to multiple applications within that Tenant.

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

    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.

    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 trade offs 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 "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.

    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 four options to do so in FusionAuth. They each have different tradeoffs. The options are:

    • Tenants

    • Applications and Registrations

    • Groups

    • Entities and Grants

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

    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.