Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Using Containerized Identity Management Services

Red Hat Enterprise Linux 7

Overview and installation of containerized Identity Management services

Florian Delehaye

Red Hat Customer Content Services

Marc Muehlfeld

Red Hat Customer Content Services

Filip Hanzelka

Red Hat Customer Content Services

Lucie Maňásková

Red Hat Customer Content Services

Aneta Šteflová Petrová

Red Hat Customer Content Services

Abstract

Learn about containerized Identity Management services in Red Hat Enterprise Linux 7, and start using them.

The following sections provide an overview of the containerized Identity Management services in Red Hat Enterprise Linux.

Warning

The rhel7/ipa-server container is a Technology Preview feature. See Technology Preview Features Support Scope in the Red Hat Knowledgebase for details.

Using Identity Management or the System Security Services Daemon (SSSD) in a container ensures that all Identity Management or SSSD processes run in isolation from the host system. This enables the host system to run other software without conflicts with these processes.

Important

The ipa-server and sssd containers are designed to be used on Red Hat Enterprise Linux Atomic Host systems. For details on Atomic Host, see Getting Started with Atomic in the Atomic documentation.

Additional Resources

1.2. Available Container Images
Copy link

The rhel7/ipa-server Container Image
  • Enables you to run Identity Management servers and related services in a container.
  • Provides Identity Management server services.
The rhel7/sssd Container Image
  • Enables you to run the System Security Services Daemon (SSSD) in a container.
  • Provides identity and authentication services to Atomic Host systems by enrolling the system to an Identity Management server or connecting it to an Active Directory domain.
  • Provides identity and authentication services to applications running in other containers.
Additional Resources
Benefits
Drawbacks
  • The Identity Management processes run under Atomic. For example, if the docker daemon terminates, the Identity Management server running under it also terminates. However, maintaining multiple replicas counters this drawback.

  • SELinux separation is not applied to the components within a container. However, the components are still separated using process UIDs.

    • Note that although SELinux does not apply its mandatory access control (MAC) between the components, the sVirt project applies MAC to the container environment. This ensures that the container as a whole is protected from other containers.
    • The ipa-server container runs only the components required to run the Identity Management server itself. The container does not run any third-party components that can attack Identity Management due to the lack of SELinux isolation.
    • See also Secure Containers with SELinux in Atomic documentation.

This part covers how to deploy an Identity Management server and replica in a container, how to migrate a server from a container to a host system, and finally, how to uninstall server and replica containers.

This chapter describes how you can install a fresh Identity Management server to start a new topology.

Before you begin, read Section 2.1, “Prerequisites” and Section 2.2, “Available Configuration in Server and Replica Containers”.

Choose one of the following installation procedures. If you are not sure which certificate authority (CA) configuration fits your situation, see Determining What CA Configuration to Use in the Linux Domain Identity, Authentication, and Policy Guide.

After you are done, read Section 2.6, “Next Steps After Installation”.

2.1. Prerequisites
Copy link

  • Upgrade the Atomic Host system before installing the container. See Upgrading and Downgrading in the Red Hat Enterprise Linux Atomic Host 7 Installation and Configuration Guide.
What Is Available
Domain level 1 or higher

Domain level 0 is not available for containers. See also Displaying and Raising the Domain Level.

As a consequence, servers running in containers can be joined in a replication agreement only with Identity Management servers based on Red Hat Enterprise Linux 7.3 or later.

Mixed container and non-container deployments
A single Identity Management domain topology can include both container-based and RPM-based servers.
What Is Not Available
Changing server components in a deployed container
Do not make runtime modifications of deployed containers. If you need to change or reinstall a server component, such as integrated DNS or Vault, create a new replica.
Upgrading between different Linux distributions

Do not change the platform on which an ipa-server container image runs. For example, do not change an image running on Red Hat Enterprise Linux to Fedora, Ubuntu, or CentOS. Similarly, do not change an image running on Fedora, Ubuntu, or CentOS to Red Hat Enterprise Linux.

Identity Management supports only upgrades to later versions of Red Hat Enterprise Linux.

Downgrading the system with a running container
Do not downgrade the system on which an ipa-server container image runs.
Upstream containers on Atomic Host
Do not install upstream container images, such as the FreeIPA ipa-server image, on Atomic Host. Install only the container images available in Red Hat Enterprise Linux.
Multiple containers on a single Atomic Host
Install only one ipa-server container image on a single Atomic Host.

This procedure shows how to install a containerized Identity Management server in the default certificate authority (CA) configuration with an integrated CA.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.
Procedure

  1. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-server-install command to start the installation.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  2. The ipa-server-install setup script starts: 

    The log file for this installation can be found in /var/log/ipaserver-install.log
========================================
This program will set up the IPA Server.
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

    The process is the same as when using the ipa-server-install utility to install a non-container server.

Example 2.1. Installation Command Examples

Command syntax for installing the ipa-server container: 

$ atomic install [ --name <container_name> ] rhel7/ipa-server [ Atomic options ] [ ipa-server-install | ipa-replica-install ] [ ipa-server-install or ipa-replica-install options ]
Copy to Clipboard Toggle word wrap

To install a server container named server-container and use default values for the Identity Management server settings: 

$ atomic install --name server-container rhel7/ipa-server publish --hostname server.example.com ipa-server-install --ip-address 2001:DB8::1111
Copy to Clipboard Toggle word wrap

To install a server with a custom host name (--hostname) and integrated DNS (--setup-dns): 

$ atomic install rhel7/ipa-server publish --hostname server.example.com ipa-server-install --setup-dns --ip-address 2001:DB8::1111
Copy to Clipboard Toggle word wrap

This procedure describes how to install a server with an integrated Identity Management certificate authority (CA) that is subordinate to an external CA.

A containerized Identity Management server and the Atomic Host system share only the parts of the file system that are mounted using a bind mount into the container. Therefore, operations related to external files must be performed from within this volume.

The ipa-server container image uses the /var/lib/<container_name>/ directory to store persistent files on the Atomic Host file system. The persistent storage volume maps to the /data/ directory inside the container.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.
Procedure

  1. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-server-install --external-ca command to start the installation.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  2. The ipa-server-install setup script starts: 

    The log file for this installation can be found in /var/log/ipaserver-install.log
========================================
This program will set up the IPA Server.
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

    The process is the same as when using the ipa-server-install utility to install a non-container server.

  3. The container installation script generates the certificate signing request (CSR) in the /var/lib/<container_name>/root/ipa.csr file. Submit the CSR to the external CA, and retrieve the issued certificate and the CA certificate chain for the issuing CA.

    See Installing a Server with an External CA as the Root CA in the Linux Domain Identity, Authentication, and Policy Guide for details.

  4. Copy the signed CA certificate and the root CA certificate into the /var/lib/<container_name>/ directory. 

    $ cp /root/{ipa,ca}.crt /var/lib/server-container/.
    Copy to Clipboard Toggle word wrap

  5. Use the atomic run command with the --external-cert-file option to specify the location of the certificates. Specify the location relative to the /data/ directory because the installer performs the call from inside the container 

    $ atomic run rhel7/ipa-server ipa-server-install --external-cert-file /data/ipa.crt --external-cert-file /data/ca.crt
    Copy to Clipboard Toggle word wrap
  6. The installation resumes. The installer now uses the supplied certificates to set up the subordinate CA.

This procedure describes how to install a server without an integrated Identity Management certificate authority (CA).

A containerized Identity Management server and the Atomic Host system share only the parts of the file system that are mounted using a bind mount into the container. Therefore, operations related to external files must be performed from within this volume.

The ipa-server container image uses the /var/lib/<container_name>/ directory to store persistent files on the Atomic Host file system. The persistent storage volume maps to the /data/ directory inside the container.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.
Procedure

  1. Manually create the persistent storage directory for the container at /var/lib/<container_name>/: 

    $ mkdir -p /var/lib/ipa-server
    Copy to Clipboard Toggle word wrap

  2. Copy the files containing the certificate chain into the directory: 

    $ cp /root/server-*.p12 /var/lib/ipa-server/.
    Copy to Clipboard Toggle word wrap

    See Installing Without a CA in the Linux Domain Identity, Authentication, and Policy Guide for details on the required files.

  3. Use the atomic install command, and provide the required certificates from the third-party authority: 

    $ atomic install --name server-container rhel7/ipa-server publish \
   --hostname server.example.com \
   ipa-server-install \
   --dirsrv-cert-file=/data/server-dirsrv-cert.p12 \
   --dirsrv-pin=1234 \
   --http-cert-file=/data/server-http-cert.p12 \
   --http-pin=1234 \
   --pkinit-cert-file=/data/server-pkinit-cert.p12 \
   --pkinit-pin=1234
    Copy to Clipboard Toggle word wrap

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  4. The ipa-server-install setup script starts: 

    The log file for this installation can be found in /var/log/ipaserver-install.log
========================================
This program will set up the IPA Server.
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

    The process is the same as when using the ipa-server-install utility to install a non-container server.

2.6. Next Steps After Installation
Copy link

  • To run the container, use the atomic run command: 

    $ atomic run rhel7/ipa-server
    Copy to Clipboard Toggle word wrap

    If you specified a name for the container when you installed it: 

    $ atomic run --name server-container rhel7/ipa-server
    Copy to Clipboard Toggle word wrap
  • A running ipa-server container works in the same way as in a standard Identity Management deployment on bare-metal or virtual machine systems. For example, you can enroll hosts to the domain or manage the topology using the command-line interface, the web UI, or JSONRPC-API in the same way as RPM-based Identity Management systems.

This chapter describes how you can install an Identity Management replica. For example, creating a container-based replica can be useful if you want to gradually transfer the workload in your existing topology to container-based servers.

