Learn how to - Run FreeIPA Server in Docker / Podman Containers

Felix Williams Containers How to LDAP February 21, 2023

Learn how to – Run FreeIPA Server in Docker / Podman Containers.

Welcome to this guide where we shall be discussing how to set up FreeIPA server on Docker/Podman containers. FreeIPA is an Open Source project sponsored by Red Hat. It is upstream for the commercial Red Hat Identity Manager. On the client-side, there is a client application used to configure target systems.

There are many reasons as to why one would want to install FreeIPA on containers as opposed to running natively on your systems. For other installation methods, have a look at:

FreeIPA system is an ideal system for centrally managing identity, policy, and audit for users and services. It can provide integrated identity management services to clients on Linux, Mac and Windows.

Features of using FreeIPA

Below are some of the features of using FreeIPA

Central Authentication Management – Centralized management of users, machines, and services within large Linux/Unix enterprise environments.
One Time Password (OTP): Provides a popular method for achieving two-factor authentication (2FA).
Fine-grained Access Control: Provides a clear method of defining access control policies to govern user identities and delegation of administrative tasks.
Direct Connect to Active Directory: You can retrieve information from Active Directory (AD) and join a domain or realm in a standard way.
Active Directory Cross-Realm Trust: As System Administrator, you can establish cross-forest Kerberos trusts with Microsoft Active Directory. This allows external Active Directory (AD) users convenient access to resources in the Identity Management domain.
Integrated Public Key Infrastructure (PKI) Service: This provides PKI services that sign and publish certificates for hosts and services, Certificate Revocation List (CRL) and OCSP services for software validating the published certificate, and an API to request, show, and find certificates.

Components of FreeIPA Server

FreeIPA server is comprised of the following projects:

389 Directory Server – Main data store and provides a full multi-master LDAPv3 directory infrastructure.
MIT Kerberos KDC – Provides Single-Sign-on authentication.
Dogtag Certificate System – Provides CA & RA for certificate management functions.
ISC Bind DNS server – for managing Domain names.
Web UI / ipa Command Line tool – Used to centrally manage access control, the delegation of administrative tasks and other network administration tasks.
NTP Server – For time synchronization with local time servers

Run FreeIPA Server in Docker / Podman Containers

In the following sections we show you how to install Docker / Podman and use it to run FreeIPA server in containers.

FreeIPA installation Minimum requirements

4GB RAM
4 vCPUs
Docker/Podman installed

Before you can run FreeIPA server on Docker/Podman, you should ensure that Docker/Podman is installed on your system.

Follow the links below to install Podman/Docker

Add your user account to docker group:

sudo usermod -aG docker $USER
newgrp docker

For Docker Dev quick and automated installation run the commands:

wget -qO- https://get.docker.com/ | sudo bash

To run Docker as a non-privileged user, consider setting up the Docker daemon in rootless mode for your user:

dockerd-rootless-setuptool.sh install

Or adding user to docker group:

sudo usermod -aG docker $USER
newgrp docker

Step 1. Build FreeIPA server image

We need to build a FreeIPA image based on your operating system before we can run the container. Install git tool:

### Ubuntu / Debian ###
sudo apt update
sudo apt install git -y

### CentOS / Fedora ###
sudo yum -y install git

Before that, we will need to clone FreeIPA’s GitHub repo which contains docker files for different Operating Systems.

git clone https://github.com/freeipa/freeipa-container.git
cd freeipa-container

For RHEL based systems, you are required to either set SELinux context or disable SELinux.

sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config
sudo setenforce 0

Build an image as shown below, replacing the DockerFile with one that suits your OS. These DockerFiles are available in the directory we cloned from GitHub.

