The FreeIPA Master Class - Part 1

Published Jan. 20, 2025, 3:27 p.m. by dwest

Introduction to Directory Servers

If you’ve ever found yourself managing a growing number of servers, desktops, web applications, and other shared services, you’ve probably run into the pain of maintaining user accounts across all of them. This is where directory servers come in. A directory server is a system designed to manage user accounts across multiple devices and handle login access in a consistent way. Like the name suggests, a directory server keeps a database, or “directory,” of usernames, passwords, and other account details that can be used across many systems. It works a bit like a digital phone book or school directory that helps identify users and determine what they have access to. The goal is to create a single sign-on experience where one account can be used to log in to multiple systems.

Unlike a physical directory, a directory server stores much more information about the network. This includes users, groups, computers, services, and other resources. Directory servers are a core part of enterprise IT because they handle authentication, authorization, and access control. The most well-known example is Microsoft Active Directory, which most Windows-based businesses depend on. But there are also open-source alternatives for other environments, such as OpenLDAP, SMB-LDAP, and older solutions like NIS. These often use the LDAP protocol to manage identity information. Even Apple had their own option called Open Directory, which bundled together several open-source tools to manage Mac environments in a way similar to Active Directory.

In this blog series, we’re going to look at FreeIPA, an enterprise-grade directory service that is mainly focused on Linux. At its core, FreeIPA is an identity management system, but it also integrates several powerful tools to offer LDAP, Kerberos, DNS, and certificate authority services all in one package. Whether you’re managing a single service or a network spanning multiple sites, FreeIPA gives you a centralized and scalable way to control access across your environment.

Core Components of FreeIPA

FreeIPA is built from several open-source projects, each responsible for a specific function. In true open-source fashion, where each tool focuses on doing one thing well, these components work together to provide a full-featured identity management solution. The core components include:

389 Directory Server - This is the LDAP server that stores and manages identity data such as users, groups, computers, policies, and services.
MIT Kerberos - Handles authentication and single sign-on (SSO) using tickets, which helps avoid sending passwords over the network.
Dogtag Certificate System - Acts as the certificate authority (CA). It issues, renews, and revokes SSL and TLS certificates. These certificates are used to establish trust between devices and services on the network.
BIND - Manages DNS records for hosts and services when DNS integration is enabled. This allows FreeIPA to automate and manage name resolution within its domain.
Samba - Provides cross-forest trust with Active Directory. It is optional, but needed if you want to sync users from AD or allow access to SMB and CIFS file shares.
Apache and Python - These power the FreeIPA web interface. The WebUI makes it easier to manage users, groups, hosts, and policies. It can also give users a way to manage their own account settings.
SSSD (System Security Services Daemon) - This runs on client systems and talks to FreeIPA servers. It caches credentials, handles access control, and makes sure clients can keep working even if the server is temporarily offline. It is not part of the server itself, but it is an important part of the overall system.

Installing FreeIPA

The process for installing a FreeIPA Master significantly changes as newer versions are released and newer operating systems change their packaging structure. At the time of this writing, the FreeIPA Masters are first installed as a client. From there, they are upgraded to a FreeIPA Master and then a FreeIPA CA. These instructions are written with the expectation that you will be running them on CentOS-Stream, but should also work on RedHat Enterprise and other RHEL-based distro’s with minimal alterations.

Install FreeIPA Client

This is probably one of the simplest steps you have to perform. Basically, you just need to install the client from you package manager or use a 3rd party provider. This part of the process is exactly the same whether you are setting up a FreeIPA master or just a client. FreeIPA will handle all the certificate generation and access control for you.

Install the IPA client ** CentOS 7/8/9/10 dnf install ipa-client

** Ubuntu/Debian apt-get install freeipa-client

Bind the host to an IPA Master on the current domain. If this is going to be the “First Master”, then you can leave off the “–server” flags. ipa-client-install –server=$IPA_MASTER1.example.com –server=$IPA_MASTER2.example.com –domain=example.com –mkhomedir

Note: If it fails due to a pre-existing entry, you can either remove it manually or add the “–force-join” flag at the end.

Install FreeIPA Master

