Home Wiki > Portal:FreeIPA/Installation
Sign up | Login

Portal:FreeIPA/Installation

tagline: From openSUSE

Introduction

Warning: FreeIPA 4.1.4 was available during the latter half of 2015 on Tumbleweed, but it is no longer available in the distribution due to lack of maintenance. This article only serves as a historical reference.

Objective

The installation guide will walk you through the setup of a fully functional and fault-tolerant FreeIPA cluster, plus a FreeIPA client. The entire setup consists of a certificate authority, FreeIPA server and replica, centrally managed automount (for home directory) and sudo rules, enrollment and registration of IPA client machine and user - everything being under the domain of "linuxdom.net".

Prerequisites - Software

As an integrated solution, FreeIPA server and replica run the complete distribution of FreeIPA server softwares, with additional dependencies on:

  • 389 Directory Server
  • Kerberos server
  • Bind (DNS server)
  • NTP (time synchronisation)

For authentication and access, a FreeIPA client needs Kerberos and FreeIPA clients, Yast authentication client module, and SSSD (System Security Services Daemon). Software installation procedures will be detailed in latter sections.

Prerequisites - Machines and Network

We will need a private network under the domain of "linuxdom.net", and three machines in the private network:

  • IPA server - ipa-primary.linuxdom.net (192.168.122.33)
  • IPA replica - ipa-standby.linuxdom.net (192.168.122.27)
  • IPA client - pulautin.linuxdom.net (192.168.122.143)

IPA server and replica must use static IP addresses, and name resolution should be functional and able to resolve the host name to respective IP address in the private network.

If name resolution is not functional or IPA servers (primary and standby) cannot be resolved to their respective IP address, extra caution and steps must be taken during the installation. These steps are detailed in latter sections.

Certificate Authority

Public Key Infrastructure is an integral component in identity management, therefore before installing FreeIPA, we prepare a new Certificate Authority along with necessary certificates for directory, Kerberos, and web services.

openSUSE makes CA management trivial by offering a graphical and step-by-step interface in "Yast CA Management module", installable via:

# zypper install yast2-ca-management

Please note that the Dogtag PKI and Certmonger features bundled with the upstream FreeIPA release are not available in this openSUSE port.

Next for our setup, we will create a new Certificate Authority, and two certificates for IPA server and replica.

Create a new root Certificate Authority

FreeIPA-CA-CreateCA.png

Enter CA details

Launch YaST CA Management, click "Create Root CA", then enter the names, organisational details, and locality details for the new certificate authority.

Click "Next" when finished.


FreeIPA-CA-Advanced.png

Adjust advanced options

Enter a strong password to protect access to the CA management features. Adjust cryptography strength by altering Key Length. Enter desired CA valid period.

Important! Due to a bug, now you have to enter "Advanced Options" and manually set "CA:true" in "Basic Constraints". Click "OK" when done.


FreeIPA-CA-Export.png

Export CA to a file

Review the new CA's details and click "Create", now the new CA is ready!

Back to main screen, click "Enter CA" to enter the new CA, then click "Advanced..." and "Export to File" to save the CA certificate in PEM format to a local file.


Later, we will distribute the saved CA certificate to the IPA server, IPA replica, and all IPA client machines.

Prepare certificate for IPA Server

Each of the directory service, Kerberos service, and web service requires a server certificate to function. They may use separate certificates, however in our setup we will use only one certificate for all three services.

FreeIPA-CA-CreateCertPrimary.png

Enter certificate details

In YaST CA Management module, enter the CA we just created.

Go to "Certificates" tab, and click "Add", then "Add Server Certificate". Fill in certificate organisational and locality details, then enter the server host name as Common Name.

It is vital for Common Name to match server host name.


FreeIPA-CA-ExportCertPrimary.png

Export certificate to a file

Select the server certificate we just created, and click "Export", then "Export to File". The exported file must use PKCS12 format and may not include CA chain. Enter a strong password (PIN) to protect the exported file.


Copy the exported PKCS12 file "ipa-primary.p12" to the IPA Server machine.

Prepare certificate for IPA Replica

The IPA replica also uses server certificates for directory, Kerberos, and web service. Just like how we created the certificate for IPA Server, remember to match Common Name to the host name.

FreeIPA-CA-CreateCertStandby.png

Enter certificate details

In YaST CA Management module, enter the CA and use the familiar routine to create server certificate. Remember to match the Common Name to the host name of IPA replica.


FreeIPA-CA-ExportCertStandby.png

Export certificate to a file

Export IPA replica certificate, also in PKCS12 format, and without CA chain.


Copy the exported PKCS12 file "ipa-standby.p12" to the IPA Server and IPA replica machine.

Common CA and LDAP configuration