[root@server freeipa-container]# ls -lh
total 352K
-rw-rw-r-- 1 jkmutai jkmutai 5.2K Ago 20 09:48 Dockerfile.almalinux-8
-rw-rw-r-- 1 jkmutai jkmutai 5.6K Ago 20 09:48 Dockerfile.centos-7
-rw-rw-r-- 1 jkmutai jkmutai 5.2K Ago 20 09:48 Dockerfile.centos-8
-rw-rw-r-- 1 jkmutai jkmutai 5.2K Ago 20 09:48 Dockerfile.centos-8-stream
-rw-rw-r-- 1 jkmutai jkmutai 5.3K Ago 20 09:48 Dockerfile.centos-9-stream
-rw-rw-r-- 1 jkmutai jkmutai 5.0K Ago 20 09:48 Dockerfile.fedora-23
-rw-rw-r-- 1 jkmutai jkmutai 5.0K Ago 20 09:48 Dockerfile.fedora-24
-rw-rw-r-- 1 jkmutai jkmutai 4.9K Ago 20 09:48 Dockerfile.fedora-25
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-26
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-27
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-28
-rw-rw-r-- 1 jkmutai jkmutai 4.7K Ago 20 09:48 Dockerfile.fedora-29
-rw-rw-r-- 1 jkmutai jkmutai 4.7K Ago 20 09:48 Dockerfile.fedora-30
-rw-rw-r-- 1 jkmutai jkmutai 4.6K Ago 20 09:48 Dockerfile.fedora-31
-rw-rw-r-- 1 jkmutai jkmutai 4.9K Ago 20 09:48 Dockerfile.fedora-32
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-33
-rw-rw-r-- 1 jkmutai jkmutai 4.9K Ago 20 09:48 Dockerfile.fedora-34
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-35
-rw-rw-r-- 1 jkmutai jkmutai 4.8K Ago 20 09:48 Dockerfile.fedora-36
-rw-rw-r-- 1 jkmutai jkmutai 4.9K Ago 20 09:48 Dockerfile.fedora-rawhide
-rw-rw-r-- 1 jkmutai jkmutai 5.5K Ago 20 09:48 Dockerfile.rhel-7
-rw-rw-r-- 1 jkmutai jkmutai 4.9K Ago 20 09:48 Dockerfile.rhel-8
-rw-rw-r-- 1 jkmutai jkmutai 5.2K Ago 20 09:48 Dockerfile.rocky-8
....

In my case, I’ll be running FreeIPA on CentOS 8 or RHEL 8 image.

For Docker:

#Build from Rocky Linux 8 image
docker build -t freeipa-rocky8 -f  Dockerfile.rocky-8 .
#Build from Rocky Linux 9 image
docker build -t freeipa-rocky9 -f  Dockerfile.rocky-9 .

#Build from AlmaLinux 8 image
docker build -t freeipa-alma8 -f Dockerfile.almalinux-8 .
#Build from AlmaLinux 9 image
docker build -t freeipa-alma9 -f Dockerfile.almalinux-9 .

#Build from RHEL 8 image
docker build -t freeipa-rhel8 -f Dockerfile.rhel-8 .
#Build from RHEL 9 image
docker build -t freeipa-rhel9 -f Dockerfile.rhel-8 .

#Build from Fedora image
docker build -t freeipa-fed38 -f Dockerfile.fedora-38 .

For Podman:

#Build from Rocky Linux 8 image
podman build -t freeipa-rocky8 -f  Dockerfile.rocky-8 .
#Build from Rocky Linux 9 image
podman build -t freeipa-rocky9 -f  Dockerfile.rocky-9 .

#Build from AlmaLinux 8 image
podman build -t freeipa-alma8 -f Dockerfile.almalinux-8 .
#Build from AlmaLinux 9 image
podman build -t freeipa-alma9 -f Dockerfile.almalinux-9 .

#Build from RHEL 8 image
podman build -t  freeipa-rhel8 -f Dockerfile.rhel-8 .
#Build from RHEL 9 image
podman build -t  freeipa-rhel9 -f Dockerfile.rhel-9 .

#Build from Fedora image
podman build -t freeipa-fed38 -f Dockerfile.fedora-38 .

The build process should take some minutes. A complete build will exit with the information below:

.....
Step 49/51 : EXPOSE 53/udp 53 80 443 389 636 88 464 88/udp 464/udp 123/udp
 ---> Running in da8d1fe2c58c
Removing intermediate container da8d1fe2c58c
 ---> 876327439584
Step 50/51 : RUN uuidgen > /data-template/build-id
 ---> Running in aa40a4e5f35a
Removing intermediate container aa40a4e5f35a
 ---> ce1ab7ef5832
Step 51/51 : LABEL maintainer="FreeIPA Developers <freeipa-devel@lists.fedorahosted.org>"
 ---> Running in f7962c72763b
Removing intermediate container f7962c72763b
 ---> ea0c2442d175
Successfully built ea0c2442d175
Successfully tagged freeipa-rocky8:latest

List images on Podman / Docker:

#Docker
$ docker images
REPOSITORY                          TAG       IMAGE ID       CREATED             SIZE
freeipa-fed36                       latest    4a2fc4dd7bd3   53 minutes ago      863MB
freeipa-alma8                       latest    f52d912f2c6e   About an hour ago   914MB
freeipa-rocky8                      latest    44c6e6219250   About an hour ago   883MB
registry.fedoraproject.org/fedora   36        2ecb6df95994   4 weeks ago         163MB
rockylinux/rockylinux               8         523ffac7fb2e   6 weeks ago         196MB
almalinux/almalinux                 8         6adabb67011e   13 months ago       209MB