This part if fairly simple since you are installing the “First Master” in the network. The “First Master” will become the CA and manage the CRL and CA renewals. While other replicas in the network can also be CA’s, the “First Master” is special. This can be changed to a different host at a later time.

Install the “freeipa-server” package dnf install freeipa-server
Now run the FreeIPA installer tool. Unless you plan on managing DNS with it, you will need to skip the DNS server setup. ipa-server-install

Note: For NTP servers, you can use either “pool.ntp.org” or “0.pool.ntp.org” if the current setup does not allow for access to the example internal ones. If there were no errors, then you should get a message saying “The ipa-server-install command was successful”

Install FreeIPA Replica

The method for adding a FreeIPA Replica has changed with the newer domain level. Before, you had to generate a replica file on an active IPA master and then transfer it over to the new host to perform the install. Now, you just need to join the host to the domain as a client and then upgrade it to a replica. This process is much easier than before, but only works with IPA Domain Levels 1 or greater.

In EL8, Redhat started using package modules for some software packages. In EL9, they scrapped it and went back to normal package repos. However, if you need to install FreeIPA on EL8, you will need to enable the idm:DL1 modules in your system.

You can enable it with the following command:

dnf module enable idm:DL1

Install the IPA client and server dnf install ipa-client freeipa-server
Bind the host to an IPA Master on the current domain ipa-client-install –server=$IPA_MASTER.example.com –domain=example.com –mkhomedir

Note: If it fails due to a pre-existing entry, you can either remove it manually or add the “–force-join” flag at the end.

Install/Upgrade the client to an IPA Replica and setup the CA on it ipa-replica-install –setup-ca

Note: If you do not run –setup-ca, then you will not install the CA service on the system. If you would like to do this after the fact, then you can run ipa-ca-install. If there were no errors, then you should get a message saying “The ipa-replica-install command was successful”

Commands

Below is a list of common commands that you will often use when administering FreeIPA.

Check status of IPA services ipactl status
Stop, start and restart the FreeIPA services. The last one will allow for the system to start up even if one of the services (such as Tomcat) fails. ipactl stop ipactl start ipactl restart ipactl restart –ignore-service-failures
List replication status for the current host ipa-replica-manage list -v $(hostname) ; ipa-csreplica-manage list -v $(hostname)
List current replication agreements/segments

    $ ipa topologysegment-find
    Suffix name: domain
    ------------------
    8 segments matched
    ------------------
      Segment name: new_segment
      Left node: server1.example.com
      Right node: server2.example.com
      Connectivity: both

Note: If you change the Suffix name to ‘ca’, it will list the CA replication agreements/segments

Add replication agreements/segments between replicas ** LDAP Replication

$ ipa topologysegment-add
Suffix name: domain
Left node: server1.example.com
Right node: server2.example.com
Segment name [server1.example.com-to-server2.example.com]: new_segment
---------------------------
Added segment "new_segment"
---------------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

Add CA replication agreements/segments between replicas ** CA Replication

$ ipa topologysegment-add
Suffix name: ca
Left node: server1.example.com
Right node: server2.example.com
Segment name [server1.example.com-to-server2.example.com]: new_segment
---------------------------
Added segment "new_segment"
---------------------------
  Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

Show replication agreement for a specific segment

$ ipa topologysegment-show
Suffix name: domain
Segment name: new_segment
  Left node: server1.example.com
  Right node: server2.example.com
  Connectivity: both

Allow for depricated security protocols. This should only be used when upgrading a legacy system to current standards. ex. SSL 1.0, 1.1 update-crypto-policies –set LEGACY
Show the current domain level ipa domainlevel-get
Change the current domain level to ‘1’ ipa domainlevel-set 1

Note: This will update the domain level on ALL FreeIPA servers in the network at the same time. Also, you can not go backwards in level. Once you do this, there is no going home again. Enjoy ;)

Reinitialize the IPA Replica from another replica. Basically, it re-syncs everything from the upstream server to resolve any conflicts. ipa-replica-manage re-initialize –from $IPA_REPLICA.example.com –verbose
Manually renew the CA certificate. Normally, this should be automatic, but it is possible that something went wrong. ipa-cacert-manage renew
Display current global group policy

