Chapter 7. Configuring Identity Management for smart card authentication

1. Obtain files with the CA certificates in the PEM format.
2. Run the built-in ipa-advise script.
3. Reload the system configuration.

Procedure

1. Create a directory in which you will do the configuration:

   [root@server]# mkdir ~/SmartCard/

2. Navigate to the directory:

   [root@server]# cd ~/SmartCard/

3. Obtain the relevant CA certificates stored in files in PEM format. If your CA certificate is stored in a file of a different format, such as DER, convert it to PEM format. The IdM Certificate Authority certificate is in PEM format and is located in the /etc/ipa/ca.crt file.

   Convert a DER file to a PEM file:

   # openssl x509 -in <filename>.der -inform DER -out <filename>.pem -outform PEM

4. For convenience, copy the certificates to the directory in which you want to do the configuration:

   [root@server SmartCard]# cp /tmp/rootca.pem ~/SmartCard/
   [root@server SmartCard]# cp /tmp/subca.pem ~/SmartCard/
   [root@server SmartCard]# cp /tmp/issuingca.pem ~/SmartCard/

5. Optional: If you use certificates of external certificate authorities, use the openssl x509 utility to view the contents of the files in the PEM format to check that the Issuer and Subject values are correct:

   [root@server SmartCard]# openssl x509 -noout -text -in rootca.pem | more

6. Generate a configuration script with the in-built ipa-advise utility, using the administrator’s privileges:

   [root@server SmartCard]# kinit admin
   [root@server SmartCard]# ipa-advise config-server-for-smart-card-auth > config-server-for-smart-card-auth.sh

   The config-server-for-smart-card-auth.sh script performs the following actions:

   • It configures the IdM Apache HTTP Server.
   • It enables Public Key Cryptography for Initial Authentication in Kerberos (PKINIT) on the Key Distribution Center (KDC).
   • It configures the IdM Web UI to accept smart card authorization requests.

7. Execute the script, adding the PEM files containing the root CA and sub CA certificates as arguments:

   [root@server SmartCard]# chmod +x config-server-for-smart-card-auth.sh
   [root@server SmartCard]# ./config-server-for-smart-card-auth.sh rootca.pem subca.pem issuingca.pem
   Ticket cache:KEYRING:persistent:0:0
   Default principal: admin@IDM.EXAMPLE.COM
   [...]
   Systemwide CA database updated.
   The ipa-certupdate command was successful

   Note

   Ensure that you add the root CA’s certificate as an argument before any sub CA certificates and that the CA or sub CA certificates have not expired.

8. Optional: If the certificate authority that issued the user certificate does not provide any Online Certificate Status Protocol (OCSP) responder, you may need to disable OCSP check for authentication to the IdM Web UI:

   1. Set the SSLOCSPEnable parameter to off in the /etc/httpd/conf.d/ssl.conf file:

      SSLOCSPEnable off

   2. Restart the Apache daemon (httpd) for the changes to take effect immediately:

      [root@server SmartCard]# systemctl restart httpd

   Warning

   Do not disable the OCSP check if you only use user certificates issued by the IdM CA. OCSP responders are part of IdM.

   For instructions on how to keep the OCSP check enabled, and yet prevent a user certificate from being rejected by the IdM server if it does not contain the information about the location at which the CA that issued the user certificate listens for OCSP service requests, see the SSLOCSPDefaultResponder directive in Apache mod_ssl configuration options.

Procedure

1. If your CA certificates are stored in files of a different format, such as DER, convert them to PEM format:

   # openssl x509 -in <filename>.der -inform DER -out <filename>.pem -outform PEM

   The IdM Certificate Authority certificate is in PEM format and is located in the /etc/ipa/ca.crt file.

2. Optional: Use the openssl x509 utility to view the contents of the files in the PEM format to check that the Issuer and Subject values are correct:

   # openssl x509 -noout -text -in root-ca.pem | more

3. Navigate to your ~/MyPlaybooks/ directory:

   $ cd ~/MyPlaybooks/

