libre.sh/keycloak-scim
4
0
Fork 0
Code Issues 15 Pull requests Releases 1 Activity Actions

KEYCLOAK-15749 Rewords SSSD (#48) Minor edit

Browse source 
* KEYCLOAK-15749 Rewords SSSD

* KEYCLOAK-15749 Post feedback changes

* more post feedback changes
This commit is contained in:
Brian Dooley 2021-02-25 20:16:54 +00:00 committed by Marek Posolda
parent 10ecbfe1db
commit bb767dcb62
4 changed files with 208 additions and 236 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
server_admin/topics/user-federation.adoc
View file

@ -2,45 +2,30 @@
== Using external storage
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.
By default, we support LDAP and Active Directory, but you can also code your own extension for any custom
user database using our User Storage SPI.
[role="_abstract"]
Organizations can have databases containing information, passwords, and other credentials. Typically, you cannot migrate existing data storage to a {project_name} deployment so {project_name} can federate existing external user databases. {project_name} supports LDAP and Active Directory, but you can also code extensions for any custom user database by using the {project_name} 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 cannot 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.
When a user attempts to log in, {project_name} examines that user's storage to find that user. If {project_name} does not find the user, {project_name} iterates over each User Storage provider for the realm until it finds a match. Data from the external data storage then maps into a standard user model the {project_name} runtime consumes. This user model then maps 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.
Therefore, 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. This approach depends on the capabilities of the provider and how it is 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}.
External user databases rarely have the data necessary to support all the features of {project_name}, so the User Storage Provider can opt to store items locally in {project_name} user data storage. Providers can import users locally and sync periodically with external data storage. This approach depends on the capabilities of the provider and the configuration of the provider. For example, your external user data storage may not support OTP. The OTP can be handled and stored by {project_name}, depending on the provider.
=== Adding a Provider
To add a storage provider, perform the following procedure:
To add a storage provider go to the `User Federation` left menu item in the Admin Console.
.Procedure
. Click *User Federation* in the menu.
+
.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.
image:{project_images}/user-federation.png[User Federation]
+
. Select the provider type from the *Add Provider* list. {project_name} brings you to that provider's configuration page.
=== Dealing with Provider Failures
If a User Storage Provider fails (for example, 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.
If a User Storage Provider fails, you may not be able to log in and view users in the Admin Console. {project_name} does not detect failures when using a Storage Provider to look up a user, so it cancels the invocation. If you have a Storage Provider with a high priority that fails during user lookup, the login or user query fails with an exception and 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.
{project_name} searches the local {project_name} user database first to resolve users before any LDAP or custom User Storage Provider. Consider creating an administrator account stored in the local {project_name} user database in case of problems connecting to your LDAP and 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.
Each LDAP and custom User Storage Provider has an `enable` toggle on its Admin Console page. Disabling the User Storage Provider skips the provider when performing queries, so you can view and log in with user accounts in a different provider with lower priority. If your provider uses an `import` strategy and is disabled, imported users are still available for lookup in read-only mode.
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.
When a Storage Provider lookup fails, {project_name} does not fail over because user databases often have duplicate usernames or duplicate emails between them. Duplicate usernames and emails can cause problems because the user loads from one external data store when the admin expects them to load from another data store.

3
server_admin/topics/user-federation/custom.adoc
View file

@ -1,5 +1,4 @@
=== Custom Providers
{project_name} does have an SPI for User Storage Federation that you can use to write your own custom providers.
You can find documentation for this in our link:{developerguide_link}[{developerguide_name}].
{project_name} does have a Service Provider Interface (SPI) for User Storage Federation to develop custom providers. You can find documentation on developing customer providers in the link:{developerguide_link}[{developerguide_name}].

195
server_admin/topics/user-federation/ldap.adoc
View file

@ -1,197 +1,148 @@
[[_ldap]]
=== LDAP and Active Directory
=== Lightweight Directory Access Protocol (LDAP) and Active Directory
{project_name} comes with a built-in LDAP/AD provider. It is possible to federate multiple different LDAP servers in the same
{project_name} realm. You can map LDAP user attributes into the {project_name} common user model.
By default, it maps username, email, first name, and last name, but you are free to configure additional <<_ldap_mappers,mappings>>.
The LDAP provider also supports password validation via LDAP/AD protocols and different storage, edit, and synchronization modes.
{project_name} includes an LDAP/AD provider. You can federate multiple different LDAP servers in one {project_name} realm and map LDAP user attributes into the {project_name} common user model.
To configure a federated LDAP store go to the Admin Console.
Click on the `User Federation` left menu option.
When you get to this page there is an `Add Provider` select box.
You should see _ldap_ within this list.
Selecting _ldap_ will bring you to the LDAP configuration page.
By default, {project_name} maps the username, email, first name, and last name of the user account, but you can also configure additional <<_ldap_mappers,mappings>>. {project_name}'s LDAP/AD provider supports password validation using LDAP/AD protocols and storage, edit, and synchronization modes.
==== Configuring Federated LDAP Storage
.Procedure
. Click *User Federation* in the menu.
+
.User Federation
image:{project_images}/user-federation.png[User Federation]
+
. Select _ldap_ from the *Add Provider* list. {project_name} brings you to the LDAP configuration page.
==== Storage Mode
By default, {project_name} will import users from LDAP into the local {project_name} user database. This copy of the user
is either synchronized on demand, or through a periodic background task.
The single exception to this is the synchronization of passwords. Passwords are never imported. Their validation is always delegated to the LDAP server.
The benefits of this approach is that all {project_name} features will work as any extra per-user data that is needed can be stored locally.
The downside of this approach is that each time that a specific user is queried for the first time, a corresponding {project_name} database insert is performed.
The import may also have to be synchronized with your LDAP server. However, import synchronization is not necessary in
the case that the LDAP mappers are configured to always read particular attributes from the LDAP rather than from the database.
{project_name} imports users from LDAP into the local {project_name} user database. This copy of the user database synchronizes on-demand or through a periodic background task. An exception exists for synchronizing passwords. {project_name} never imports passwords. Password validation always occurs on the LDAP server.
Alternatively, you can choose not to import users into the {project_name} user database. In this case, the common user model
that the {project_name} runtime uses is backed only by the LDAP server. This means that if LDAP doesn't support
a piece of data that a {project_name} feature needs that feature will not work.
The benefit to this approach is that you do not have the overhead of importing and synchronizing a copy of the LDAP user into the
{project_name} user database.
The advantage of synchronization is that all {project_name} features work efficiently because any required extra per-user data is stored locally. The disadvantage is that each time {project_name} queries a specific user for the first time, {project_name} performs a corresponding database insert.
This storage mode is controled by the `Import Users` switch. Set to `On` to import users.
You can synchronize the import with your LDAP server. Import synchronization is unnecessary when LDAP mappers always read particular attributes from the LDAP rather than the database.
NOTE: If user import is disabled, you cannot save user profile attributes into the {project_name} database. Also you cannot save
metadata except for user profile metadata that are mapped to the LDAP. The single exception to this are user profile metadata,
which are mapped to the LDAP. This possibly includes role mappings, group mappings and other metadata based on the configuration
of your LDAP mappers.
When the attempt is made to change some of the non-LDAP mapped user data, the update of the user will not be possible. For example
you will not be able to disable the LDAP mapped user unless the `enabled` flag of the user is mapped to some LDAP
attribute (which is usually not the case).
You can use LDAP with {project_name} without importing users into the {project_name} user database. The LDAP server backs up the common user model that the {project_name} runtime uses. If LDAP does not support data that a {project_name} feature requires, that feature will not work. The advantage of this approach is that you do not have the resource usage of importing and synchronizing copies of LDAP users into the {project_name} user database.
The *Import Users* switch on the LDAP configuration page controls this storage mode. To import users, toggle this switch to *ON*.
[NOTE]
====
If you disable *Import Users*, you cannot save user profile attributes into the {project_name} database. Also, you cannot save metadata except for user profile metadata mapped to the LDAP. This metadata can include role mappings, group mappings, and other metadata based on the LDAP mappers' configuration.
When you attempt to change the non-LDAP mapped user data, the user update is not possible. For example, you cannot disable the LDAP mapped user unless the user's `enabled` flag maps to an LDAP attribute.
====
==== Edit Mode
Users, through the <<_account-service, User Account Service>>, and admins through the Admin Console
have the ability to modify user metadata. Depending on your setup you may or may not have LDAP update privileges. The
`Edit Mode` configuration option defines the edit policy you have with your LDAP store.
Users and admins can modify user metadata, users through the <<_account-service, Account Console>>, and admins through the admin console. The `Edit Mode` configuration on the LDAP configuration page defines the user's LDAP update privileges.
READONLY::
Username, email, first name, last name, and other mapped attributes will be unchangeable.
{project_name} will show an error anytime anybody tries to update these fields.
Also, password updates will not be supported.
You cannot change the username, email, first name, last name, and other mapped attributes. {project_name} shows an error anytime a user attempts to update these fields. Password updates are not supported.
WRITABLE::
Username, email, first name, last name, and other mapped attributes and passwords can all be updated and will be synchronized automatically with your LDAP store.
You cannot change the username, email, first name, last name, and other mapped attributes and passwords and synchronize them automatically with the LDAP store.
UNSYNCED::
Any changes to username, email, first name, last name, and passwords will be stored in {project_name} local storage.
It is up to you to figure out how to synchronize back to LDAP. This allows {project_name} deployments to support
updates of user metadata on a read-only LDAP server. This option only applies when you are importing users from LDAP into the local {project_name} user database.
{project_name} stores changes to the username, email, first name, last name, and passwords in {project_name} local storage, so the administrator must synchronize this data back to LDAP. In this mode, {project_name} deployments can update user metadata on read-only LDAP servers. This option also applies when importing users from LDAP into the local {project_name} user database.
NOTE: When the LDAP provider is created, the set of initial <<_ldap_mappers,LDAP mappers>> is created. The mappers are configured on a "best-effort" basis
based on the chosen combination of the `Vendor`, `Edit Mode`, and `Import Users` switches. For example in case of UNSYNCED edit mode, the mappers are pre-configured
in a way that a particular user attribute is preferably read from the database instead of from the LDAP. However when you later change the edit mode,
the mappers configuration will not be changed as it is not easily possible to detect if they were manually changed in the meantime.
This means that it is recommended NOT to update the `Edit Mode` switch, but rather always decide on `Edit Mode` when creating the
LDAP provider. This applies for `Import Users` switch as well.
[NOTE]
====
When {project_name} creates the LDAP provider, {project_name} also creates a set of initial <<_ldap_mappers,LDAP mappers>>. {project_name} configures these mappers based on a combination of the *Vendor*, *Edit Mode*, and *Import Users* switches. For example, when edit mode is UNSYNCED, {project_name} configures the mappers to read a particular user attribute from the database and not from the LDAP server. However, if you later change the edit mode, the mapper's configuration does not change because it is impossible to detect if the configuration changes changed in UNSYNCED mode. Decide the *Edit Mode* when creating the LDAP provider. This note applies to *Import Users* switch also.
====
==== Other config options
==== Other configuration options
Console Display Name::
Name used when this provider is referenced in the admin console
The name of the provider to display in the admin console.
Priority::
The priority of this provider when looking up users or adding a user.
The priority of the provider when looking up users or adding a user.
Sync Registrations::
Does your LDAP support adding new users? Click this switch if you want new users created by {project_name} in the admin console or the registration page
to be added to LDAP.
Toggle this switch to *ON* if you want new users created by {project_name} added to LDAP.
Allow Kerberos authentication::
Enable Kerberos/SPNEGO authentication in realm with users data provisioned from LDAP.
More info in <<_kerberos,Kerberos section>>.
Enable Kerberos/SPNEGO authentication in the realm with user data provisioned from LDAP. For more information, see the <<_kerberos,Kerberos section>>.
Other options::
The rest of the configuration options should be self explanatory.
You can hover the mouse pointer over the tooltips in the Admin Console to see some more details about them.
Hover the mouse pointer over the tooltips in the Admin Console to see more details about these options.
==== Connect to LDAP over SSL
==== Connecting to LDAP over SSL
When you configure a secured connection URL to your LDAP store (for example,`ldaps://myhost.com:636'), {project_name} will use SSL for communication with the LDAP server.
The important thing is to properly configure a truststore on the {project_name} server side, otherwise {project_name} can't trust the SSL connection to LDAP.
When you configure a secure connection URL to your LDAP store (for example,`ldaps://myhost.com:636'), {project_name} uses SSL to communicate with the LDAP server. Configure a truststore on the {project_name} server side so that {project_name} can trust the SSL connection to LDAP.
The global truststore for the {project_name} can be configured with the Truststore SPI. Please check out the link:{installguide_link}[{installguide_name}] for more details.
If you do not figure the truststore SPI, the truststore will fall back on the default mechanism provided by Java (either the file provided by system property `javax.net.ssl.trustStore`
or the cacerts file from the JDK if the system property is not set).
Configure the global truststore for {project_name} with the Truststore SPI. For more information about configuring the global truststore, see the link:{installguide_link}[{installguide_name}]. If you do not configure the Truststore SPI, the truststore falls back to the default mechanism provided by Java, which can be the file supplied by the `javax.net.ssl.trustStore` system property or the cacerts file from the JDK if the system property is unset.
There is a configuration property `Use Truststore SPI` in the LDAP federation provider configuration, where you can choose whether the Truststore SPI is used.
By default, the value is `Only for ldaps`, which is fine for most deployments. The Truststore SPI will only be used
if the connection URL to LDAP starts with `ldaps`.
The `Use Truststore SPI` configuration property, in the LDAP federation provider configuration, controls the truststore SPI. By default, {project_name} sets the property to `Only for ldaps`, which is adequate for most deployments. {project_name} uses the Truststore SPI if the connection URL to LDAP starts with `ldaps` only.
==== Sync of LDAP users to {project_name}
==== Synchronizing LDAP users to {project_name}
If you enable the Import Users option, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the {project_name} local database.
As users log in, the LDAP provider will import the LDAP user
into the {project_name} database and then authenticate against the LDAP password. This is the only time users will be imported.
If you go to the `Users` left menu item in the Admin Console and click the `View all users` button, you will only see those LDAP users that
have been authenticated at least once by {project_name}. It is implemented this way so that this operation does not trigger an import of the entire LDAP user database.
If you set the *Import Users* option, the LDAP Provider handles importing LDAP users into the {project_name} local database. The first time a user logs in, the LDAP provider imports the LDAP user into the {project_name} database and validates the LDAP password. This first time a user logs in is the only time {project_name} imports the user. If you click the *Users* menu in the Admin Console and click the *View all users* button, you only see the LDAP users authenticated at least once by {project_name}. {project_name} imports users this way, so this operation does not trigger an import of the entire LDAP user database.
If you want to sync all LDAP users into the {project_name} database, configure and enable the *Sync Settings* on the LDAP provider configuration page.
If you want to sync all LDAP users into the {project_name} database, you may configure and enable the `Sync Settings` on the LDAP provider configuration page.
Two types of synchronization exist:
Periodic Full sync::
This type will synchronize all LDAP users into the {project_name} database.
Those LDAP users, which already exist in {project_name} and were changed in LDAP directly will be updated in the {project_name} database. For example, the user `Mary Kelly` was changed in LDAP to `Mary Smith`.
This type synchronizes all LDAP users into the {project_name} database. The LDAP users already in {project_name}, but different in LDAP, directly update in the {project_name} database.
Periodic Changed users sync::
When syncing occurs, only those users that were created or updated after the last sync will be updated and/or imported.
When synchronizing, {project_name} creates or updates users created or updated after the last sync only.
The best way to handle syncing is to click the `Synchronize all users` button when you first create the LDAP provider,
then set up a periodic sync of changed users.
The best way to synchronize is to click *Synchronize all users* when you first create the LDAP provider, then set up periodic synchronization of changed users.
[[_ldap_mappers]]
==== LDAP Mappers
LDAP mappers are `listeners`, which are triggered by the LDAP Provider at various points and provide another extension point to LDAP integration.
They are triggered when a user logs in via LDAP and needs to be imported, during {project_name} initiated registration, or when a user is queried from the Admin Console.
When you create an LDAP Federation provider, {project_name} will automatically provide set of built-in `mappers` for this provider.
You are free to change this set and create a new mapper or update/delete existing ones.
LDAP mappers are `listeners` triggered by the LDAP Provider. They provide another extension point to LDAP integration. LDAP mappers are triggered when:
* Users log in by using §LDAP.
* Users initially register.
* The Admin Console queries a user.
When you create an LDAP Federation provider, {project_name} automatically provides a set of `mappers` for this provider. This set is changeable by users, who can also develop mappers or update/delete existing ones.
User Attribute Mapper::
This allows you to specify which LDAP attribute is mapped to which attribute of {project_name} user.
So, for example, you can configure that LDAP attribute `mail` to the attribute `email` in the {project_name} database.
For this mapper implementation, there is always a one-to-one mapping (one LDAP attribute is mapped to one {project_name} attribute)
This mapper specifies which LDAP attribute maps to the attribute of the {project_name} user. For example, you can configure the `mail` LDAP attribute to the `email` attribute in the {project_name} database. For this mapper implementation, a one-to-one mapping always exists.
FullName Mapper::
This allows you to specify that the full name of the user, which is saved in some LDAP attribute (usually `cn` ) will be mapped to `firstName` and `lastname` attributes in the {project_name} database.
Having `cn` to contain full name of user is a common case for some LDAP deployments.
This mapper specifies the full name of the user. {project_name} saves the name in an LDAP attribute (usually `cn`) and maps the name to the `firstName` and `lastname` attributes in the {project_name} database. Having `cn` to contain the full name of the user is common for LDAP deployments.
NOTE: When registering new users in {project_name} and `Sync Registrations` is ON for the LDAP provider, the fullName mapper
allows the possibility of fallback to the username. This fallback is especially useful in case of the Microsoft Active Directory. The common
setup for the MSAD is to configure `cn` LDAP attribute as fullName and at the same time, the `cn` is usually used as `RDN LDAP Attribute`
in the configuration of the LDAP provider. With this setup, the fallback to the username will be used. For example when you create
{project_name} user "john123" and leave firstName and lastName empty, then fullname mapper will save "john123" as the value of the `cn` in LDAP.
When you later enter "John Doe" for firstName and lastName, the fullname mapper will update LDAP `cn` to the value "John Doe" as
fallback to the username will not be needed anymore.
[NOTE]
====
When you register new users in {project_name} and `Sync Registrations` is ON for the LDAP provider, the fullName mapper permits falling back to the username. This fallback is useful when using Microsoft Active Directory (MSAD). The common setup for MSAD is to configure the `cn` LDAP attribute as fullName and, at the same time, use the `cn` LDAP attribute as the `RDN LDAP Attribute` in the LDAP provider configuration. With this setup, {project_name} falls back to the username. For example, if you create {project_name} user "john123" and leave firstName and lastName empty, then the fullname mapper saves "john123" as the value of the `cn` in LDAP. When you enter "John Doe" for firstName and lastName later, the fullname mapper updates LDAP `cn` to the "John Doe" value as falling back to the username is unnecessary.
====
Hardcoded Attribute Mapper::
This mapper adds a hardcoded attribute value to each {project_name} user linked with LDAP.
This mapper can also force the values for the `enabled` or `emailVerified` user properties.
This mapper adds a hardcoded attribute value to each {project_name} user linked with LDAP. This mapper can also force values for the `enabled` or `emailVerified` user properties.
Role Mapper::
This allows you to configure role mappings from LDAP into {project_name} role mappings.
One Role mapper can be used to map LDAP roles (usually groups from a particular branch of LDAP tree) into roles corresponding to either realm roles or client roles of a specified client.
It's not a problem to configure more Role mappers for the same LDAP provider.
So for example you can specify that role mappings from groups under
`ou=main,dc=example,dc=org` will be mapped to realm role mappings and role mappings from groups under
`ou=finance,dc=example,dc=org` will be mapped to client role mappings of client `finance`.
This mapper configures role mappings from LDAP into {project_name} role mappings. A single role mapper can map LDAP roles (usually groups from a particular branch of the LDAP tree) into roles corresponding to a specified client's realm roles or client roles. You can configure more Role mappers for the same LDAP provider. For example, you can specify that role mappings from groups under `ou=main,dc=example,dc=org` map to realm role mappings, and role mappings from groups under `ou=finance,dc=example,dc=org` map to client role mappings of client `finance`.
Hardcoded Role Mapper::
This mapper will grant a specified {project_name} role to each {project_name} user from the LDAP provider.
This mapper grants a specified {project_name} role to each {project_name} user from the LDAP provider.
Group Mapper::
This allows you to map LDAP groups from a particular branch of an LDAP tree into groups in {project_name}.
It will also propagate user-group mappings from LDAP into user-group mappings in {project_name}.
This mapper maps LDAP groups from a branch of an LDAP tree into groups within {project_name}. This mapper also propagates user-group mappings from LDAP into user-group mappings in {project_name}.
MSAD User Account Mapper::
This mapper is specific to Microsoft Active Directory (MSAD). It's able to tightly integrate the MSAD user account state
into the {project_name} account state (account enabled, password is expired, and so on).
It is using the `userAccountControl` and `pwdLastSet` LDAP attributes, which are both specific to MSAD and are not LDAP standard.
For example if `pwdLastSet` is `0`, the {project_name} user is required to update their password
and there will be an UPDATE_PASSWORD required action added to the user. If `userAccountControl` is
`514` (disabled account) the {project_name} user is disabled as well.
This mapper is specific to Microsoft Active Directory (MSAD). It can integrate the MSAD user account state into the {project_name} account state, such as enabled account or expired password. This mapper uses the `userAccountControl`, and `pwdLastSet` LDAP attributes, specific to MSAD and are not the LDAP standard. For example, if the value of `pwdLastSet` is `0`, the {project_name} user must update their password. The result is an UPDATE_PASSWORD required action added to the user. If the value of `userAccountControl` is `514` (disabled account), the {project_name} user is disabled.
Certificate Mapper::
This mapper is specific for mapping X.509 certificates. It will generally be used in conjunction with X.509 authentication
and `Full certificate in PEM format` as an identity source.
It behaves the same way as the `User Attribute Mapper`, but allows {project_name} to filter for an LDAP attribute which stores
a certificate in either PEM or DER format. It is generally advised to enable `Always Read Value From LDAP` with this mapper.
This mapper maps X.509 certificates. {project_name} uses it in conjunction with X.509 authentication and `Full certificate in PEM format` as an identity source. This mapper behaves similarly to the `User Attribute Mapper`, but {project_name} can filter for an LDAP attribute storing a PEM or DER format certificate. Enable `Always Read Value From LDAP` with this mapper.
By default, there are User Attribute mappers that map basic {project_name} user attributes like username, firstname, lastname, and email to corresponding LDAP attributes.
You are free to extend these and provide additional attribute mappings.
Admin console provides tooltips, which should help with configuring the corresponding mappers.
User Attribute mappers that map basic {project_name} user attributes, such as username, firstname, lastname, and email, to corresponding LDAP attributes. You can extend these and provide your own additional attribute mappings. The Admin Console provides tooltips to help with configuring the corresponding mappers.
[[_ldap_password_hashing]]
==== Password Hashing
When the password of user is updated from {project_name} and sent to LDAP, it is always sent in plain-text. This is different from
updating the password to built-in {project_name} database, when the hashing and salting is applied to the password before it is sent to DB.
In the case of LDAP, the {project_name} relies on the LDAP server to provide hashing and salting of passwords.
When {project_name} updates a password, {project_name} sends the password in plain-text format. This action is different from updating the password in the built-in {project_name} database, where {project_name} hashes and salts the password before sending it to the database. For LDAP, {project_name} relies on the LDAP server to hash and salt the password.
LDAP servers such as Microsoft Active Directory, RHDS or FreeIPA provide this by default. Others such as OpenLDAP or ApacheDS may store the passwords
in plain-text by default unless you use the _LDAPv3 Password Modify Extended Operation_ as per *RFC3062*. The LDAPv3 Password Modify Extended Operation
must be enabled explicitly in the LDAP configuration page. See the documentation of your LDAP server for more details.
By default, LDAP servers such as MSAD, RHDS, or FreeIPA hash and salt passwords. Other LDAP servers such as OpenLDAP or ApacheDS store the passwords in plain-text unless you use the _LDAPv3 Password Modify Extended Operation_ as described in https://tools.ietf.org/html/rfc3062[RFC3062]. Enable the LDAPv3 Password Modify Extended Operation in the LDAP configuration page. See the documentation of your LDAP server for more details.
WARNING: Always verify that user passwords are properly hashed and not stored as plaintext by inspecting a changed
directory entry using `ldapsearch` and base64 decode the `userPassword` attribute value.

201
server_admin/topics/user-federation/sssd.adoc
View file

@ -1,90 +1,112 @@
[[_sssd]]
=== SSSD and FreeIPA Identity Management Integration
{project_name} also comes with a built-in https://fedoraproject.org/wiki/Features/SSSD[SSSD] (System Security Services Daemon) plugin. SSSD is part of the latest Fedora or Red Hat Enterprise Linux and provides access to multiple identity and authentication providers. It provides benefits such as failover and offline support. To see configuration options and for more information see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/sssd[the Red Hat Enterprise Linux Identity Management documentation].
{project_name} includes a https://fedoraproject.org/wiki/Features/SSSD[System Security Services Daemon (SSSD)] plugin. SSSD is part of the Fedora and Red Hat Enterprise Linux (RHEL), and it provides access to multiple identities and authentication providers. SSSD also provides benefits such as failover and offline support. For more information, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/sssd[the Red Hat Enterprise Linux Identity Management documentation].
SSSD also integrates with the FreeIPA identity management (IdM) server, providing authentication and access control. For {project_name}, we benefit from this integration authenticating against PAM services and retrieving user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/linux_domain_identity_authentication_and_policy_guide/index[the Red Hat Enterprise Linux Identity Management documentation].
SSSD integrates with the FreeIPA identity management (IdM) server, providing authentication and access control. With this integration, {project_name} can authenticate against privileged access management (PAM) services and retrieve user data from SSSD. For more information about using Red Hat Identity Management in Linux environments, see https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/linux_domain_identity_authentication_and_policy_guide/index[the Red Hat Enterprise Linux Identity Management documentation].
image:{project_images}/keycloak-sssd-freeipa-integration-overview.png[]
Most of the communication between {project_name} and SSSD occurs through read-only D-Bus interfaces. For this reason, the only way to provision and update users is to use the FreeIPA/IdM administration interface. By default, like the LDAP federation provider, it is set up only to import username, email, first name, and last name.
{project_name} and SSSD communicate through read-only D-Bus interfaces. For this reason, the way to provision and update users is to use the FreeIPA/IdM administration interface. By default, the interface imports the username, email, first name, and last name.
[NOTE]
Groups and roles are automatically registered, but not synchronized, so any changes made by the {project_name} administrator directly in {project_name} are not synchronized with SSSD.
Information on how to configure the FreeIPA/IdM server follows.
====
{project_name} registers groups and roles automatically but does not synchronize them. Any changes made by the {project_name} administrator in {project_name} do not synchronize with SSSD.
====
==== FreeIPA/IdM Server
For the sake of simplicity, a https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] already available is used. To set up a server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation].
Running a FreeIPA server with Docker requires this command:
A https://hub.docker.com/r/freeipa/freeipa-server/[FreeIPA Docker image] is available in Docker. To set up a FreeIPA server, see the https://www.freeipa.org/page/Quick_Start_Guide[FreeIPA documentation].
.Procedure
. Run your FreeIPA server using this command:
+
[source,bash,subs=+attributes]
----
docker run --name freeipa-server-container -it \
-h server.freeipa.local -e PASSWORD=YOUR_PASSWORD \
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
-v /var/lib/ipa-data:/data:Z freeipa/freeipa-server
----
+
The parameter `-h` with `server.freeipa.local` represents the FreeIPA/IdM server hostname.
Change `YOUR_PASSWORD` to a password of your own.
The parameter `-h` with `server.freeipa.local` represents the FreeIPA/IdM server hostname. Be sure to change `YOUR_PASSWORD` to a password of your choosing.
After the container starts, change `/etc/hosts` to:
x.x.x.x server.freeipa.local
. After the container starts, change the `/etc/hosts` file to include:
+
[source,bash,subs=+attributes]
----
x.x.x.x server.freeipa.local
----
+
If you do not make this change, you must set up a DNS server.
You must enroll your Linux machine in the IPA domain so that the SSSD federation provider is started and running on {project_name}:
. Use the following command to enroll your Linux server in the IPA domain so that the SSSD federation provider starts and runs on {project_name}:
+
[source,bash,subs=+attributes]
----
ipa-client-install --mkhomedir -p admin -w password
----
To ensure that everything is working as expected, on the client machine, run:
. Run the following command on the client to verify the installation is working:
+
[source,bash,subs=+attributes]
----
kinit admin
----
You should be prompted for the password. After that, you can add users to the IPA server using this command:
. Enter your password.
. Add users to the IPA server using this command:
+
[source,bash,subs=+attributes]
----
$ ipa user-add <username> --first=<first name> --last=<surname> --email=<email address> --phone=<telephoneNumber> --street=<street> \ --city=<city> --state=<state> --postalcode=<postal code> --password
----
$ ipa user-add john --first=John --last=Smith --email=john@smith.com --phone=042424242 --street="Testing street" \ --city="Testing city" --state="Testing State" --postalcode=0000000000 --password
To force setting the user's password, use kinit. Given the user john, you would enter this command:
kinit john
To restore normal IPA operation, you would enter these commands:
kdestroy -A
kinit admin
. Force set the user's password using kinit.
+
[source,bash,subs=+attributes]
----
kinit <username>
----
. Enter the following to restore normal IPA operation:
+
[source,bash,subs=+attributes]
----
kdestroy -A
kinit admin
----
==== SSSD and D-Bus
As mentioned previously, the federation provider obtains the data from SSSD using D-BUS and authentication occurs using PAM.
The federation provider obtains the data from SSSD using D-BUS. It authenticates the data using PAM.
First, you have to install the sssd-dbus RPM, which allows information from SSSD to be transmitted over the system bus.
$ sudo yum install sssd-dbus
.Procedure
. Install the sssd-dbus RPM.
+
[source,bash,subs=+attributes]
----
$ sudo yum install sssd-dbus
----
ifeval::[{project_community}==true]
You must run the provisioning script available from the Keycloak distribution:
. Run the provisioning script available from the Keycloak distribution:
+
[source,bash,subs=+attributes]
----
$ bin/federation-sssd-setup.sh
endif::[]
ifeval::[{project_product}==true]
You must run this provisioning script:
[source]
----
$ .../bin/federation-sssd-setup.sh
----
endif::[]
This script makes the necessary changes to `/etc/sssd/sssd.conf`:
+
This provisioning script makes the following changes to `/etc/sssd/sssd.conf`:
+
[source,bash,subs=+attributes]
----
[domain/your-hostname.local]
...
ldap_user_extra_attrs = mail:mail, sn:sn, givenname:givenname, telephoneNumber:telephoneNumber
@ -95,69 +117,84 @@ This script makes the necessary changes to `/etc/sssd/sssd.conf`:
[ifp]
allowed_uids = root, yourOSUsername
user_attributes = +mail, +telephoneNumber, +givenname, +sn
----
Also, a `keycloak` file is included under `/etc/pam.d/`:
auth required pam_sss.so
account required pam_sss.so
Ensure everything is working as expected by running `dbus-send`:
sudo dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserGroups string:john
You should be able to see the user's group. If this command returns a timeout or an error, it means that the federation provider running on {project_name} will also be unable to retrieve anything.
Most of the time this occurs because the machine was not enrolled in the FreeIPA IdM server or you do not have permission to access the SSSD service.
If you do not have permission, ensure that the user running the {project_name} server is included in the `/etc/sssd/sssd.conf` file in the following section:
[ifp]
allowed_uids = root, your_username
. Run `dbus-send` to ensure the setup is successful.
+
[source,bash,subs=+attributes]
----
sudo dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserGroups string:john
----
+
If the setup is successful, you see the user's group. If this command returns a timeout or an error, the federation provider running on {project_name} cannot retrieve any data. This error usually happens because the server is not enrolled in the FreeIPA IdM server, or does not have permission to access the SSSD service.
+
If you do not have permission to access the SSSD service, ensure that the user running the {project_name} server is in the `/etc/sssd/sssd.conf` file in the following section:
+
[source,bash,subs=+attributes]
----
[ifp]
allowed_uids = root, your_username
----
==== Enabling the SSSD Federation Provider
{project_name} uses DBus-Java to communicate at a low level with D-Bus, which depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library].
{project_name} uses DBus-Java to communicate at a low level with D-Bus. D-Bus depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library].
ifeval::[{project_community}==true]
An RPM for this library can be found in https://github.com/keycloak/libunix-dbus-java/releases[this repository]. Before installing it, be sure to check the RPM signature:
You can find an RPM for this library in https://github.com/keycloak/libunix-dbus-java/releases[the keycloak repository]. Before installing this RPM, check the RPM signature using this command:
[source,bash,subs=+attributes]
----
$ rpm -K libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm
libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm:
Header V4 RSA/SHA256 Signature, key ID 84dc9914: OK
Header SHA1 digest: OK (d17bb7ebaa7a5304c1856ee4357c8ba4ec9c0b89)
V4 RSA/SHA256 Signature, key ID 84dc9914: OK
MD5 digest: OK (770c2e68d052cb4a4473e1e9fd8818cf)
$ sudo yum install libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm
----
Install the RPM using this command:
[source,bash,subs=+attributes]
----
$ sudo yum install libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm
----
endif::[]
ifeval::[{project_product}==true]
Before enabling the SSSD Federation provider, you must install the RPM for this library:
Before enabling the SSSD Federation provider, install the RPM for this library:
$ sudo yum install rh-sso7-libunix-dbus-java
[source,bash,subs=+attributes]
----
$ sudo yum install rh-sso7-libunix-dbus-java
----
endif::[]
For authentication with PAM {project_name} uses JNA. Be sure you have this package installed:
{project_name} uses JNA to authenticate with PAM. Ensure you have the JAN package installed.
$ sudo yum install jna
[source,bash,subs=+attributes]
----
$ sudo yum install jna
Use `sssctl user-checks` command to validate your setup:
----
Use the `sssctl user-checks` command to validate your setup:
[source]
----
$ sudo sssctl user-checks admin -s keycloak
----
=== Configuring a Federated SSSD Store
After the installation, you need to configure a federated SSSD store.
After the installation, configure a federated SSSD store.
To configure a federated SSSD store, complete the following steps:
. Navigate to the Administration Console.
. From the left menu, select *User Federation.*
. From the *Add Provider* dropdown list, select *sssd.* The sssd configuration page opens.
.Procedure
. Click *User Federation* in the menu.
. From the *Add Provider* list select _sssd_. {project_name} brings you to the sssd configuration page.
. Click *Save*.
Now you can authenticate against {project_name} using FreeIPA/IdM credentials.
You can now authenticate against {project_name} using FreeIPA/IdM credentials.