$ ipa pwpolicy-show
  Group: global_policy
  Max lifetime (days): 3650
  Min lifetime (hours): 1
  History size: 0
  Character classes: 0
  Min length: 8
  Max failures: 6
  Failure reset interval: 60
  Lockout duration: 600

Change minimum password lifetime requirement

$ ipa pwpolicy-mod --minlife=0 global_policy
  Group: global_policy
  Max lifetime (days): 3650
  Min lifetime (hours): 0
  History size: 0
  Character classes: 0
  Min length: 8
  Max failures: 6
  Failure reset interval: 60
  Lockout duration: 600

Update the LDAP schema and configuration files. This is useful when updating the server packages and the auto-upgrade does not successfully run. ipa-server-upgrade
Update the local IPA cert database with local certificates from the server. This helps to ensure that all IPA server certificates are stored in IPA. ipa-certupdate

Procedures

These instructions are written with the expectation that you will be running them on CentOS-Stream.

Install FreeIPA Client

This is probably one of the simplest steps you have to perform. Basically, you just need to install the client and the install it to 1 or 2 masters. If the system is in the DMZ, make sure you bind it to the IPA masters in the DMZ. FreeIPA will handle all the certificate generation and access control for you.

Install the IPA client ** CentOS dnf install ipa-client

** Ubuntu apt-get install freeipa-client

Bind the host to an IPA Master on the current domain ipa-client-install –server=$IPA_MASTER1.example.com –server=$IPA_MASTER2.example.com –domain=example.com –mkhomedir

Note: If it fails due to a pre-existing entry, you can either remove it manually or add the “–force-join” flag at the end.

Enable the DL1 AppStream module

Before you can install a FreeIPA Master or Replica, you will need to enable the “DL1” module that can be found in the “AppStream” repository

You can determine which module provides the packages for it by running the following:

$ dnf module list idm
  Updating Subscription Management repositories.
  Updating Subscription Management repositories.
  Last metadata expiration check: 0:16:51 ago on Sat 29 Dec 2018 09:52:44 AM EAT.
  Red Hat Enterprise Linux 8 for x86_64 - AppStream Beta (RPMs)
  Name         Stream             Profiles                                          Summary
  idm          DL1                adtrust, client, dns, server, default [d]         The Red Hat Enterprise Linux Identity Management system module
  idm          client [d]         default [d]                                       RHEL IdM long term support client module
  Hint: [d]efault, [e]nabled, [x]disabled, [i]nstalled

You can see more info about which packages this provides by running the following: dnf module info idm:DL1
Install this module using YUM/DNF dnf install @idm:DL1

Install FreeIPA Master

Install the “freeipa-server” package dnf install freeipa-server
Now run the FreeIPA installer tool. Unless you plan on managing DNS with it, you will need to skip the DNS server setup. ipa-server-install

Install FreeIPA Replica

You can enable it with the following command:

dnf module enable idm:DL1

Install the IPA client and server dnf install ipa-client freeipa-server
Bind the host to an IPA Master on the current domain ipa-client-install –server=$IPA_MASTER.example.com –domain=example.com –mkhomedir

Note: If it fails due to a pre-existing entry, you can either remove it manually or add the “–force-join” flag at the end.

Install/Upgrade the client to an IPA Replica and setup the CA on it ipa-replica-install –setup-ca

Uninstall FreeIPA and Replication Agreements

This is usually used if something went wrong during the install process or FreeIPA is acting weird. You will need to completely clean out all records for the replica and uninstall the the host.

Uninstall the FreeIPA Server ipa-server-install –uninstall

Note: If something fails during the uninstall, you can add the “–force” flag at the end to force it to completion

Uninstall the FreeIPA Client ipa-client-install –uninstall
Remove IPA Replica from directory ipa-replica-manage del $REPLICA_NAME.example.com

Note: If this fails due to connectivity issues, then you can add the “–force” flag to forcefully remove it and the “–clean” flag to clean up any orphaned records

Remove FreeIPA Packages dnf remove -y ipa-client freeipa-server @idm:DL1

Migrate Accounts to new FreeIPA Master and Environment

