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:
- How to Install FreeIPA Server on CentOS 7
- How to Install FreeIPA Server on Ubuntu
- How to Install and Configure FreeIPA Server on RHEL / CentOS 8
- Install FreeIPA Server on Rocky Linux 9 / AlmaLinux 9
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
- Install and Use Podman on CentOS 8 / RHEL 8
- How To Install Podman on Ubuntu
- How To Install Docker CE on Linux Systems
- Install Docker CE on Rocky Linux 8 / AlmaLinux 8
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 bashTo run Docker as a non-privileged user, consider setting up the Docker daemon in rootless mode for your user:
dockerd-rootless-setuptool.sh installOr adding user to docker group:
sudo usermod -aG docker $USER
newgrp dockerStep 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 gitBefore 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-containerFor 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 0Build 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 <[email protected]>"
---> Running in f7962c72763b
Removing intermediate container f7962c72763b
---> ea0c2442d175
Successfully built ea0c2442d175
Successfully tagged freeipa-rocky8:latestList 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 209MBStep 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 1Create 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-dataCreate 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-rocky8For 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-rocky8Replace 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=0The 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:latestStep 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.
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
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.
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.COMCheck 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:
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:
