23.5. PKINIT Smart-card Authentication in Identity Management

Identity Management users can authenticate with a smart card to a desktop client system joined to Identity Management and get a Kerberos ticket-granting ticket (TGT) automatically. The users can use the ticket for further single sign-on (SSO) authentication from the client.

23.5.1. Preparing the Identity Management Client for PKINIT Authentication

As the Identity Management administrator, perform these steps on the client where you want the users to authenticate:
  1. On the server, create a shell script to configure the client.
    1. Use the ipa-advise config-client-for-smart-card-auth command, and save its output to a file:
      # ipa-advise config-client-for-smart-card-auth > client_smart_card_script.sh
    2. Open the script file, and review its contents.
    3. Add execute permissions to the file using the chmod utility:
      # chmod +x client_smart_card_script.sh
  2. Copy the script to the client, and run it. Add the path to the PEM file with the certificate authority (CA) that signed the smart card certificate:
    # ./client_smart_card_script.sh CA_cert.pem
  3. Make sure the krb5-pkinit package is installed.
Additionally, if an external certificate authority (CA) signed the certificate on the smart card, add the smart card CA as a trusted CA:
  1. On the Identity Management server, install the CA certificate:
    # ipa-cacert-manage -n "SmartCard CA" -t CT,C,C install ca.pem
    # ipa-certupdate
    Repeat ipa-certupdate also on all replicas and clients.
  2. Restart the HTTP server:
    # systemctl restart httpd
    Repeat systemctl restart httpd also on all replicas.

Note

SSSD enables administrators to tune the certificate verification process with the certificate_verification parameter, for example if the Online Certificate Status Protocol (OCSP) servers defined in the certificate are not reachable from the client. For more information, see the sssd.conf(5) man page.

23.5.2. As an Identity Management User: Authenticate Using PKINIT on an Identity Management Client

Authenticate using the kinit utility on an Identity Management client:
$ kinit -X X509_user_identity='PKCS11:opensc-pkcs11.so' idm_user
The -X option specifies the opensc-pkcs11.so module as the pre-authentication attribute. For details, see the kinit(1) man page.

23.5.3. As an Active Directory User: Authenticate Using PKINIT on an Identity Management Client

Prerequisites

As the administrator, configure the environment to support PKINIT authentication for Active Directory users:
  • Configure the Active Directory server to trust the certificate authority (CA) that issued the smart card certificate. Import the CA in the NTAuth store (see Microsoft support), and add the CA as a trusted CA. See Active Directory documentation for details.
  • Configure the Kerberos client to trust the CA that issued the smart card certificate:
    1. On the Identity Management client, open the /etc/krb5.conf file.
    2. Add the following lines to the file:
      [libdefaults]
      [... file truncated ...]
       pkinit_eku_checking = kpServerAuth
       pkinit_kdc_hostname = adserver.ad.domain.com
  • If the user certificates do not contain a certificate revocation list (CRL) distribution point extension, configure Active Directory to ignore revocation errors:
    1. Save the following REG-formatted content in a plain text file, and double-click the file to import it to the Windows Registry:
      Windows Registry Editor Version 5.00
      
      [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Kdc]
      "UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors"=dword:00000001
      
      [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\LSA\Kerberos\Parameters]
      "UseCachedCRLOnlyAndIgnoreRevocationUnknownErrors"=dword:00000001
      Alternatively, set the values manually using the regedit.exe application.
    2. Reboot the Windows system to apply the changes.

Procedure

Authenticate using the kinit utility on an Identity Management client. Specify the Active Directory user with the user name and domain name:
$ kinit -X X509_user_identity='PKCS11:opensc-pkcs11.so' ad_user@AD.DOMAIN.COM
The -X option specifies the opensc-pkcs11.so module as the pre-authentication attribute. For details, see the kinit(1) man page.