This is used if the current IPA environment has unrecoverable issues, such as the CA API not working correctly. This will not migrate any kerberos data since the new KDC will be issuing those tickets from now one. However, passwords will get migrated pre-hashed, so it will not generate Kerberos keys unless it can get a clear text entry. This just means that users will have to use the “Migration” service to update their passwords in the directory. The migration tool will need to be performed on the destination IPA server and will require logging in with an account on the source IPA server. You can run it with the following:

ipa migrate-ds \
  --bind-dn="cn=Directory Manager" \
  --user-container=cn=users,cn=accounts \
  --group-container=cn=groups,cn=accounts \
  --group-objectclass=posixgroup \
  --user-ignore-attribute=  {krbPrincipalName,krbextradata,krblastfailedauth,krblastpwdchange,krblastsuccessfulauth,krbloginfailedcount,krbpasswordexpiration,krbticketflags,krbpwdpolicyreference,mepManagedEntry} \
  --user-ignore-objectclass=mepOriginEntry \
  --with-compat \
  ldap://$OLD_MASTER.example.com

Note: This will probably fail on a few of the default accounts, such as “admin” and “root”, but that should be fine.

Failed user:
  admin: This entry already exists
  root: Kerberos principal root@example.COM already exists. Use 'ipa user-mod' to set it manually.
Failed group:
  admins: This entry already exists. Check GID of the existing group. Use --group-overwrite-gid option to overwrite the GID
  editors: This entry already exists. Check GID of the existing group. Use --group-overwrite-gid option to overwrite the GID
----------
Passwords have been migrated in pre-hashed format.
IPA is unable to generate Kerberos keys unless provided
with clear text passwords. All migrated users need to
login at https://your.domain/ipa/migration/ before they
can use their Kerberos accounts.

Password migrations can be handled by each user at the following site: * https://$IPA_MASTER.galois.com/ipa/migration/

Promote Replica to Renewal and CRL Master

If you fail to do this before removing your “First Master” from the FreeIPA cluster, then you might be in for a world of hurt. While all FreeIPA replicas are considered masters, there is a special “First Master” that usually controls the certificate renewals and CRL. It is better to only have one IPA Master do this, otherwise you might get some conflicting records. It is also possible to do this after the fact, but it can be much more difficult or fail to do so..

Determine which host is the current renewal master ldapsearch -H ldap://$HOSTNAME -D ‘cn=Directory Manager’ -W -b ‘cn=masters,cn=ipa,cn=etc,dc=example,dc=com’ ‘(&(cn=CA)(ipaConfigString=caRenewalMaster))’ dn
Set current host as renewal master ipa-csreplica-manage set-renewal-master

Enable CRL updates on the new master by changing the following to “true”. Make sure the replicas all have this set to “false”.

    /etc/pki/pki-tomcat/ca/CS.cfg
ca.crl.MasterCRL.enableCRLCache=true
ca.crl.MasterCRL.enableCRLUpdates=true

On each of the Replicas, tell apache to redirect CRL requests to the new CRL master

/etc/httpd/conf.d/ipa-pki-proxy.conf
# Only enable this on servers that are not generating a CRL
RewriteRule ^/ipa/crl/MasterCRL.bin https:///ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]

Restart the Tomcat service systemctl restart pki-tomcatd@pki-tomcat

Add Samba Support

Most of this should be taken care of by Puppet, with the exception of manually adding the CIFS principal for your Samba server. It should allow users to login to their Samba share using their FreeIPA credentials. It might work with FreeNAS, but we do not have a currently working setup for it. Assuming you are installing this on a CentOS 7/8/Stream server, here are the steps for binding Samba to FreeIPA.

Install the required packages on the FreeIPA server and Samba server ** FreeIPA Server yum install freeipa-server-trust-ad ** Samba Server yum install samba samba-client samba-common sssd-libwbclient cifs-utils
On CentOS 8/Stream, you will need to enable the ‘adtrust’ stream. ex. dnf install idm:DL1/adtrust
Initialize CIFS support on each FreeIPA Server. This will automatically generate the SID’s for any existing user that does not have one assigned to them. It should already be done on existing IPA servers, but new ones will need to have this ran. ** FreeIPA Server

$ ipa-adtrust-install
Enable trusted domains support in slapi-nis? [no]: yes
Do you want to run the ipa-sidgen task? [no]: yes