Before you begin, read Section 3.1, “Prerequisites” and Section 3.2, “Available Configuration in Server and Replica Containers”.

Choose one of the following installation procedures. If you are not sure which certificate authority (CA) configuration fits your situation, see Determining What CA Configuration to Use in the Linux Domain Identity, Authentication, and Policy Guide.

After you are done, read Section 3.5, “Next Steps After Installation”.

3.1. Prerequisites
Copy link

  • Upgrade the Atomic Host system before installing the container. See Upgrading and Downgrading in the Red Hat Enterprise Linux Atomic Host 7 Installation and Configuration Guide.
What Is Available
Domain level 1 or higher

Domain level 0 is not available for containers. See also Displaying and Raising the Domain Level.

As a consequence, servers running in containers can be joined in a replication agreement only with Identity Management servers based on Red Hat Enterprise Linux 7.3 or later.

Mixed container and non-container deployments
A single Identity Management domain topology can include both container-based and RPM-based servers.
What Is Not Available
Changing server components in a deployed container
Do not make runtime modifications of deployed containers. If you need to change or reinstall a server component, such as integrated DNS or Vault, create a new replica.
Upgrading between different Linux distributions

Do not change the platform on which an ipa-server container image runs. For example, do not change an image running on Red Hat Enterprise Linux to Fedora, Ubuntu, or CentOS. Similarly, do not change an image running on Fedora, Ubuntu, or CentOS to Red Hat Enterprise Linux.

Identity Management supports only upgrades to later versions of Red Hat Enterprise Linux.

Downgrading the system with a running container
Do not downgrade the system on which an ipa-server container image runs.
Upstream containers on Atomic Host
Do not install upstream container images, such as the FreeIPA ipa-server image, on Atomic Host. Install only the container images available in Red Hat Enterprise Linux.
Multiple containers on a single Atomic Host
Install only one ipa-server container image on a single Atomic Host.

This procedure shows how to install a containerized Identity Management server in the default certificate authority (CA) configuration with an integrated CA.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-replica-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-replica-install, described in Installing and Uninstalling Identity Management Replicas in the Linux Domain Identity, Authentication, and Policy Guide.
  • You must have an installed server available: either on a bare metal machine, or on another Atomic Host system.
Procedure
  1. If you want to install a replica against a master server in a container, enable two-way communication to the master container over the ports specified in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.

  2. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-replica-install command to start the installation. Include the --server and --domain options to specify the host name and domain name of your Identity Management server.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.

    • Due to a known issue in the interactive replica installation mode, add standard ipa-replica-install options to specify one of the following:

    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

Example 3.1. Installation Command Examples

Command syntax for installing the ipa-server container: 

$ atomic install [ --name <container_name> ] rhel7/ipa-server [ Atomic options ] [ ipa-server-install | ipa-replica-install ] [ ipa-server-install or ipa-replica-install options ]
Copy to Clipboard Toggle word wrap

To install a replica container named replica-container using the administrator’s credentials, while using default values for the Identity Management replica settings: 

$ atomic install --name replica-container rhel7/ipa-server publish \
    --hostname replica.example.com \
    ipa-replica-install \
    --server server.example.com \
    --domain example.com \
    --ip-address 2001:DB8::1111 \
    --principal admin \
    --admin-password <admin_password>
Copy to Clipboard Toggle word wrap

This procedure describes how to install a server without an integrated Identity Management certificate authority (CA).

A containerized Identity Management server and the Atomic Host system share only the parts of the file system that are mounted using a bind mount into the container. Therefore, operations related to external files must be performed from within this volume.

The ipa-server container image uses the /var/lib/<container_name>/ directory to store persistent files on the Atomic Host file system. The persistent storage volume maps to the /data/ directory inside the container.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-replica-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-replica-install, described in Installing and Uninstalling Identity Management Replicas in the Linux Domain Identity, Authentication, and Policy Guide.
  • You must have an installed server available: either on a bare metal machine, or on another Atomic Host system.
Procedure
  1. If you want to install a replica against a master server in a container, enable two-way communication to the master container over the ports specified in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.

  2. Manually create the persistent storage directory for the container at /var/lib/<container_name>/: 

    $ mkdir -p /var/lib/ipa-server
    Copy to Clipboard Toggle word wrap

  3. Copy the files containing the certificate chain into the directory: 

    $ cp /root/server-*.p12 /var/lib/ipa-server/.
    Copy to Clipboard Toggle word wrap

    See Installing Without a CA in the Linux Domain Identity, Authentication, and Policy Guide for details on the required files.

  4. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-replica-install command, include the --server and --domain options to specify the host name and domain name of your Identity Management server, and provide the required certificates from the third-party authority: 

    $ atomic install --name replica-container rhel7/ipa-server publish \
    --hostname replica.example.com \
    ipa-replica-install \
    --server server.example.com \
    --domain example.com \
    --dirsrv-cert-file=/data/replica-dirsrv-cert.p12 \
    --dirsrv-pin=1234 \
    --http-cert-file=/data/replica-http-cert.p12 \
    --http-pin=1234 \
    --pkinit-cert-file=/data/replica-pkinit-cert.p12 \
    --pkinit-pin=1234
    Copy to Clipboard Toggle word wrap
    Note

    The paths to the certificates include /data/ because the persistent storage volume maps to /data/ inside the container.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.

    • Due to a known issue in the interactive replica installation mode, add standard ipa-replica-install options to specify one of the following:

    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