Step 2. Running FreeIPA server Container

The next step is to run the FreeIPA server on Podman/Docker containers. The FreeIPA server runs systemd to manage the services in a single container. This means that if you are running on an SELinux enabled system, you need to allow systemd to run in containers by setting the SELinux boolean as below:

sudo setsebool -P container_manage_cgroup 1

Create a data directory for persistent volume of the FreeIPA container. We shall then mount the volume at /data path of the container.

sudo mkdir -p /var/lib/ipa-data

Create the FreeIPA container with the following command.

For Podman:

podman run --name freeipa-server-container -ti 
    -h ipa.example.com --read-only 
    -v /var/lib/ipa-data:/data:Z localhost/freeipa-rocky8

For Docker:

docker run --name freeipa-server-container -ti 
    -h ipa.example.com --read-only 
    -v /sys/fs/cgroup:/sys/fs/cgroup:ro 
    -v /var/lib/ipa-data:/data:Z freeipa-rocky8

Replace ipa.example.com with your FreeIPA domain.

If you run into an error like this below:

IPv6 stack is enabled in the kernel but there is no interface that
has ::1 address assigned. Add ::1 address resolution to 'lo' interface.
You might need to enable IPv6 on the interface 'lo' in sysctl.conf.

You will be required to add the option below.

--sysctl net.ipv6.conf.all.disable_ipv6=0

The above two commands for Podman and Docker automatically initializes the ipa-server-install script of FreeIPA.

You will then be required to key in the information from the prompts.

$ sudo docker run --name freeipa-server-container -ti 
-h ipa.example.com --read-only  
--sysctl net.ipv6.conf.all.disable_ipv6=0 
-v /sys/fs/cgroup:/sys/fs/cgroup:ro 
-v /var/lib/ipa-data:/data:Z freeipa-server 

systemd 239 (239-41.el8_3) running in system mode. (+PAM +AUDIT +SELINUX +IMA -APPARMOR +SMACK +SYSVINIT +UTMP +LIBCRYPTSETUP +GCRYPT +GNUTLS +ACL +XZ +LZ4 +SECCOMP +BLKID +ELFUTILS +KMOD +IDN2 -IDN +PCRE2 default-hierarchy=legacy)
Detected virtualization container-other.
Detected architecture x86-64.
Set hostname to <ipa.example.com>.
Sun Aug 22 07:02:27 UTC 2021 /usr/sbin/ipa-server-configure-first 

The log file for this installation can be found in /var/log/ipaserver-install.log
==============================================================================
This program will set up the IPA Server.
Version 4.9.2

This includes:
  * Configure a stand-alone CA (dogtag) for certificate management
  * Configure the NTP client (chronyd)
  * Create and configure an instance of Directory Server
  * Create and configure a Kerberos Key Distribution Center (KDC)
  * Configure Apache (httpd)
  * Configure the KDC to enable PKINIT

To accept the default shown in brackets, press the Enter key.

Do you want to configure integrated DNS (BIND)? [no]: <yes/no>

Enter the fully qualified domain name of the computer
on which you're setting up server software. Using the form
<hostname>.<domainname>
Example: master.example.com.


Server host name [ipa.example.com]: <Set/Confirm Hostname>

The domain name has been determined based on the host name.

Please confirm the domain name [example.com]: <Confirm domain name>

The kerberos protocol requires a Realm name to be defined.
This is typically the domain name converted to uppercase.

Please provide a realm name [EXAMPLE.COM]:  <Confirm Real name>
Certain directory server operations require an administrative user.
This user is referred to as the Directory Manager and has full access
to the Directory for system management tasks and will be added to the
instance of directory server created for IPA.
The password must be at least 8 characters long.

Directory Manager password: <Enter Password>
Password (confirm): <Confirm Password>

The IPA server requires an administrative user, named 'admin'.
This user is a regular system account used for IPA server administration.

IPA admin password: <Enter Password>
Password (confirm):  <Confirm Password>

Do you want to configure chrony with NTP server or pool address? [no]: 

The IPA Master Server will be configured with:
Hostname:       ipa.example.com
IP address(es): 172.17.0.2
Domain name:    example.com
Realm name:     EXAMPLE.COM

The CA will be configured with:
Subject DN:   CN=Certificate Authority,O=EXAMPLE.COM
Subject base: O=EXAMPLE.COM
Chaining:     self-signed

Continue to configure the system with these values? [no]: yes

