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

[[_sssd]]

=== SSSD and FreeIPA Identity Management Integration

{{book.project.name}} also comes with a built-in https://fedorahosted.org/sssd/wiki[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://fedorahosted.org/sssd/wiki/Documentation[the Fedora documentation].

SSSD also integrates with the http://www.freeipa.org/page/Main_Page[FreeIPA identity management (IdM)] server, providing authentication and access control. For {book_project_name}, we benefit from this integration authenticating against http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html[PAM] services and retrieving user data from SSSD.

image:../../{{book.images}}/keycloak-sssd-freeipa-integration-overview.png[]

Most of the communication between {{book.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 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.

[NOTE]
Groups and roles are automatically registered, but not synchronized, so any changes made by the {{book.project.name}} administrator directly in {{book.project.name}} is not synchronized with SSSD.

Information on how to configure the FreeIPA/IdM server follows.

==== FreeIPA/IdM Server

As a matter of simplicity, a https://www.freeipa.org/page/Docker[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:

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

So that the SSSD federation provider is started and running on {{book.project.name}} you must enroll your Linux machine in the IPA domain:

 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

==== SSSD and D-Bus

As mentioned previously, the federation provider obtains the data from SSSD using D-BUS and authentication occurs using http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html[PAM].

{% if book.community %}

You must run the provisioning script available from the Keycloak distribution:

  $ bin/federation-sssd-setup.sh

{% endif %}

{% if book.product %}

You must copy and run this provisioning script:

[source,bash]
----

#!/bin/sh

# Setup for SSSD
SSSD_FILE="/etc/sssd/sssd.conf"

if [ -f "$SSSD_FILE" ];
then
  sed -i '/ldap_tls_cacert/a ldap_user_extra_attrs = mail:mail, sn:sn, givenname:givenname, telephoneNumber:telephoneNumber' $SSSD_FILE
  sed -i 's/nss, sudo, pam/nss, sudo, pam, ifp/' $SSSD_FILE
  sed -i '/\[ifp\]/a allowed_uids = root\nuser_attributes = +mail, +telephoneNumber, +givenname, +sn' $SSSD_FILE
  systemctl restart sssd
else
  echo "Please make sure you have $SSSD_FILE into your system! Aborting."
  exit 1
fi

# Setup for PAM
PAM_FILE="/etc/pam.d/keycloak"

if [ ! -f "$PAM_FILE" ];
then
cat <<EOF > $PAM_FILE
  auth    required   pam_sss.so
  account required   pam_sss.so
EOF
else
  echo "$PAM_FILE already exists. Skipping it..."
  exit 0
fi

----
{% endif %}

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 will also not be able to retrieve anything on {{book.project.name}}.

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 {{book.project.name}} is included in the `/etc/sssd/sssd.conf` file in the following section:

  [ifp]
  allowed_uids = root, your_username

==== Enabling the SSSD Federation Provider

{{book.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].

{% if book.community %}

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:

  $ 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

{% endif %}

{% if book.product %}

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

  $ sudo yum install rh-sso7-libunix-dbus-java.x86_64.rpm

{% endif %}

For authentication with PAM {{book.project.name}} uses JNA. Be sure you have this package installed:

  $ sudo yum install jna

=== Configuring a Federated SSSD Store

After installation, you need to 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.
. Click *Save*.

Now you can authenticate against {{book.project.name}} using FreeIPA/IdM credentials.