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 search requests may be made through the User Search API or within the FusionAuth admin UI under Users.

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

Configuration

See the fusionauth-app.search-engine-type and fusionauth-app.search-servers properties, as well as the FUSIONAUTH_SEARCH_ENGINE_TYPE and FUSIONAUTH_SEARCH_SERVERS environment variables definitions of the Configuration Reference for details on configuring the search engine and (optional) Elasticsearch integration.

If you are running FusionAuth in a Docker environment, see the Using FusionAuth on Docker documentation for an example configuring Elasticsearch as the user search engine.

You may view the configured search engine type in the FusionAuth admin UI by navigating to System → About.

About - Search Engine Type

You may also switch between the different search engines.

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 is appropriate for systems that are not dependent on the User Search APIs, is not expected to have a large number of active users, and may be running in an embedded environment.

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

  • firstName

  • lastName

  • fullName

  • email

  • username

User Search with Database Search Engine

Limitations

can you search for a value starting or ending with a certain string (prefix/suffix) ? is the search case sensitive? how are strings containing whitespaces supported? can you use quotes? can regular expressions be used?

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.

The Elasticsearch search engine is appropriate for systems that are dependent on the User Search APIs, are expected to have a large number of active users, and requires a more tactical search than is provided by the database search engine.

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

User Search by JSON Query

Advanced search UI

Reindex

It is possible, though rare, for an Elasticsearch index to become out of sync with the database. If you stand up FusionAuth with a database dump and restore, you may need to run this operation. You may also be instructed to do so by FusionAuth support.

However, in general, even if a temporary outage occurs with Elasticsearch, the index will be sync up automatically. Reindexing is an expensive operation, especially if your system has a large number of users, so it should not be run unless necessary.

If you do need to run this, navigate to System → Reindex in the FusionAuth admin UI to initiate a reindex of all users. This navigation item will only be displayed when the search engine is Elasticsearch.