3.5. Next Steps After Installation
Copy link

  • To run the container, use the atomic run command: 

    $ atomic run rhel7/ipa-server
    Copy to Clipboard Toggle word wrap

    If you specified a name for the container when you installed it: 

    $ atomic run --name replica-container rhel7/ipa-server
    Copy to Clipboard Toggle word wrap
  • A running ipa-server container works in the same way as in a standard Identity Management deployment on bare-metal or virtual machine systems. For example, you can enroll hosts to the domain or manage the topology using the command-line interface, the web UI, or JSONRPC-API in the same way as RPM-based Identity Management systems.

This chapter describes how you can migrate a server originally installed in a container to a bare-metal or a virtual machine system. In the following scenario, we migrate to a Red Hat Enterprise Linux system.

This procedure shows how to migrate a containerized Identity Management server to the host system and, optionally, decomission the container.

Procedure

  1. Enroll the host system as an Identity Management replica against the container. If you want to decommission the container with the Identity Management server later, make sure you create the replica with a certificate authority (CA) configured.

    See Installing and Uninstalling Identity Management Replicas.

  2. Migrate the CA master responsibilities from the server in the container to the new replica on the host system.

    See Promoting a Replica to a Master CA Server.

  3. Decommission the server in the container.

    See Chapter 5, Uninstalling Server and Replica Containers.

This chapter describes how you can uninstall an Identity Management server or replica container.

5.1. Uninstalling a Server or Replica Container
Copy link

This procedure shows how to uninstall an Identity Management server or replica container and make sure the server or replica is properly removed from the topology.

Procedure

  1. To ensure that a replica container belonging to an existing topology is properly removed from that topology, use the ipa server-del <container-host-name> command on any enrolled host.

    This step is necessary because the atomic uninstall command does not:

    • Perform checks to prevent disconnected domain level 1 topology or the removal of the last certificate authority (CA), key recovery authority (KRA), or DNS server
    • Remove the replica container from the existing topology

  2. Use the atomic uninstall command, and include the container name and image name: 

    $ atomic uninstall --name <container_name> rhel7/ipa-server
    Copy to Clipboard Toggle word wrap

5.2. Next Steps After Uninstalling
Copy link

  • You can find a backup of the container’s mounted data directory under /var/lib/<container_name>.backup.<timestamp>. If you need to create a new container, the backup enables you to reuse the persistent data stored in the volume.

Part II. Using the sssd Container
Copy link

This part covers how to deploy, configure, update and uninstall the SSSD container on Atomic Host. In addition, this documentation explains how to grant or restrict access to SSSD containers and how to create and use a centralized Kerberos credential cache.

As a system administrator, you can use SSSD in a container to provide external identity, authentication, and authorization services for the Atomic Host system. This chapter describes how to run the SSSD container as privileged, which enables users from external identity sources (Identity Management or Active Directory) to leverage the services running on the Atomic host itself.

Alternatively, you can run the SSSD container as unprivileged, which enables users from external identity sources (Identity Management or Active Directory) to leverage the services running in other containers on the Atomic Host. This is covered in Chapter 7, Deploying SSSD Containers With Different Configurations.

Before you start, see:

To enroll the Atomic Host to an Identity Management server, see:

To enroll the Atomic Host to Active Directory, see:

6.1. Prerequisites
Copy link

  • Upgrade the Atomic Host system before installing the container. See Upgrading and Downgrading in the Red Hat Enterprise Linux Atomic Host 7 Installation and Configuration Guide.

This procedure describes how to install an SSSD container and configure it for enrollment against an Identity Management server. During the installation:

  • Various configuration and data are copied into the container.
  • The ipa-client-install utility for configuring an Identity Management client starts.
  • After a successful enrollment into the Identity Management domain, the configuration and data are copied back to the Atomic Host system.
Prerequisites

You need one of the following:

  • A random password for one-time client enrollment of the Atomic Host system to the Identity Management domain. To generate the password, add the Atomic Host system as an Identity Management host on the Identity Management server, for example: 

    $ ipa host-add <atomic.example.com> --random
[... output truncated ...]
  Random password: 4Re[>5]OB$3K($qYs:M&}B
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

    For details, see Installing a Client in the Linux Domain Identity, Authentication, and Policy Guide.

  • Credentials of an Identity Management user allowed to enroll clients. By default, this is the admin user.
