[[_user-storage-federation]]

== User Storage Federation

Many companies have existing user databases that hold information about users and their passwords or other credentials.
In may cases, it is just not possible to migrate off of those existing stores to a pure {project_name} deployment.
{project_name} can federate existing external user databases.
Out of the box we have support for LDAP and Active Directory.  You can also code your own extension for any custom
user databases you might have using our User Storage SPI.

The way it works is that when a user logs in, {project_name} will look into its own internal user store to find the user.
If it can't find it there it will iterate
over every User Storage provider you have configured for the realm until it finds a match.  Data from the external store is mapped into a common user model that is consumed by the {project_name}
runtime.  This common user model can then be mapped to OIDC token claims and SAML assertion attributes.

External user databases rarely have every piece of data need to support all the features that {project_name} has.
In this case, the User Storage Provider can opt to store some things locally in the {project_name} user store.
Some providers even import the user locally and sync periodically with the external store.  All this depends on the capabilities of the provider and how its configured.  For example, your
external user store may not support OTP.  Depending on the provider, this OTP can be handled and stored by {project_name}.

=== Adding a Provider

To add a storage provider go to the `User Federation` left menu item in the Admin Console.

.User Federation
image:{project_images}/user-federation.png[]

On the center, there is an `Add Provider` list box.  Choose the provider type you want to add and you will be brought to the configuration page of that provider.

=== Dealing with Provider Failures

If a User Storage Provider fails, that is, if your LDAP server is down, you may have trouble logging in and may not be able to view users in the admin console.
{project_name} does not catch failures when using a Storage Provider to lookup a user.  It will abort the invocation.  So, if you have a Storage Provider with a higher
priority that fails during user lookup, the login or user query will fail entirely with an exception and abort.  It will not fail over to the next configured provider.

The local {project_name} user database is always searched first to resolve users before any LDAP or custom User Storage Provider.
You may want to consider creating an admin account that is stored in the local {project_name} user database just in case any problems come up in connecting
to your LDAP and custom back ends.

Each LDAP and custom User Storage Provider has an `enable` switch on its admin console page.  Disabling the User Storage Provider will skip the provider when
doing user queries so that you can view and login with users that might be stored in a different provider with lower priority.  If your provider is using an
`import` strategy and you disable it, imported users are still available for lookup, but only in read only mode.  You will not be able to modify these users until
you re-enable the provider.

The reason why {project_name} does not fail over if a Storage Provider lookup fails is that user databases often have duplicate usernames or duplicate emails between them.
This can cause security issues and unforeseen problems as the user may be loaded from one external store when the admin is expecting the user to be loaded from another.