Before proceeding with installation or configuration of IPA server, replica, or client, the involved machines must trust the CA we just created. This procedure must be carried out on all machines that are going to run IPA server, replica,or client.

Copy the exported CA certificate (LinuxDomCA.crt) to "/etc/pki/trust/anchors/" and run on each machine:

# update-ca-certificates

Edit global LDAP client configuration /etc/openldap/ldap.conf:

TLS_CACERT  /etc/pki/trust/anchors/LinuxDomCA.crt
URI         ldap://ipa-primary.linuxdom.net ldap://ipa-standby.linuxdom.net
BASE        dc=linuxdom,dc=net

LDAP parameter "URI" and "BASE" are configured for convenience, so that by default LDAP clients will run queries on the redundant cluster of IPA servers.

FreeIPA Server

FreeIPA installation turns a server into a specialised IPA server. For security reasons please avoid using the server for other roles such as web hosting or running business applications. For a rather small organisation (less than 100 users), the server will need approximately 400MB of memory.

Install all FreeIPA packages and dependencies will be installed automatically:

# zypper install 'freeipa-*'

Install

In our setup, the server's host name is expected to be "ipa-primary" and the fully-qualified-domain-name (FQDN) should be in "linuxdom.net" domain, run hostname command to verify:

# hostname
ipa-primary

# hostname -f
ipa-primary.linuxdom.net

If host name or FQDN is incorrect, installation may still proceed, however the names must be manually corrected and entered into hosts file:

# hostnamectl set-hostname ipa-primary.linuxdom.net

# ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default 
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
2: ens3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 52:54:00:73:de:4e brd ff:ff:ff:ff:ff:ff
    inet 192.168.122.33/24 brd 192.168.122.255 scope global ens3
       valid_lft forever preferred_lft forever

# echo '192.168.122.33 ipa-primary.linuxdom.net ipa-primary' >> /etc/hosts

The entry in hosts file must have FQDN listed before the host name.

Installation may now begin. Invoke the ipa-serverinstall command, then the installation wizard (CLI) will start:

# ipa-server-install \
  --ca-cert-file=LinuxDomCA.crt \
  --dirsrv-cert-file=ipa-primary.p12 --dirsrv-pin=p12_password \
  --http-cert-file=ipa-primary.p12 --http-pin=p12_password \
  --pkinit-cert-file=ipa-primary.p12 --pkinit-pin=p12_password

The installation wizard will ask several questions regarding the network environment, IPA name resolution service, and IPA administrative passwords. Carefully answer the questions, and eventually the installation will take several minutes to complete.

The full conversation and output from our linuxdom.net installation is available here: ipa-server-install Example Output

Verify

After server installation is successfully completed, we can verify that FreeIPA is operating properly by running the following commands on the IPA server:

# kinit admin
Password for admin@LINUXDOM.NET: <enter IPA Admin password>

# klist
... Default principal: admin@LINUXDOM.NET ...

# klist -k
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   2 host/ipa-primary.linuxdom.net@LINUXDOM.NET
...

# ipa user-show admin
  User login: admin
  Last name: Administrator
  Home directory: /home/admin
  Login shell: /bin/bash
  UID: 1435400000
  GID: 1435400000
  Account disabled: False
  Password: True
  Member of groups: admins, trust admins
  Kerberos keys available: True

# ipa host-show ipa-primary
  Host name: ipa-primary.linuxdom.net
  Principal name: host/ipa-primary.linuxdom.net@LINUXDOM.NET
  Password: False
  Keytab: True
  Managed by: ipa-primary.linuxdom.net

Congratulations, your IPA server is now running and operational!

Prepare for replica

One IPA server is a single point of failure; to mitigate potential downtime caused by the single IPA server, we will soon install an IPA Replica. Before proceeding with the installation of IPA Replica, the server has to be prepared and hand over a "replica information" file to the replica machine, by running the following command:

# ipa-replica-prepare ipa-standby.linuxdom.net \
  --http-cert-file ipa-standby.p12 \
  --dirsrv-cert-file ipa-standby.p12 \
  --ip-address 192.168.122.27

ipa-replica-prepare wizard (CLI) will ask for IPA directory manager password and passwords for unlocking the file ipa-standby.p12. Eventually, a file called "replica-info-ipa-standby.linuxdom.net.gpg" will be generated.

Copy the file to IPA replica machine, and preparation is complete. The full conversation and output from our linuxdom.net replica preparation is available here: ipa-replica-prepare Example Output

FreeIPA Replica

Once set up, an IPA replica becomes a complete copy of server, sharing the same internal information about users, machines, policies, etc. All IPA replicas are "master"s, and IPA clients may contact any available IPA server or replica. The single point of failure of IPA server is eliminated by the introduction of IPA replica.

The software, network and hardware requirements of an IPA replica is identical to that of an ordinary IPA server. For security reasons please avoid using the replica for other roles such as web hosting or running business applications.

In the previous section we prepared the IPA server for the replica setup, soon we will install the IPA replica. Beginning with package installation, IPA replica uses all FreeIPA packages and dependencies:

# zypper install 'freeipa-*'

Install

First please make sure that CA and LDAP configuration has been carried out on the replica machine, as described in Common CA and LDAP configuration, otherwise replica installation will definitely fail.

Just like an IPA server, the replica also requires the host name and FQDN to be properly configured. The techniques used for verifying host names on IPA server apply here.

After host names are verified, the installation of replica may begin. Invoke the ipa-replica-install command, then the installation wizard (CLI) will start:

# ipa-replica-install \
  --setup-dns --forwarder 8.8.8.8 \
  --skip-conncheck \
  replica-info-ipa-standby.linuxdom.net.gpg

In our setup, the DNS service is enabled in order to provide IPA clients with redundant name resolution servers. he full conversation and output from our linuxdom.net replica installation is available here: ipa-replica-install Example Output

Note that "--skip-conncheck" disables connection check which tests Kerberos, LDAP, and SSH connectivity between a replica and the replicated server. SSH connectivity test will fail unless the replicated server is configured to be its own client; since we are not going to do it, the connection check has to be skipped.

Verify

After replica installation is successfully completed, we can verify that FreeIPA is operating properly by running the following commands on the IPA replica:

# kinit admin
Password for admin@LINUXDOM.NET: <enter IPA admin password>

# klist
... Default principal: admin@LINUXDOM.NET ...

# klist -k
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   2 host/ipa-standby.linuxdom.net@LINUXDOM.NET
...

# ipa host-show ipa-standby
  Host name: ipa-standby.linuxdom.net
  Principal name: host/ipa-standby.linuxdom.net@LINUXDOM.NET
  Password: False
  Keytab: True
  Managed by: ipa-standby.linuxdom.net

# ipa user-show admin
  User login: admin
  Last name: Administrator
  Home directory: /home/admin
  Login shell: /bin/bash
  UID: 1435400000
  GID: 1435400000
  Account disabled: False
  Password: True
  Member of groups: admins, trust admins
  Kerberos keys available: True

Administration

FreeIPA offers a web UI application for administration of all entities and policies. The web UI application runs on every server/replica; administrators can log into the web application remotely via username/password combination. A command line tool "ipa" is available locally on each server/replica, unfortunately it cannot be used for administration of a remote server in this openSUSE port.

FreeIPA-Admin-Login.png

Launch your favourite browser and navigate to any IPA server/replica on HTTPS, enter IPA admin credentials, and explore!


Manage user and hosts

FreeIPA-Admin-NewUser.png

Create demo user "matti"

Navigate to "Identity", "Users", then click "Add".

Fill in user details and enter an initial password. As IPA admin, you may edit user details and reset password at any time.


FreeIPA-Admin-NewHost.png

Create demo host "pulautin"

Navigate to "Identity", "Hosts", then click "Add".

Fill in new machine's host name and IP address. The host name becomes immediately resolvable via IPA DNS service.


Manage automount

Our setup will automatically mount /home directory of IPA clients to an NFS share on a storage server (in this case ipa-primary).

FreeIPA-Admin-NewMount.png

Set up Automount for /home

Navigate to "Network Services", "Automount". Create a new location ("officehome"), and enter NFS location in a new Automount Key.

If your NFS server is Kerberos-enabled, remember to prefix Mount Information with:

-fstype=nfs4 -sec=krb5


Manage sudo

We will give user matti super-power by authorising him to run any command, as anybody, on any host.

FreeIPA-Admin-NewSudo.png

Enter sudo rule details

Navigate to "Policy", "Sudo", then click "Add". Fill in the sudo rules form.


Command line tools

Nearly all administrative tasks can be carried out using command line tool "ipa", which is available locally on each server/replica.

Before running the tool, you must obtain a Kerberos ticket using a user with IPA administrative privilege:

# kinit admin
Password for admin@LINUXDOM.NET: <enter IPA admin password>

# klist
... Default principal: admin@LINUXDOM.NET ...

# ipa host-show ipa-primary
  Host name: ipa-primary.linuxdom.net
  Principal name: host/ipa-primary.linuxdom.net@LINUXDOM.NET
  Password: False
  Keytab: True
  Managed by: ipa-primary.linuxdom.net

For more information and examples, please consult the manual page:

# man ipa

"ipa" cannot be used to administrate a remote IPA server/replica in this openSUSE port.

FreeIPA Client

To make a machine IPA-ready, the system administrator has to take care of enrolment of the machine and setting up authentication client - the process involves using IPA command line tools and YaST Authentication Client module. Install the tools and all necessary dependencies by:

# zypper install freeipa-client yast2-auth-client sssd sssd-ipa krb5-client openldap2-client

Please note that "ipa-client-install", a utility for IPA client configuration in the upstream FreeIPA project, is not available in this openSUSE port.

Remember that all IPA clients (and servers, replicas) must use appropriate CA and LDAP configuration. If this is not yet done on the client machine, please revisit the Common CA and LDAP configuration.

Enrol a new machine

The DHCP server in the private network should be properly configured to match the IPA domain name (linuxdom.net) and announce IPA server (and replicas) as DNS servers. If manual configuration is required on the client machine, enter the domain name and name server addresses in /etc/resolv.conf:

search linuxdom.net
nameserver 192.168.122.33 # ipa-primary.linuxdom.net
nameserver 192.168.122.27 # ipa-standby.linuxdom.net

Configure Kerberos client to work in the IPA realm by editing /etc/krb5.conf:

[libdefaults]
default_realm = LINUXDOM.NET
forwardable = true

[realms]
LINUXDOM.NET = {
  kdc = ipa-primary.linuxdom.net
  kdc = ipa-standby.linuxdom.net
  admin_server = ipa-primary.linuxdom.net
}

[domain_realm]
linuxdom.net = LINUXDOM.NET
.linuxdom.net = LINUXDOM.NET

Parameter "forwardable" makes the creation of initial Kerberos tickets forwardable by default. IPA client self-service single-signon will not work unless the parameter is explicitly set to true.

To complete host enrolment procedure, retrieve the IPA client machine's keytab using the privilege of IPA admin, or any user specifically allowed to retrieve keytab according to policies defined in IPA:

# kinit admin
Password for admin@LINUXDOM.NET: <enter password>

# ipa-getkeytab -s ipa-primary.linuxdom.net -p host/pulautin.linuxdom.net -k /etc/krb5.keytab
Keytab successfully retrieved and stored in: /etc/krb5.keytab

If you decide to use IPA Automount feature that involves an NFSv4, Kerberos-enabled NFS server, remember to retrieve a Kerberos keytab for the enrolled host as well, for example:

# ipa-getkeytab -s ipa-primary.linuxdom.net -p nfs/pulautin.linuxdom.net -k /etc/krb5.keytab
Keytab successfully retrieved and stored in: /etc/krb5.keytab

Verify that keytab is correct by running klist:

# klist -k
Keytab name: FILE:/etc/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   1 host/pulautin.linuxdom.net@LINUXDOM.NET
...

Configure authentication using Yast

The remainder of IPA client configuration is carried out using YaST Authentication Client module.

FreeIPA-Client-Yast1.png

Enable the client and join domain

Launch Authentication Client module.

Tick both "Create Home Directory on Login" and "Enable SSSD Daemon".

Click "New Service/Domain", choose "Service", and enable all of these services: autofs, sudo, nss, pam.

Click "New Service/Domain", choose "Domain", and enter IPA domain name. Choose "ipa" as Identification Provider.

Click "OK" to proceed to the next dialog.


FreeIPA-Client-Yast2.png

Enter IPA server addresses

Enter IPA server (and replica) host name or IP address.


FreeIPA-Client-Yast3.png

Configure for automount and sudo

Previously on IPA administrative web application, we created an Automount service called "officelocation" which automatically mounts /home to an NFS share; specify IPA as "autofs_provider", and enter "officehome" as "ipa_automount_location".

Specify IPA as "sudo_provider" to make our IPA sudo rules effective.

When done, click "OK".


Sudo and Name Service Switch

After going through YaST Authentication Client configuration, the IPA client now accepts both IPA sudo rules and local /etc/sudoers configuration - and the local configuration takes precedence. This is done for safety reasons, to make sure that you are not locked out of sudo access in case of a mistake in IPA policy.

Please thoroughly test IPA Sudo policy, and then edit /etc/nsswitch.conf, find the line:

sudoers: files sss

And replace it with:

sudoers: sss

Local sudo configuration will no longer be effective. Only IPA sudo rules will apply from now on.

Experience the desktop and IPA self-service

Reboot the client machine and login to your favourite desktop using an IPA user's credentials.

FreeIPA-Client-DesktopLogin.png

Desktop login as an IPA user

Enter IPA user name and initial password.

You will be prompted to change your initial password immediately after login.


FreeIPA-Client-FirefoxConf.png

(Optional) Configure Firefox for Single-SignOn

If you wish to enable Single-SignOn to IPA user self-service, open Firefox and naviagate to "about:config".

Search for parameters named "negotiate" and enter IPA domain name into parameter "delegation-uris" and "trusted-uris".


FreeIPA-Client-SelfService.png

User self-service

Launch browser and navigate to any IPA server/replica on HTTPS. You are automatically signed on and are able to change personal details such as telephone number and display name.

Remember to try your IPA sudo policy too.