Procedure

  1. Start the sssd container installation by using the atomic install command, and provide the random password or credentials of an IdM user that is allowed to enroll new hosts. In most cases, this is the admin user. 

    # atomic install rhel7/sssd --password "4Re[>5]OB$3K($qYs:M&}B"
[... output truncated ...]
Service sssd.service configured to run SSSD container.
[... output truncated ...]
    Copy to Clipboard Toggle word wrap 
    # atomic install rhel7/sssd -p admin -w <admin_password>
[... output truncated ...]
Service sssd.service configured to run SSSD container.
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

    The atomic install rhel7/sssd command accepts standard ipa-client-install options. Depending on your configuration, you might need to provide additional information using these options. For example, if ipa-client-install cannot determine the host name of your server and the domain name, use the --server and --domain options: 

    # atomic install rhel7/sssd --password "4Re[>5]OB$3K($qYs:M&}B" --server <server.example.com> --domain <example.com>
    Copy to Clipboard Toggle word wrap
    Note

    You can also pass options to ipa-client-install by storing them to the /etc/sssd/ipa-client-install-options file on the Atomic Host before running atomic install. For example, the file can contain: 

    --password=4Re[>5]OB$3K($qYs:M&}B
--server=server.example.com
--domain=example.com
    Copy to Clipboard Toggle word wrap

  2. Start SSSD in the container by using one of the following commands: 

    # atomic run rhel7/sssd
    Copy to Clipboard Toggle word wrap 
    # systemctl start sssd
    Copy to Clipboard Toggle word wrap

  3. Optional. Confirm that the container is running: 

    # docker ps
CONTAINER ID        IMAGE
5859b9366f0f        rhel7/sssd
    Copy to Clipboard Toggle word wrap

  4. Optional. Confirm that SSSD on the Atomic Host resolves identities from the Identity Management domain.

    1. Obtain a Kerberos ticket for an Identity Management user, and log in to the Atomic Host by using the ssh utility. 

      $ atomic run sssd kinit <idm_user>
$ ssh <idm_user>@<atomic.example.com>
      Copy to Clipboard Toggle word wrap

    2. Use the id utility to verify that you are logged in as the intended user: 

      $ id
uid=1215800001(idm_user) gid=1215800001(idm_user) groups=1215800001(idm_user) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
      Copy to Clipboard Toggle word wrap

    3. Use the hostname utility to verify that you are logged in to the Atomic Host system: 

      $ hostname
atomic.example.com
      Copy to Clipboard Toggle word wrap

This procedure describes how to install an SSSD container and configure it to join the Atomic Host system to Active Directory.

Procedure

  1. Save the password of a user allowed to enroll systems to the Active Directory domain, such as the Administrator, in the /etc/sssd/realm-join-password file on the Atomic Host system: 

    # echo <password> > /etc/sssd/realm-join-password
    Copy to Clipboard Toggle word wrap

    Providing the password in the file is necessary because the realm join command does not accept the password as a command-line parameter.

    Note

    If you want to specify a custom container image name later with the atomic install command to use instead of the default name (sssd), add the custom name to the path of the file: /etc/sssd/<custom_container_name>/realm-join-password.

  2. Start the sssd container installation by using the atomic install command, and specify the realm that you want to join. If you are using the default Administrator user account for the operation: 

    # atomic install rhel7/sssd realm join <ad.example.com>
docker run --rm=true --privileged --net=host -v /:/host -e NAME=sssd -e IMAGE=rhel7/sssd -e HOST=/host rhel7/sssd /bin/install.sh realm join ad.example.com
Initializing configuration context from host ...
Password for Administrator:
Copying new configuration to host ...
Service sssd.service configured to run SSSD container.
    Copy to Clipboard Toggle word wrap

    If you are using another user account, specify it with the --user option: 

    # atomic install rhel7/sssd realm join --user <user_name> <ad.example.com>
    Copy to Clipboard Toggle word wrap

  3. Start SSSD in the container by using one of the following commands: 

    # atomic run rhel7/sssd
    Copy to Clipboard Toggle word wrap 
    # systemctl start sssd
    Copy to Clipboard Toggle word wrap

  4. Optional. Confirm that the container is running: 

    # docker ps
CONTAINER ID        IMAGE
5859b9366f0f        rhel7/sssd
    Copy to Clipboard Toggle word wrap

  5. Optional. On the Atomic Host system, confirm that SSSD resolves identities from the Active Directory domain: 

    # id administrator@<ad.example.com>
uid=1397800500(administrator@ad.example.com) gid=1397800513(domain users@ad.example.com)
    Copy to Clipboard Toggle word wrap
Additional Resources

As a system administrator, you can deploy multiple unprivileged SSSD containers that each use a specific identity provider, such as Identity Management or Active Directory. This enables other application containers to use only their preferred identity source.

