Chapter 32. Configuring authentication with a certificate stored on the desktop of an IdM client

By configuring Identity Management (IdM), IdM system administrators can enable users to authenticate to the IdM web UI and command-line interface (CLI) using a certificate that a Certificate Authority (CA) has issued to the users.

The web browser can run on a system that is not part of the IdM domain.

This user story provides instructions on how to effectively configure and test logging into Identity Management web UI and CLI with a certificate stored on the desktop of an IdM client. In following this user story,

Note

Only Identity Management users can log into the web UI using a certificate. Active Directory users can log in with their user name and password.

32.1. Configuring the Identity Management Server for Certificate Authentication in the Web UI

As an Identity Management (IdM) administrator, you can allow users to use certificates to authenticate to your IdM environment.

Procedure

As the Identity Management administrator:

  1. On an Identity Management server, obtain administrator privileges and create a shell script to configure the server.

    1. Run the ipa-advise config-server-for-smart-card-auth command, and save its output to a file, for example server_certificate_script.sh:

      # kinit admin
      # ipa-advise config-server-for-smart-card-auth > server_certificate_script.sh
    2. Add execute permissions to the file using the chmod utility:

      # chmod +x server_certificate_script.sh
  2. On all the servers in the Identity Management domain, run the server_certificate_script.sh script

    1. with the path of the IdM Certificate Authority certificate, /etc/ipa/ca.crt, as input if the IdM CA is the only certificate authority that has issued the certificates of the users you want to enable certificate authentication for:

      # ./server_certificate_script.sh /etc/ipa/ca.crt
    2. with the paths leading to the relevant CA certificates as input if different external CAs signed the certificates of the users who you want to enable certificate authentication for:

      # ./server_certificate_script.sh /tmp/ca1.pem /tmp/ca2.pem
Note

Do not forget to run the script on each new replica that you add to the system in the future if you want to have certificate authentication for users enabled in the whole topology.

32.2. Requesting a new user certificate and exporting it to the client

As an Identity Management (IdM) administrator, you can create certificates for users in your IdM environment and export them to the IdM clients on which you want to enable certificate authentication for users.

Note

You can skip this section if the user you want to authenticate using a certificate already has a certificate.

Procedure

  1. Optionally, create a new directory, for example ~/certdb/, and make it a temporary certificate database. When asked, create an NSS Certificate DB password to encrypt the keys to the certificate to be generated in a subsequent step:

    # mkdir ~/certdb/
    # certutil -N -d ~/certdb/
    Enter a password which will be used to encrypt your keys.
    The password should be at least 8 characters long,
    and should contain at least one non-alphabetic character.
    
    Enter new password:
    Re-enter password:
  2. Create the certificate signing request (CSR) and redirect the output to a file. For example, to create a CSR with the name certificate_request.csr for a 4096 bit certificate for the idm_user user in the IDM.EXAMPLE.COM realm, setting the nickname of the certificate private keys to idm_user for easy findability, and setting the subject to CN=idm_user,O=IDM.EXAMPLE.COM:

    # certutil -R -d ~/certdb/ -a -g 4096 -n idm_user -s "CN=idm_user,O=IDM.EXAMPLE.COM" > certificate_request.csr
  3. When prompted, enter the same password that you entered when using certutil to create the temporary database. Then continue typing randlomly until told to stop:

    Enter Password or Pin for "NSS Certificate DB":
    
    A random seed must be generated that will be used in the
    creation of your key.  One of the easiest ways to create a
    random seed is to use the timing of keystrokes on a keyboard.
    
    To begin, type keys on the keyboard until this progress meter
    is full.  DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!
    
    
    Continue typing until the progress meter is full:
  4. Submit the certificate request file to the server. Specify the Kerberos principal to associate with the newly-issued certificate, the output file to store the certificate, and optionally the certificate profile. For example, to obtain a certificate of the IECUserRoles profile, a profile with added user roles extension, for the idm_user@IDM.EXAMPLE.COM principal, and save it in the ~/idm_user.pem file:

    # ipa cert-request certificate_request.csr --principal=idm_user@IDM.EXAMPLE.COM --profile-id=IECUserRoles --certificate-out=~/idm_user.pem
  5. Add the certificate to the NSS database. Use the -n option to set the same nickname that you used when creating the CSR previously so that the certificate matches the private key in the NSS database. The -t option sets the trust level. For details, see the certutil(1) man page. The -i option specifies the input certificate file. For example, to add to the NSS database a certificate with the idm_user nickname that is stored in the ~/idm_user.pem file in the ~/certdb/ database:

    # certutil -A -d ~/certdb/ -n idm_user -t "P,," -i ~/idm_user.pem
  6. Verify that the key in the NSS database does not show (orphan) as its nickname. For example, to verify that the certificate stored in the ~/certdb/ database is not orphaned:

    # certutil -K -d ~/certdb/
    < 0> rsa      5ad14d41463b87a095b1896cf0068ccc467df395   NSS Certificate DB:idm_user
  7. Use the pk12util command to export the certificate from the NSS database to the PKCS12 format. For example, to export the certificate with the idm_user nickname from the /root/certdb NSS database into the ~/idm_user.p12 file:

    # pk12util -d ~/certdb -o ~/idm_user.p12 -n idm_user
    Enter Password or Pin for "NSS Certificate DB":
    Enter password for PKCS12 file:
    Re-enter password:
    pk12util: PKCS12 EXPORT SUCCESSFUL
  8. Transfer the certificate to the host on which you want the certificate authentication for idm_user to be enabled:

    # scp ~/idm_user.p12 idm_user@client.idm.example.com:/home/idm_user/
  9. On the host to which the certificate has been transferred, make the directory in which the .pkcs12 file is stored inaccessible to the 'other' group for security reasons:

    # chmod o-rwx /home/idm_user/
  10. For security reasons, remove the temporary NSS database and the .pkcs12 file from the server:

    # rm ~/certdb/
    # rm ~/idm_user.p12