4. Create a subdirectory dedicated to the CA certificates:

   $ mkdir SmartCard/

5. For convenience, copy all the required certificates to the ~/MyPlaybooks/SmartCard/ directory:

   # cp /tmp/root-ca.pem ~/MyPlaybooks/SmartCard/
   # cp /tmp/intermediate-ca.pem ~/MyPlaybooks/SmartCard/
   # cp /etc/ipa/ca.crt ~/MyPlaybooks/SmartCard/ipa-ca.crt

6. In your Ansible inventory file, specify the following:

   • The IdM servers that you want to configure for smart card authentication.
   • The IdM administrator password.

   • The paths to the certificates of the CAs in the following order:

     • The root CA certificate file
     • The intermediate CA certificates files
     • The IdM CA certificate file

   The file can look as follows:

   [ipaserver]
   ipaserver.idm.example.com
   
   [ipareplicas]
   ipareplica1.idm.example.com
   ipareplica2.idm.example.com
   
   [ipacluster:children]
   ipaserver
   ipareplicas
   
   [ipacluster:vars]
   ipaadmin_password= "{{ ipaadmin_password }}"
   ipasmartcard_server_ca_certs=/home/<user_name>/MyPlaybooks/SmartCard/root-ca.pem,/home/<user_name>/MyPlaybooks/SmartCard/intermediate-ca.pem,/home/<user_name>/MyPlaybooks/SmartCard/ipa-ca.crt

7. Create an install-smartcard-server.yml playbook with the following content:

   ---
   - name: Playbook to set up smart card authentication for an IdM server
     hosts: ipaserver
     become: true
   
     roles:
     - role: ipasmartcard_server
       state: present

8. Save the file.

9. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file:

   $ ansible-playbook --vault-password-file=password_file -v -i inventory install-smartcard-server.yml

   The ipasmartcard_server Ansible role performs the following actions:

   • It configures the IdM Apache HTTP Server.
   • It enables Public Key Cryptography for Initial Authentication in Kerberos (PKINIT) on the Key Distribution Center (KDC).
   • It configures the IdM Web UI to accept smart card authorization requests.

10. Optional: If the certificate authority that issued the user certificate does not provide any Online Certificate Status Protocol (OCSP) responder, you may need to disable OCSP check for authentication to the IdM Web UI:

    1. Connect to the IdM server as root:

       ssh root@ipaserver.idm.example.com

    2. Set the SSLOCSPEnable parameter to off in the /etc/httpd/conf.d/ssl.conf file:

       SSLOCSPEnable off

    3. Restart the Apache daemon (httpd) for the changes to take effect immediately:

       # systemctl restart httpd

    Warning

    Do not disable the OCSP check if you only use user certificates issued by the IdM CA. OCSP responders are part of IdM.

    For instructions on how to keep the OCSP check enabled, and yet prevent a user certificate from being rejected by the IdM server if it does not contain the information about the location at which the CA that issued the user certificate listens for OCSP service requests, see the SSLOCSPDefaultResponder directive in Apache mod_ssl configuration options.

Procedure

1. On an IdM server, generate a configuration script with ipa-advise using the administrator’s privileges:

   [root@server SmartCard]# kinit admin
   [root@server SmartCard]# ipa-advise config-client-for-smart-card-auth > config-client-for-smart-card-auth.sh

   The config-client-for-smart-card-auth.sh script performs the following actions:

   • It configures the smart card daemon.
   • It sets the system-wide truststore.
   • It configures the System Security Services Daemon (SSSD) to allow users to authenticate with either their user name and password or with their smart card. For more details on SSSD profile options for smart card authentication, see Smart card authentication options in RHEL.

2. From the IdM server, copy the script to a directory of your choice on the IdM client machine:

   [root@server SmartCard]# scp config-client-for-smart-card-auth.sh root@client.idm.example.com:/root/SmartCard/
   Password:
   config-client-for-smart-card-auth.sh        100%   2419       3.5MB/s   00:00

