46 lines
3.5 KiB
Text
46 lines
3.5 KiB
Text
[[_user-storage-federation]]
|
|
|
|
== User Storage Federation
|
|
|
|
Many companies have existing user databases that hold information about users and their passwords or other credentials.
|
|
In many 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 needed 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.
|