keycloak-scim/server_admin/topics/user-federation/sssd.adoc

[[_sssd]]

=== SSSD and FreeIPA Identity Management Integration

{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 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[]

{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]
====
{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

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.

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

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

. Run the following command on the client to verify the installation is working:
+
[source,bash,subs=+attributes]
----
 kinit admin
----

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

. 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

The federation provider obtains the data from SSSD using D-BUS. It authenticates the data using PAM.

.Procedure
. Install the sssd-dbus RPM.
+
[source,bash,subs=+attributes]
----
$ sudo yum install sssd-dbus
----

ifeval::[{project_community}==true]

. Run the provisioning script available from the Keycloak distribution:
+
[source,bash,subs=+attributes]
----
  $ bin/federation-sssd-setup.sh
----

endif::[]
+
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
  ...
  [sssd]
  services = nss, sudo, pam, ssh, ifp
  ...
  [ifp]
  allowed_uids = root, yourOSUsername
  user_attributes = +mail, +telephoneNumber, +givenname, +sn
----

. 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. D-Bus depends on the http://www.matthew.ath.cx/projects/java/[Unix Sockets Library].

ifeval::[{project_community}==true]

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

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, install the RPM for this library:

[source,bash,subs=+attributes]
----
$ sudo yum install rh-sso7-libunix-dbus-java
----

endif::[]

{project_name} uses JNA to authenticate with PAM. Ensure you have the JAN package installed.

[source,bash,subs=+attributes]
----
$ sudo yum install jna

----

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, configure a federated SSSD store.

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

You can now authenticate against {project_name} using FreeIPA/IdM credentials.