3. From the IdM server, copy the CA certificate files in PEM format for convenience to the same directory on the IdM client machine as used in the previous step:

   [root@server SmartCard]# scp {rootca.pem,subca.pem,issuingca.pem} root@client.idm.example.com:/root/SmartCard/
   Password:
   rootca.pem                          100%   1237     9.6KB/s   00:00
   subca.pem                           100%   2514    19.6KB/s   00:00
   issuingca.pem                       100%   2514    19.6KB/s   00:00

4. On the client machine, execute the script, adding the PEM files containing the CA certificates as arguments:

   [root@client SmartCard]# kinit admin
   [root@client SmartCard]# chmod +x config-client-for-smart-card-auth.sh
   [root@client SmartCard]# ./config-client-for-smart-card-auth.sh rootca.pem subca.pem issuingca.pem
   Ticket cache:KEYRING:persistent:0:0
   Default principal: admin@IDM.EXAMPLE.COM
   [...]
   Systemwide CA database updated.
   The ipa-certupdate command was successful

   Note

   Ensure that you add the root CA’s certificate as an argument before any sub CA certificates and that the CA or sub CA certificates have not expired.

Procedure

1. If your CA certificates are stored in files of a different format, such as DER, convert them to PEM format:

   # openssl x509 -in <filename>.der -inform DER -out <filename>.pem -outform PEM

   The IdM CA certificate is in PEM format and is located in the /etc/ipa/ca.crt file.

2. Optional: Use the openssl x509 utility to view the contents of the files in the PEM format to check that the Issuer and Subject values are correct:

   # openssl x509 -noout -text -in root-ca.pem | more

3. On your Ansible control node, navigate to your ~/MyPlaybooks/ directory:

   $ cd ~/MyPlaybooks/

4. Create a subdirectory dedicated to the CA certificates:

   $ mkdir SmartCard/

5. For convenience, copy all the required certificates to the ~/MyPlaybooks/SmartCard/ directory, for example:

   # cp /tmp/root-ca.pem ~/MyPlaybooks/SmartCard/
   # cp /tmp/intermediate-ca.pem ~/MyPlaybooks/SmartCard/
   # cp /etc/ipa/ca.crt ~/MyPlaybooks/SmartCard/ipa-ca.crt

6. In your Ansible inventory file, specify the following:

   • The IdM clients that you want to configure for smart card authentication.
   • The IdM administrator password.

   • The paths to the certificates of the CAs in the following order:

     • The root CA certificate file
     • The intermediate CA certificates files
     • The IdM CA certificate file

   The file can look as follows:

   [ipaclients]
   ipaclient1.example.com
   ipaclient2.example.com
   
   [ipaclients:vars]
   ipaadmin_password=SomeADMINpassword
   ipasmartcard_client_ca_certs=/home/<user_name>/MyPlaybooks/SmartCard/root-ca.pem,/home/<user_name>/MyPlaybooks/SmartCard/intermediate-ca.pem,/home/<user_name>/MyPlaybooks/SmartCard/ipa-ca.crt

7. Create an install-smartcard-clients.yml playbook with the following content:

   ---
   - name: Playbook to set up smart card authentication for an IdM client
     hosts: ipaclients
     become: true
   
     roles:
     - role: ipasmartcard_client
       state: present

8. Save the file.

9. Run the Ansible playbook. Specify the playbook and inventory files:

   $ ansible-playbook --vault-password-file=password_file -v -i inventory install-smartcard-clients.yml

   The ipasmartcard_client Ansible role performs the following actions:

   • It configures the smart card daemon.
   • It sets the system-wide truststore.
   • It configures the System Security Services Daemon (SSSD) to allow users to authenticate with either their user name and password or their smart card. For more details on SSSD profile options for smart card authentication, see Smart card authentication options in RHEL.

Procedure

1. Log into the IdM Web UI as an administrator if you want to add a certificate to another user. For adding a certificate to your own profile, you do not need the administrator’s credentials.
2. Navigate to Users Active users sc_user.
3. Find the Certificate option and click Add.