Note: Running the ipa-sidgen task should only need to be done once

Make sure the Samba server is joined to the realm

    ipa-client-install --server=.example.com> --server=.example.com --mkhomedir
    authconfig --enablesssdauth --enablemkhomedir --update

Add the CIFS principal for Samba on the FreeIPA server ipa service-add cifs/samba_server_name.example.com
Install the keytab on the Samba server ipa-getkeytab -s .example.com> -p cifs/samba_server_name.example.com -k /etc/samba/samba.keytab
Make sure your Samba config file is setup. Here is a config example: /etc/samba/smb.conf

    #
    # smb.conf for hosts on internal subnets
    #
    # file maintained by puppet. local edits will be lost!
    #
    # ======================================================================

    # Global Configuration
    [global]
        debug pid = yes
        realm = example.COM
        workgroup = example
        domain master= yes
        ldap group suffix = cn=groups,cn=accounts
        ldap machine suffix = cn=computers,cn=accounts
        ldap ssl = no
        ldap suffix = dc=example,dc=com
        ldap user suffix = cn=users,cn=accounts
        log file = /var/log/samba/log.%m
        max log size = 100000
        follow symlinks = yes
        wide links = yes
        unix extensions = no
        domain logons = Yes
        registry shares = Yes
        disable spoolss = Yes
        dedicated keytab file = FILE:/etc/samba/samba.keytab
        kerberos method = dedicated keytab
        passdb backend = ipasam:ldaps://foresight.example.com ldaps://hindsight.example.com
        security = USER
        create krb5 conf = No
        rpc_daemon:lsasd = fork
        rpc_daemon:epmd = fork
        rpc_server:tcpip = yes
        rpc_server:netlogon = external
        rpc_server:samr = external
        rpc_server:lsasd = external
        rpc_server:lsass = external
        rpc_server:lsarpc = external
        rpc_server:epmapper = external
        ldapsam:trusted = yes
        idmap config * : backend = tdb

        ldap admin dn = cn=Directory Manager

    # Shares
    [some_directory_share]
      comment = Example Share
      path = /srv/some_directory
      valid users = @admins
      browseable = no
      writeable = yes
      read only = no
      inherit acls = Yes

    #
    # EOF
    #

If you are sharing the home directories on an SE Linux system, make sure you enable the boolean for it. ex. setsebool -P samba_enable_home_dirs on
Restart the Samba service systemctl restart smb
Test from a Samba Client to ensure that you can make a connection

kinit @example.COM
smbclient -k -L samba_server_name.example.com
smbclient -k //samba_server_name.example.com/some_directory_share

Download Certificate Authority

FreeIPA uses a self-signed certificate for its web interface by default. This is because it is the certificate signing authority for the network and considers itself to be trusted. However, most web browsers frown upon self-signed certificates because the signing authority is not known. When visiting a website with a self-signed certificate, your browser will throw up a big nasty error saying the Certificate Authority can not be trusted. Some browsers will even prevent you from accepting the risk and continuing to that website unprotected. This is because your web browser does not know about FreeIPA as a CA by default an will try to protect you by preventing access to it. One solution is to use a real certificate for the web interface. This is a little tricky and there seems to be issues when you mix HTTPS and LDAPS certificates with different signing authorities. The other option is to import the Certificate Authority as a trusted authority into your web browser, keychain, etc. This certificate can be downloaded using the following command:

openssl s_client -connect ipa.example.com:443 -showcerts < /dev/null > ipa.example.com_ca.crt

The FreeIPA Master Class - Part 1

Introduction to Directory Servers

Core Components of FreeIPA

Installing FreeIPA

Install FreeIPA Client

Install FreeIPA Master

Install FreeIPA Replica

Commands

Procedures

Install FreeIPA Client

Enable the DL1 AppStream module

Install FreeIPA Master

Install FreeIPA Replica

Uninstall FreeIPA and Replication Agreements

Migrate Accounts to new FreeIPA Master and Environment

Promote Replica to Renewal and CRL Master

Enable CRL updates on the new master by changing the following to “true”. Make sure the replicas all have this set to “false”.

Add Samba Support

Download Certificate Authority

Similar posts

0 comments

Add a new comment

Search

Categories

Popular Posts