7.1. Prerequisites
Copy link

  • To use the services provided by the SSSD container from other containers, the client container’s rhel7 base image must include the sssd-client package. However, the default rhel7 base image does not include this package.

    If you need to use the SSSD services from other containers, create your own image for the client container based on the default rhel7 base image and include sssd-client. For details, see Creating Docker images.

To start an SSSD container and join it to an identity resource, such as Active Directory:

  1. Start the SSSD container by using the atomic install command. For example: 

    # atomic install --opt1='--dns=192.0.2.1 --dns-search=idm.example.com --hostname=server.ad.example.com -e SSSD_CONTAINER_TYPE=application --net=default' --name=ad_sssd rhel7/sssd realm join -v ad.example.com
    Copy to Clipboard Toggle word wrap

    The previous example creates an SSSD application container named ad_sssd. Pass the DNS server IP address, search domain, host name, and realm join command to atomic install to automatically join SSSD running in the container to the Active Directory domain.

    Repeat this step for each identity provider for which you want to provide an SSSD container.

  2. Start the container. For example: 

    # atomic run ad_sssd
    Copy to Clipboard Toggle word wrap

To use the SSSD cache in an application container, pass the relevant directories to the docker run command when you start the application container: 

# docker run --rm --name=<container_name> -v=/var/lib/sssd_container/<sssd-container-name>/client/etc/krb5.conf.d:/etc/krb5.conf.d -v=/var/lib/sssd_container/<sssd-container-name>/client/var/lib/sss/pipes/:/var/lib/sss/pipes/ <image_name>
Copy to Clipboard Toggle word wrap

This maps the directories of the SSSD container to the corresponding directory inside the application container.

The application running in the container is now able to authenticate using, for example, the kinit utility or the mod_auth_gssapi module.

For the Identity Management domain, each SSSD container represents itself as a different host, and administrators can set up host-based access control (HBAC) rules to allow or restrict access to individual containers separately.

For details about configuring HBAC rules in Identity Management, see Configuring Host-Based Access Control in the Linux Domain Identity, Authentication, and Policy Guide

As a system administrator, you can centrally authenticate to a Kerberos server to initialize the credential cache. You can also ensure that applications running in containers are able to use this central cache to authenticate without requiring to manage keytab files, authentication, or renewal separately.

9.1. Prerequisites
Copy link

  • To use the services provided by the SSSD container from other containers, the client container’s rhel7 base image must include the sssd-client package. However, the default rhel7 base image does not include this package.

    If you need to use the SSSD services from other containers, create your own image for the client container based on the default rhel7 base image and include sssd-client. For details, see Creating Docker images.

This procedure describes how to install an SSSD container and configure it to join the Atomic Host system to Active Directory.

Procedure

  1. Save the password of a user allowed to enroll systems to the Active Directory domain, such as the Administrator, in the /etc/sssd/realm-join-password file on the Atomic Host system: 

    # echo <password> > /etc/sssd/realm-join-password
    Copy to Clipboard Toggle word wrap

    Providing the password in the file is necessary because the realm join command does not accept the password as a command-line parameter.

    Note

    If you want to specify a custom container image name later with the atomic install command to use instead of the default name (sssd), add the custom name to the path of the file: /etc/sssd/<custom_container_name>/realm-join-password.

  2. Start the sssd container installation by using the atomic install command, and specify the realm that you want to join. If you are using the default Administrator user account for the operation: 

    # atomic install --opt1='--dns=<DNS_server_IP> --dns-search=<DNS_domain> --hostname=<host_name> -e SSSD_CONTAINER_TYPE=application --net=default' rhel7/sssd realm join -v <ad.example.com>
docker run --rm=true --privileged --net=host -v /:/host -e NAME=sssd -e IMAGE=rhel7/sssd -e HOST=/host rhel7/sssd /bin/install.sh realm join -v ad.example.com
Initializing configuration context from host ...
 * Resolving: _ldap._tcp.ad.example.com
 * Performing LDAP DSE lookup on: 192.168.122.105
...
Service sssd.service configured to run SSSD container.
    Copy to Clipboard Toggle word wrap

    If you are using another user account, specify it with the --user option: 

    # atomic install rhel7/sssd realm join --user <user_name> <ad.example.com>
    Copy to Clipboard Toggle word wrap

  3. Start SSSD in the container by using one of the following commands: 

    # atomic run rhel7/sssd
    Copy to Clipboard Toggle word wrap 
    # systemctl start sssd
    Copy to Clipboard Toggle word wrap

  4. Optional. Confirm that the container is running: 

    # docker ps
CONTAINER ID        IMAGE
5859b9366f0f        rhel7/sssd
    Copy to Clipboard Toggle word wrap

  5. Optional. On the Atomic Host system, confirm that SSSD resolves identities from the Active Directory domain: 

    # id administrator@<ad.example.com>
uid=1397800500(administrator@ad.example.com) gid=1397800513(domain users@ad.example.com)
    Copy to Clipboard Toggle word wrap