The following operations may take some minutes to complete.
Please wait until the prompt is returned.

.......

The above prompt will:

Configure a stand-alone CA (dogtag) for certificate management
Configure the NTP client (chronyd)
Create and configure an instance of Directory Server
Create and configure a Kerberos Key Distribution Center (KDC)
Configure Apache (httpd)
Configure the KDC to enable PKINIT

A complete installation will give the output below:

Configuring example.com as NIS domain.
Client configuration complete.
The ipa-client-install command was successful

Please add records in this file to your DNS system: /tmp/ipa.system.records.jafe12ca.db
==============================================================================
Setup complete

Next steps:
	1. You must make sure these network ports are open:
		TCP Ports:
		  * 80, 443: HTTP/HTTPS
		  * 389, 636: LDAP/LDAPS
		  * 88, 464: kerberos
		UDP Ports:
		  * 88, 464: kerberos
		  * 123: ntp

	2. You can now obtain a kerberos ticket using the command: 'kinit admin'
	   This ticket will allow you to use the IPA tools (e.g., ipa user-add)
	   and the web user interface.
	3. Kerberos requires time synchronization between clients
	   and servers for correct operation. You should consider enabling chronyd.

Be sure to back up the CA certificates stored in /root/cacert.p12
These files are required to create replicas. The password for these
files is the Directory Manager password
The ipa-server-install command was successful
FreeIPA server does not run DNS server, skipping update-self-ip-address.
Created symlink /etc/systemd/system/container-ipa.target.wants/ipa-server-update-self-ip-address.service → /usr/lib/systemd/system/ipa-server-update-self-ip-address.service.
Created symlink /etc/systemd/system/container-ipa.target.wants/ipa-server-upgrade.service → /usr/lib/systemd/system/ipa-server-upgrade.service.
Removed /etc/systemd/system/container-ipa.target.wants/ipa-server-configure-first.service.
FreeIPA server configured.

FreeIPA External access

If you intend to use FreeIPA externally, you will have to forward the neccessary ports to the host with the -p flag. You can also specify the environment variables during the installation such as the password.

docker run -e PASSWORD=Secret@123  -p 53:53/udp -p 53:53 
    -p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 
-p 88:88/udp -p 464:464/udp -p 123:123/udp ...

A complete command with the ports exposed would look like this:

docker run --name freeipa-server -ti 
	-h ipa.example.com -p 53:53/udp -p 53:53 
	-p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 -p 88:88/udp 
       	-p 464:464/udp -p 123:123/udp --read-only  
	--sysctl net.ipv6.conf.all.disable_ipv6=0 -v /sys/fs/cgroup:/sys/fs/cgroup:ro 
	-v /var/lib/ipa-data:/data:Z freeipa-server:latest

Step 3. Access FreeIPA server on Web

The next step is to access FreeIPA on the web interface. Navigate to https://ipa.example.com or the IP/Hostname of the Docker/Podman host.

Run FreeIPA Server in Docker / Podman Containers 1

You will be required to login with the user admin and the password you created during the installation.

After a successful login, you will be redirected to the FreeIPA dashoard

Run FreeIPA Server in Docker / Podman Containers 2

Step 4. Manage users using FreeIPA

The next step is to manage users using FreeIPA

Users can be added using the command-line interface of the Docker/Podman container or the web interface.

For the web option, click on the “Add” button under the “Active users” section to add the user.

Run FreeIPA Server in Docker / Podman Containers 3

Step 5: Connect Clients to FreeIPA Server

To connect a client to the FreeIPA instance, we need to have installed IPA client on your system. Follow the guide below to set up IPA client:

How To Install FreeIPA Client on CentOS 8 / RHEL 8

Add the client to FreeIPA server

sudo ipa-client-install --hostname=centos8.example.com 
 --mkhomedir 
 --server=ipa.example.com 
 --domain example.com 
 --realm EXAMPLE.COM

Check and verify that the added user is available:

$ id user1
uid=1676000008(user1) gid=1676000008(user1) groups=1676000008(user1),1676000007(wheel-users)

Step 6: Securing FreeIPA Server With Let’s Encrypt

If your FreeIPA Server is on a Cloud instance you can secure it with Let’s Encrypt Certificate as discussed in our guide:

Secure FreeIPA Server With Let’s Encrypt SSL Certificate

Conclusion

The above steps summarize how to set up FreeIPA server on Docker/Podman. Feel free to get in touch in case you encounter problems setting up this environment. Cheers!

Next reading:

Cart

Learn how to – Run FreeIPA Server in Docker / Podman Containers