Chapter 14. User Storage Federation

By default, Red Hat Single Sign-On will import users from LDAP into the local Red Hat Single Sign-On 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 Red Hat Single Sign-On 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 Red Hat Single Sign-On 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.

Alternatively, you can choose not to import users into the Red Hat Single Sign-On user database. In this case, the common user model that the Red Hat Single Sign-On runtime uses is backed only by the LDAP server. This means that if LDAP doesn’t support a piece of data that a Red Hat Single Sign-On 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 Red Hat Single Sign-On user database.

This storage mode is controled by the Import Users switch. Set to On to import users.

Users, through the 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.

When you configure a secured connection URL to your LDAP store (for example,`ldaps://myhost.com:636'), Red Hat Single Sign-On will use SSL for communication with the LDAP server. The important thing is to properly configure a truststore on the Red Hat Single Sign-On server side, otherwise Red Hat Single Sign-On can’t trust the SSL connection to LDAP.

The global truststore for the Red Hat Single Sign-On can be configured with the Truststore SPI. Please check out the Server Installation and Configuration Guide 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).

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.

If you enable the Import Users option, the LDAP Provider will automatically take care of synchronization (import) of needed LDAP users into the Red Hat Single Sign-On local database. As users log in, the LDAP provider will import the LDAP user into the Red Hat Single Sign-On 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 Red Hat Single Sign-On. It is implemented this way so that this operation does not trigger an import of the entire LDAP user database.

If you want to sync all LDAP users into the Red Hat Single Sign-On database, you may configure and enable the Sync Settings on the LDAP provider configuration page. Two types of synchronization exist:

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.

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 Red Hat Single Sign-On initiated registration, or when a user is queried from the Admin Console. When you create an LDAP Federation provider, Red Hat Single Sign-On 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.

By default, there are User Attribute mappers that map basic Red Hat Single Sign-On 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.

When the password of user is updated from Red Hat Single Sign-On and sent to LDAP, it is always sent in plain-text. This is different from updating the password to built-in Red Hat Single Sign-On database, when the hashing and salting is applied to the password before it is sent to DB. In the case of LDAP, the Red Hat Single Sign-On relies on the LDAP server to provide hashing and salting of passwords.

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.

For the sake of simplicity, a FreeIPA Docker image already available is used. To set up a server, see the FreeIPA documentation.

Running a FreeIPA server with Docker requires this command:

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

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 Red Hat Single Sign-On:

ipa-client-install --mkhomedir -p admin -w password

To ensure that everything is working as expected, on the client machine, run:

kinit admin

You should be prompted for the password. After that, you can add users to the IPA server using this command:

$ 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

As mentioned previously, the federation provider obtains the data from SSSD using D-BUS and authentication occurs 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

You must run this provisioning script:

$ .../bin/federation-sssd-setup.sh

This script makes the necessary changes to /etc/sssd/sssd.conf:

[domain/your-hostname.local]
...
ldap_user_extra_attrs = mail:mail, sn:sn, givenname:givenname, telephoneNumber:telephoneNumber
...
[sssd]
services = nss, sudo, pam, ssh, ifp
...
[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 Red Hat Single Sign-On 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 Red Hat Single Sign-On server is included in the /etc/sssd/sssd.conf file in the following section:

[ifp]
allowed_uids = root, your_username

Red Hat Single Sign-On uses DBus-Java to communicate at a low level with D-Bus, which depends on the Unix Sockets Library.

Before enabling the SSSD Federation provider, you must install the RPM for this library:

$ sudo yum install rh-sso7-libunix-dbus-java

For authentication with PAM Red Hat Single Sign-On uses JNA. Be sure you have this package installed:

$ sudo yum install jna

Use sssctl user-checks command to validate your setup:

$ sudo sssctl user-checks admin -s keycloak