Additional Resources

9.3. Authenticating to SSSD Running in a Container
Copy link

To authenticate to a Kerberos server using SSSD that runs in a container:

  1. Pass the kinit option to the docker exec command. For example, to authenticate as the administrator user: 

    # docker exec -i <container_name> kinit administrator
Password for administrator@<DOMAIN>:
    Copy to Clipboard Toggle word wrap

  2. Optionally, verify that your Kerberos credential cache is stored in the Kerberos Credential Manager (KCM): 

    # docker exec -i <container_name> klist
Ticket cache: KEYRING:persistent:0:0
Default principal: Administrator@<DOMAIN>

Valid starting     Expires            Service principal
08/11/17 11:51:06  08/11/17 21:51:06  krbtgt/<DOMAIN>@<DOMAIN>
	renew until 08/18/17 11:51:03
    Copy to Clipboard Toggle word wrap

To make a Kerberos cache from an SSSD container available to other container applications, pass the /var/lib/sssd_container/<sssd-container-name>/client/etc/krb5.conf.d and /var/lib/sssd_container/<sssd-container-name>/client/var/lib/sss/pipes/ directories as volumes to the application container. For example: 

# docker run --rm --name=<application_container> -v=/var/lib/sssd_container/<sssd-container-name>/client/etc/krb5.conf.d:/etc/krb5.conf.d/ -v=/var/lib/sssd_container/<sssd-container-name>/client/var/lib/sss/pipes/:/var/lib/sss/pipes/ docker-registry.engineering.redhat.com/idmqe/sssd-client-test:2.0 klist
Copy to Clipboard Toggle word wrap

The previous example executes the klist command in the container and lists the Kerberos tickets managed by the SSSD container.

Note

If you delete the Kerberos ticket from the cache using the kdestroy utility, the application containers can no longer use the ticket.

Chapter 10. Updating SSSD Containers
Copy link

This procedure describes how you can update System Security Services Daemon (SSSD) containers if a new version of the rhel7/sssd image is released.

Procedure

  1. Stop the SSSD service:

    1. If SSSD is running as a system container: 

      # systemctl stop sssd
      Copy to Clipboard Toggle word wrap

    2. If SSSD is running as an application container: 

      # atomic stop <container_name>
      Copy to Clipboard Toggle word wrap

  2. Use the docker rm command to remove the image: 

    # docker rm rhel7/sssd
    Copy to Clipboard Toggle word wrap

  3. Install the latest SSSD image: 

    # atomic install rhel7/sssd
    Copy to Clipboard Toggle word wrap

  4. Start the SSSD service:

    1. If SSSD runs as a system container: 

      # systemctl start sssd
      Copy to Clipboard Toggle word wrap

    2. If SSSD runs as an application container, start each container using the atomic start command: 

      # atomic start <container_name>
      Copy to Clipboard Toggle word wrap

Chapter 11. Uninstalling SSSD Containers
Copy link

This chapter describes how you can uninstall a System Security Services Daemon (SSSD) container.

This procedure describes how to uninstall the System Security Services Daemon (SSSD) container from an Atomic Host system and unenroll the Atomic Host system from the Identity Management domain.

Procedure

  1. Use the atomic uninstall command, and include the image name: 

    # atomic uninstall rhel7/sssd
[... output truncated ...]
Unenrolling client from IPA server
[... output truncated ...]
Client uninstall complete
[... output truncated ...]
    Copy to Clipboard Toggle word wrap

  2. Remove the Atomic Host system’s host entry on an Identity Management server. For example, from the command line: 

    $ ipa host-del <atomic.example.com>
    Copy to Clipboard Toggle word wrap

  3. To prevent the sssd service on the Atomic Host from attempting to start the container that is now unconfigured, remove the systemd unit file for the service and reload the systemd process: 

    # rm /etc/systemd/system/sssd.service
# systemctl daemon-reload
    Copy to Clipboard Toggle word wrap

This procedure describes how to uninstall the System Security Services Daemon (SSSD) container from an Atomic Host system and unenroll the Atomic Host system from the Active Directory domain.

Procedure

  • Use the atomic uninstall command, include the image name, and specify the realm that you want to leave. If you are using the default Administrator user account for the operation: 

    # atomic uninstall rhel7/sssd realm leave <ad.example.com>
    Copy to Clipboard Toggle word wrap

    If you are using another user account, specify it with the --user option: 

    # atomic uninstall rhel7/sssd realm leave --user <user_name> <ad.example.com>
    Copy to Clipboard Toggle word wrap

This appendix describes procedures that help you to troubleshoot IdM and SSSD running in a container, as well as collecting important configuration and log files that you can attach to Red Hat support tickets.

A.1. Creating an sosreport on Atomic Host
Copy link

This section describes how to install and start the rhel7/rhel-tools container, as well as creating an sosreport.

