Product SiteDocumentation Site

6.5. Managing Services

6.5.1. Adding and Editing Service Entries and Keytabs

As with host entries, service entries for the host (and any other services on that host which will belong to the domain) must be added manually to the FreeIPA domain. This is a two step process. First, the service entry must be created, and then a keytab must be created for that service which it will use to access the domain.
By default, FreeIPA saves its HTTP keytab to /etc/httpd/conf/ipa.keytab.

NOTE

This keytab is used for the web UI. if a key were stored in ipa.keytab and that keytab file is delete, the FreeIPA web UI will stop working, because the original key would also be deleted.
Similar locations can be specified for each service that needs to be made Kerberos aware. There is no specific location that must be used, but, when using ipa-getkeytab, you should avoid using /etc/krb5.keytab. This file should not contain service-specific keytabs; each service should have its keytab saved in a specific location and the access privileges (and possibly SELinux rules) should be configured so that only this service has access to the keytab.

6.5.1.1. >Adding Services and Keytabs from the Web UI

  1. Open the Identity tab, and select the Services subtab.
  2. Click the Add link at the top of the services list.
  3. Select the service type from the drop-down menu, and give it a name.
  4. Select the hostname of the FreeIPA host on which the service is running. The hostname is used to construct the full service principal name.
  5. Click the Add button to save the new service principal.
  6. Use the ipa-getkeytab command to generate and assign the new keytab for the service principal.
    # ipa-getkeytab -s server.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e des-cbc-crc
    • The realm name is optional. The FreeIPA server automatically appends the Kerberos realm for which it is configured. You cannot specify a different realm.
    • The hostname must resolve to a DNS A record for it to work with Kerberos. You can use the --force flag to force the creation of a principal should this prove necessary.
    • The -e argument can include a comma-separated list of encryption types to include in the keytab. This supersedes any default encryption type.

    WARNING

    Creating a new key resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

6.5.1.2. >Adding Services and Keytabs from the Command Line

  1. Create the service principal. The service is recognized through a name like service/FQDN:
    # ipa service-add serviceName/hostname
    For example:
    $ ipa service-add HTTP/server.example.com
    -------------------------------------------------------
    Added service "HTTP/server.example.com@EXAMPLE.COM"
    -------------------------------------------------------
      Principal: HTTP/server.example.com@EXAMPLE.COM
      Managed by: ipaserver.example.com
    
  2. Create the service keytab file. This is done using the ipa-getkeytab command. The command requires the Kerberos service principal (-p), the FreeIPA server name (-s), the file to write (-k), and the encryption method (-e). Be sure to copy the keytab to the appropriate directory for the service.
    For example:
    # ipa-getkeytab -s server.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e des-cbc-crc
    • The realm name is optional. The FreeIPA server automatically appends the Kerberos realm for which it is configured. You cannot specify a different realm.
    • The hostname must resolve to a DNS A record for it to work with Kerberos. You can use the --force flag to force the creation of a principal should this prove necessary.
    • The -e argument can include a comma-separated list of encryption types to include in the keytab. This supersedes any default encryption type.

    WARNING

    The ipa-getkeytab command resets the secret for the specified principal. This means that all other keytabs for that principal are rendered invalid.

6.5.2. Adding Services and Certificates for Services

While services can use keytabs, some services require certificates for access. In that case, a service can be added (or modified) to include a certificate with its service entry.

6.5.2.1. Adding Services and Certificates from the Web UI

  1. Open the Identity tab, and select the Services subtab.
  2. Click the Add link at the top of the services list.
  3. Select the service type from the drop-down menu, and give it a name.
  4. Select the hostname of the FreeIPA host on which the service is running. The hostname is used to construct the full service principal name.
  5. Click the Add and Edit button to go directly to the service entry page.
  6. Scroll to the bottom of the page, to the Service Certificate section.
  7. Click the New Certificate button to create the service certificate.

6.5.2.2. Adding Services and Certificates from the Command Line

  1. Create a certificate for the service. Be sure to copy the keytab to the appropriate directory for the service.
    For example:
    $ ipa cert-request --principal=HTTP/web.example.com example.csr

    TIP

    Use the --add option to create the service automatically when requesting the certificate.
    Alternatively, use the getcert command, which creates and manages the certificate through certmonger. The options are described more in Section 18.1, “Requesting a Certificate with certmonger” and .
    $ ipa-getcert request -d /etc/httpd/alias -n Server-Cert -K HTTP/client1.example.com -N 'CN=client1.example.com,O=EXAMPLE.COM'
  2. Create the service principal. The service is recognized through a name like service/FQDN:
    # ipa service-add serviceName/hostname --certificate="CSR"
    For example (this example shortens the certificate):
    $ ipa service-add HTTP/server.example.com --certificate="MIICbTCCAVUCAQ...IzSljdLMYNg=="
    
    -------------------------------------------------------
    Added service "HTTP/server.example.com@EXAMPLE.COM"
    -------------------------------------------------------
      Principal: HTTP/server.example.com@EXAMPLE.COM
      Managed by: ipaserver.example.com
    
    Include the complete certificate request in the --certificate option.

6.5.3. Storing Certificates in NSS Databases

When services use certificates, the certificates and keys can be stored in NSS databases (which may also be used by the services themselves, as well as FreeIPA).
  1. Create the NSS databases.
    $ certutil -N -d /path/to/database/dir
  2. Request the certificate using certutil, an NSS tool.
    $ certutil -R -s "CN=client1.example.com,O=EXAMPLE.COM" -d /path/to/database/dir -a > example.csr
If the FreeIPA domain is using Certificate System for its CA, only the CN of the subject name is used. With a self-signed CA, the subject must match the configured certificate subject base. The FreeIPA server rejects requests with a subject base that differs from this value.

6.5.4. Configuring Clustered Services

The FreeIPA server is not cluster aware. However, it is possible to configure a clustered service to be part of FreeIPA by synchronizing Kerberos keys across all of the participating hosts and configuring services running on the hosts to respond to whatever names the clients use.

6.5.4.1. Configuring Kerberos Credentials for a Clustered Environment

  1. Enroll all of the hosts in the cluster into the FreeIPA domain.
  2. Create any service principals and generate the required keytabs.
  3. Collect any keytabs that have been set up for services on the host, including the host keytab at /etc/krb5.keytab.
  4. Use the ktutil command to produce a single keytab file that contains the contents of all of the keytab files.
    1. For each file, use the rkt command to read the keys from that file.
    2. Use the wkt command to write all of the keys which have been read to a new keytab file.
  5. Replace the keytab files on each host with the newly-created combined keytab file.
  6. At this point, each host in this cluster can now impersonate any other host.
  7. Some services require additional configuration to accommodate cluster members which do not reset hostnames when taking over a failed service.
    • For sshd, set GSSAPIStrictAcceptorCheck no in /etc/ssh/sshd_config.
    • For mod_auth_kerb, set KrbServiceName Any in /etc/httpd/conf.d/auth_kerb.conf.

NOTE

For SSL servers, the subject name or a subject alternative name for the server's certificate must appear correct when a client connects to the clustered host. If possible, share the private key among all of the hosts. If each cluster member contains a subject alternative name which includes the names of all the other cluster members will satisfy any client connection requirements.

6.5.5. Using the Same Service Principal for Multiple Services

Within a cluster, the same service principal can be used for multiple services, spread across different machines.
  1. Retrieve a service principal using the ipa-getkeytab command.
    # ipa-getkeytab -s kdc.example.com -p HTTP/server.example.com -k /etc/httpd/conf/krb5.keytab -e des-cbc-crc
  2. Either direct multiple servers or services to use the same file, or copy the file to individual servers as required.