32.3. Making sure the certificate and user are linked together

Note

You can skip this section if the user’s certificate has been issued by the IdM CA.

For certificate authentication to work, you need to make sure that the certificate is linked to the user that will use it to authenticate to Identity Management (IdM).

32.4. Configuring a browser to enable certificate authentication

To be able to authenticate with a certificate when using the WebUI to log into Identity Management (IdM), you need to import the user and the relevant certificate authority (CA) certificates into the Mozilla Firefox or Google Chrome browser. The host itself on which the browser is running does not have to be part of the IdM domain.

IdM supports the following browsers for connecting to the WebUI:

  • Mozilla Firefox 38 and later
  • Google Chrome 46 and later

The following procedure shows how to configure the Mozilla Firefox 57.0.1 browser.

Prerequisites

  • You have the user certificate that you want to import to the browser at your disposal in the PKCS#12 format.

Procedure

  1. Open Firefox, then navigate to PreferencesPrivacy & Security.

    Figure 32.1. Privacy and Security section in Preferences

    privacy and security
  2. Click View Certificates.

    Figure 32.2. View Certificates in Privacy and Security

    view certificates
  3. In the Your Certificates tab, click Import. Locate and open the certificate of the user in the PKCS12 format, then click OK and OK.
  4. Make sure that the Identity Management Certificate Authority is recognized by Firefox as a trusted authority:

    1. Save the IdM CA certificate locally:

      • Navigate to the IdM web UI by writing the name of your IdM server in the Firefox address bar. Click Advanced on the Insecure Connection warning page.

        Figure 32.3. Insecure Connection

        connection not secure idm
      • Add Exception. Click View.

        Figure 32.4. View the Details of a Certificate

        view ca certificate idm
      • In the Details tab, highlight the Certificate Authority fields.

        Figure 32.5. Exporting the CA Certificate

        exporting ca cert idm
      • Click Export. Save the CA certificate, for example as the CertificateAuthority.crt file, then click Close, and Cancel.
    2. Import the IdM CA certificate to Firefox as a trusted certificate authority certificate:

      • Open Firefox, navigate to Preferences and click Privacy & Security.

        Figure 32.6. Privacy and Security section in Preferences

        privacy and security
      • Click View Certificates.

        Figure 32.7. View Certificates in Privacy and Security

        view certificates
      • In the Authorities tab, click Import. Locate and open the CA certificate that you saved in the previous step in the CertificateAuthority.crt file. Trust the certificate to identify websites, then click OK and OK.
  5. Continue to Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User.

32.5. Authenticating to the Identity Management Web UI with a Certificate as an Identity Management User

This procedure describes authenticating as a user to the Identity Management (IdM) web UI using a certificate stored on the desktop of an Identity Management client.

Procedure

  1. In the browser, navigate to the Identity Management web UI at, for example, https://server.idm.example.com/ipa/ui.
  2. Click Login Using Certificate.

    .Login Using Certificate in the Identity Management web UI

    smart card login
  3. The user’s certificate should already be selected. Uncheck Remember this decision, then click OK.

You are now authenticated as the user who corresponds to the certificate.

Additional resources

  • For information about authenticating to the IdM web UI using a certificate stored on a smart card, see

32.6. Configuring an IdM client to enable authenticating to the CLI using a certificate

To make certificate authentication work for an IdM user in the Command Line Interface (CLI) of your IdM client, import the IdM user’s certificate and the private key to the IdM client. For details on creating and transferring the user certificate, see Section 32.2, “Requesting a new user certificate and exporting it to the client”.

Procedure

  • Log into the IdM client and have the .p12 file containing the user’s certificate and the private key ready. To obtain and cache the Kerberos ticket granting ticket (TGT), run the kinit command with the user’s principal, using the -X option with the X509_username:/path/to/file.p12 attribute to specify where to find the user’s X509 identity information. For example, to obtain the TGT for idm_user using the user’s identity information stored in the ~/idm_user.p12 file:

    $ kinit -X X509_idm_user='PKCS12:~/idm_user.p12' idm_user
    Note

    The command also supports the .pem file format: kinit -X X509_username='FILE:/path/to/cert.pem,/path/to/key' user_principal