4. In the command-line interface, display the certificate in the PEM format using the cat utility or a text editor:

   [user@client SmartCard]$ cat testuser.crt

5. Copy and paste the certificate from the CLI into the window that has opened in the Web UI.

6. Click Add.

   Figure 7.1. Adding a new certificate in the IdM Web UI

   

Procedure

1. Log into the IdM CLI as an administrator if you want to add a certificate to another user:

   [user@client SmartCard]$ kinit admin

   For adding a certificate to your own profile, you do not need the administrator’s credentials:

   [user@client SmartCard]$ kinit sc_user

2. Create an environment variable containing the certificate with the header and footer removed and concatenated into a single line, which is the format expected by the ipa user-add-cert command:

   [user@client SmartCard]$ export CERT=`openssl x509 -outform der -in testuser.crt | base64 -w0 -`

   Note that certificate in the testuser.crt file must be in the PEM format.

3. Add the certificate to the profile of sc_user using the ipa user-add-cert command:

   [user@client SmartCard]$ ipa user-add-cert sc_user --certificate=$CERT

Procedure

1. Install the opensc and gnutls-utils packages:

   # yum -y install opensc gnutls-utils

2. Start the pcscd service.

   # systemctl start pcscd

Procedure

1. Erase your smart card and authenticate yourself with your PIN:

   $ pkcs15-init --erase-card --use-default-transport-keys
   Using reader with a card: Reader name
   PIN [Security Officer PIN] required.
   Please enter PIN [Security Officer PIN]:

   The card has been erased.

2. Initialize your smart card, set your user PIN and PUK, and your Security Officer PIN and PUK:

   $ pkcs15-init --create-pkcs15 --use-default-transport-keys \ --pin 963214 --puk 321478 --so-pin 65498714 --so-puk 784123
   Using reader with a card: Reader name

   The pcks15-init tool creates a new slot on the smart card.

3. Set a label and the authentication ID for the slot:

   $ pkcs15-init --store-pin --label testuser \ --auth-id 01 --so-pin 65498714 --pin 963214 --puk 321478
   Using reader with a card: Reader name

   The label is set to a human-readable value, in this case, testuser. The auth-id must be two hexadecimal values, in this case it is set to 01.

4. Store and label the private key in the new slot on the smart card:

   $ pkcs15-init --store-private-key testuser.key --label testuser_key \ --auth-id 01 --id 01 --pin 963214
   Using reader with a card: Reader name

   Note

   The value you specify for --id must be the same when storing your private key and storing your certificate in the next step. Specifying your own value for --id is recommended as otherwise a more complicated value is calculated by the tool.

5. Store and label the certificate in the new slot on the smart card:

   $ pkcs15-init --store-certificate testuser.crt --label testuser_crt \ --auth-id 01 --id 01 --format pem --pin 963214
   Using reader with a card: Reader name

6. Optional: Store and label the public key in the new slot on the smart card:

   $ pkcs15-init --store-public-key testuserpublic.key --label testuserpublic_key --auth-id 01 --id 01 --pin 963214
   Using reader with a card: Reader name

   Note

   If the public key corresponds to a private key or certificate, specify the same ID as the ID of the private key or certificate.

7. Optional: Certain smart cards require you to finalize the card by locking the settings:

   $ pkcs15-init -F

   At this stage, your smart card includes the certificate, private key, and public key in the newly created slot. You have also created your user PIN and PUK and the Security Officer PIN and PUK.

Procedure

1. Open the IdM Web UI in the browser.

2. Click Log In Using Certificate.

   

3. If the Password Required dialog box opens, add the PIN to unlock the smart card and click the OK button.

   The User Identification Request dialog box opens.

   If the smart card contains more than one certificate, select the certificate you want to use for authentication in the drop down list below Choose a certificate to present as identification.

4. Click the OK button.

Procedure

1. Insert the smart card in the reader.
2. Enter the smart card PIN.
3. Click Sign In.