The rhel7/rhel-tools container uses privileged security switches that enables processes running in this container:

  • To interact with all semaphores and shared memory segments on the host
  • To listen to ports and raw IP traffic on the host’s network
  • Interact with all processes on the host

Note that rhel7/rhel-tools runs without any separation from the host. Using the utilities provided by this container is similar as running them as the root user directly on the system.

Procedure

  1. Install the rhel7/rhel-tools container: 

    # docker pull rhel7/rhel-tools
    Copy to Clipboard Toggle word wrap

  2. Start the rhel7/rhel-tools container: 

    # atomic run rhel7/rhel-tools
    Copy to Clipboard Toggle word wrap

  3. Run the sosreport utility: 

    # sosreport
    Copy to Clipboard Toggle word wrap

    The utility stores the archive of the collected information in the /host/var/tmp/sos_tal4k_* file.

  4. Enter exit to leave the container. 

    # exit
    Copy to Clipboard Toggle word wrap
  5. Attach the sosreport archive to a support request.

This section describes how to display the version of installed IdM and SSSD containers. For example, use this information to search the Red Hat Enterprise Linux Release Notes if a problem has been fixed in a newer version.

Procedure

  • Display the version of the rhel7/ipa-server container: 

    # atomic images version rhel7/ipa-server
IMAGE NAME                                            VERSION   IMAGE ID
registry.access.redhat.com/rhel7/ipa-server:latest    4.6.5-29  9d500a8e4296
    Copy to Clipboard Toggle word wrap

  • Display the version of the rhel7/sssd container: 

    # atomic images version rhel7/sssd
IMAGE NAME                                       VERSION   IMAGE ID
registry.access.redhat.com/rhel7/sssd:latest     7.7-12    19e5cab1c905
    Copy to Clipboard Toggle word wrap

This section describes how to create an archive with important SSSD configuration and log files.

Procedure

  1. Stop the sssd container: 

    # docker stop sssd
    Copy to Clipboard Toggle word wrap

  2. Remove the contents of the SSSD cache and log directories: 

    # rm -rf /var/lib/sss/db/* /var/lib/sss/mc/* /var/log/sssd/*
    Copy to Clipboard Toggle word wrap

  3. Edit the /etc/sssd/sssd.conf file, and set the debug_level parameters to 9: 

    [domain/dockerlab.local]
...
debug_level = 9

[nss]
debug_level = 9
    Copy to Clipboard Toggle word wrap

  4. Start the sssd container: 

    docker start sssd
    Copy to Clipboard Toggle word wrap

  5. Create the /tmp/sssd-debug.tar.gz archive that contains the relevant SSSD configuration and log files: 

    # tar czvf /tmp/sssd-debug.tar.gz /etc/sssd/sssd.conf  /etc/nsswitch.conf /etc/krb5.conf /etc/pam.d /etc/samba/smb.conf /var/log/secure /var/log/messages /var/log/sssd
    Copy to Clipboard Toggle word wrap
  6. Attach the /tmp/sssd-debug.tar.gz file to the support case.

A.4. Displaying the IdM client installation log
Copy link

This section describes how you display the IdM client installation log. The log files help you to debug the problem if the client installation fails.

Procedure

  • To display the IdM client installation log: 

    # cat /var/log/sssd/install/ipaclient-install.log
    Copy to Clipboard Toggle word wrap

Appendix B. Revision History
Copy link

The revision numbers below relate to the edition of this manual, not to version numbers of Red Hat Enterprise Linux.

Expand
VersionDate and changeAuthor

7.0-11

Oct 15 2019: Added troubleshooting appendix.

Marc Muehlfeld

7.0-10

Sep 26 2019: Added Granting and Restricting Access to SSSD Containers Using HBAC Rules.

Marc Muehlfeld

7.0-9

Aug 23 2019: Updated introduction of Configuring the SSSD Container to Provide Identity and Authentication Services on Atomic Host.

Marc Muehlfeld

7.0-8

Apr 05 2018: Preparing document for 7.5 GA publication.

Lucie Maňásková

7.0-7

Mar 19 2018: Updated Deploying sssd containers with different configurations.

Lucie Maňásková

7.0-6

Jan 29 2018: Minor fixes.

Aneta Šteflová Petrová

7.0-5

Nov 20 2017: Updated Enrolling to an Identity Management Domain Using an SSSD Container.

Aneta Šteflová Petrová

7.0-4

Sep 12 2017: Added a procedure for uninstalling an SSSD container joined to an AD domain.

Aneta Šteflová Petrová

7.0-3

Aug 28 2017: Updated part Using the sssd container with more user stories and fixes.

Aneta Šteflová Petrová

7.0-2

Aug 14 2017: Updated sections Available Container Images and Joining an Active Directory Domain Using an SSSD Container.

Aneta Šteflová Petrová

7.0-1

Jul 18 2017: Document version for 7.4 GA publication.

Aneta Šteflová Petrová

Legal Notice
Copy link

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat