Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 7. Installing an IdM server: Without integrated DNS, with an external CA as the root CA

This chapter describes how you can install a new Identity Management (IdM) server, without integrated DNS, that uses an external certificate authority (CA) as the root CA.

Note

Red Hat strongly recommends installing IdM-integrated DNS for basic usage within the IdM deployment: When the IdM server also manages DNS, there is tight integration between DNS and native IdM tools which enables automating some of the DNS record management.

For more details, see Planning your DNS services and host names.

7.1. Options used when installing an IdM CA with an external CA as the root CA

You may want to install an Identity Management IdM certificate authority (CA) with an external CA as the root CA if one of the following conditions applies:

  • You are installing a new IdM server or replica by using the ipa-server-install command.
  • You are installing the CA component into an existing IdM server by using the ipa-ca-install command.

You can use following options for both commands that you can use for creating a certificate signing request (CSR) during the installation of an IdM CA with an external CA as the root CA.

--external-ca-type=TYPE
Type of the external CA. Possible values are generic and ms-cs. The default value is generic. Use ms-cs to include a template name required by Microsoft Certificate Services (MS CS) in the generated CSR. To use a non-default profile, use the --external-ca-profile option in conjunction with --external-ca-type=ms-cs.
--external-ca-profile=PROFILE_SPEC

Specify the certificate profile or template that you want the MS CS to apply when issuing the certificate for your IdM CA.

Note that the --external-ca-profile option can only be used if --external-ca-type is ms-cs.

You can identify the MS CS template in one of the following ways:

  • <oid>:<majorVersion>[:<minorVersion>]. You can specify a certificate template by its object identifier (OID) and major version. You can optionally also specify the minor version.
  • <name>. You can specify a certificate template by its name. The name cannot contain any : characters and cannot be an OID, otherwise the OID-based template specifier syntax takes precedence.
  • default. If you use this specifier, the template name SubCA is used.

In certain scenarios, the Active Directory (AD) administrator can use the Subordinate Certification Authority (SCA) template, which is a built-in template in AD CS, to create a unique template to better suit the needs of the organization. The new template can, for example, have a customized validity period and customized extensions. The associated Object Identifier (OID) can be found in the AD Certificates Template console.

If the AD administrator has disabled the original, built-in template, you must specify the OID or name of the new template when requesting a certificate for your IdM CA. Ask your AD administrator to provide you with the name or OID of the new template.

If the original SCA AD CS template is still enabled, you can use it by specifying --external-ca-type=ms-cs without additionally using the --external-ca-profile option. In this case, the subCA external CA profile is used, which is the default IdM template corresponding to the SCA AD CS template.

7.2. Interactive installation

During the interactive installation using the ipa-server-install utility, you are asked to supply basic configuration of the system, for example the realm, the administrator’s password and the Directory Manager’s password.

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Follow this procedure to install a server:

  • Without integrated DNS
  • With an external certificate authority (CA) as the root CA

Prerequisites

  • You have determined the type of the external CA to specify with the --external-ca-type option. See the ipa-server-install(1) man page for details.

  • If you are using a Microsoft Certificate Services certificate authority (MS CS CA) as your external CA: you have determined the certificate profile or template to specify with the --external-ca-profile option. By default, the SubCA template is used.

    For more information about the --external-ca-type and --external-ca-profile options, see Options used when installing an IdM CA with an external CA as the root CA.

Procedure

  1. Run the ipa-server-install utility with the --external-ca option.

    • If you are using the Microsoft Certificate Services (MS CS) CA, also use the --external-ca-type option and, optionally, the --external-ca-profile option: 

      [root@server ~]# ipa-server-install --external-ca --external-ca-type=ms-cs --external-ca-profile=<oid>/<name>/default

    • If you are not using MS CS to generate the signing certificate for your IdM CA, no other option may be necessary: 

      # ipa-server-install --external-ca

  2. The script prompts to configure an integrated DNS service. Press Enter to select the default no option. 

    Do you want to configure integrated DNS (BIND)? [no]:

  3. The script prompts for several required settings and offers recommended default values in brackets.

    • To accept a default value, press Enter.

    • To provide a custom value, enter the required value. 

      Server host name [server.idm.example.com]:
Please confirm the domain name [idm.example.com]:
Please provide a realm name [IDM.EXAMPLE.COM]:
      Warning

      Plan these names carefully. You will not be able to change them after the installation is complete.

  4. Enter the passwords for the Directory Server superuser (cn=Directory Manager) and for the IdM administration system user account (admin). 

    Directory Manager password:
IPA admin password:

  5. Enter yes to confirm the server configuration. 

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

  6. During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr: 

    ...

Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
  [1/8]: creating certificate server user
  [2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate

    When this happens:

    1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

    2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Be sure to get the full certificate chain for the CA, not just the CA certificate.

    3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example: 

      # ipa-server-install --external-cert-file=/tmp/servercert20170601.pem --external-cert-file=/tmp/cacert.pem
  7. The installation script now configures the server. Wait for the operation to complete.

  8. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 

    ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
    Important

    The server installation is not complete until you add the DNS records to the existing DNS servers.

Additional resources

  • For more information about the DNS resource records you must add to your DNS system, see IdM DNS records for external DNS systems.

  • The ipa-server-install --external-ca command can sometimes fail with the following error: 

    ipa         : CRITICAL failed to configure ca instance Command '/usr/sbin/pkispawn -s CA -f /tmp/pass:quotes[configuration_file]' returned non-zero exit status 1
Configuration of CA failed

    This failure occurs when the *_proxy environmental variables are set. For a solution of the problem, see Troubleshooting: External CA installation fails.

7.3. Non-interactive installation

This procedure installs a server:

  • Without integrated DNS
  • With an external certificate authority (CA) as the root CA
Note

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Prerequisites

  • You have determined the type of the external CA to specify with the --external-ca-type option. See the ipa-server-install(1) man page for details.

  • If you are using a Microsoft Certificate Services certificate authority (MS CS CA) as your external CA: you have determined the certificate profile or template to specify with the --external-ca-profile option. By default, the SubCA template is used.

    For more information about the --external-ca-type and --external-ca-profile options, see Options used when installing an IdM CA with an external CA as the root CA.

Procedure

  1. Run the ipa-server-install utility with the options to supply all the required information. The minimum required options for non-interactive installation of an IdM server with an external CA as the root CA are:

    • --external-ca to specify an external CA is the root CA
    • --realm to provide the Kerberos realm name
    • --ds-password to provide the password for the Directory Manager (DM), the Directory Server super user
    • --admin-password to provide the password for admin, the IdM administrator

    • --unattended to let the installation process select default options for the host name and domain name

      For example: 

      # ipa-server-install --external-ca --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended

    If you are using a Microsoft Certificate Services (MS CS) CA, also use the --external-ca-type option and, optionally, the --external-ca-profile option. For more information, see Options used when installing an IdM CA with an external CA as the root CA.

  2. During the configuration of the Certificate System instance, the utility prints the location of the certificate signing request (CSR): /root/ipa.csr: 

    ...

Configuring certificate server (pki-tomcatd). Estimated time: 3 minutes
  [1/11]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /usr/sbin/ipa-server-install as:
/usr/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
The ipa-server-install command was successful

    When this happens:

    1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

    2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Be sure to get the full certificate chain for the CA, not just the CA certificate.

    3. Run ipa-server-install again, this time specifying the locations and names of the newly-issued CA certificate and the CA chain files. For example: 

      # ipa-server-install --external-cert-file=/tmp/servercert20170601.pem --external-cert-file=/tmp/cacert.pem --realm IDM.EXAMPLE.COM --ds-password DM_password --admin-password admin_password --unattended
  3. The installation script now configures the server. Wait for the operation to complete.

  4. The installation script produces a file with DNS resource records: the /tmp/ipa.system.records.UFRPto.db file in the example output below. Add these records to the existing external DNS servers. The process of updating the DNS records varies depending on the particular DNS solution. 

    ...
Restarting the KDC
Please add records in this file to your DNS system: /tmp/ipa.system.records.UFRBto.db
Restarting the web server
...
Important

The server installation is not complete until you add the DNS records to the existing DNS servers.

Additional resources

7.4. IdM DNS records for external DNS systems

After installing an IdM server without integrated DNS, you must add LDAP and Kerberos DNS resource records for the IdM server to your external DNS system.

The ipa-server-install installation script generates a file containing the list of DNS resource records with a file name in the format /tmp/ipa.system.records.<random_characters>.db and prints instructions to add those records: 

Please add records in this file to your DNS system: /tmp/ipa.system.records.6zdjqxh3.db

This is an example of the contents of the file: 

_kerberos-master._tcp.example.com. 86400 IN SRV 0 100 88 server.example.com.
_kerberos-master._udp.example.com. 86400 IN SRV 0 100 88 server.example.com.
_kerberos._tcp.example.com. 86400 IN SRV 0 100 88 server.example.com.
_kerberos._udp.example.com. 86400 IN SRV 0 100 88 server.example.com.
_kerberos.example.com. 86400 IN TXT "EXAMPLE.COM"
_kpasswd._tcp.example.com. 86400 IN SRV 0 100 464 server.example.com.
_kpasswd._udp.example.com. 86400 IN SRV 0 100 464 server.example.com.
_ldap._tcp.example.com. 86400 IN SRV 0 100 389 server.example.com.
Note

After adding the LDAP and Kerberos DNS resource records for the IdM server to your DNS system, ensure that the DNS management tools have not added PTR records for ipa-ca. The presence of PTR records for ipa-ca in your DNS could cause subsequent IdM replica installations to fail.