Chapter 23. Smart-card Authentication in Identity Management

Authentication based on smart cards is an alternative to passwords. User credentials are stored on the smart card, and special software and hardware is used to access them. The user places the smart card into a reader and supplies the PIN code for the smart card.

This chapter describes how an administrator can configure smart card-based authentication in Identity Management and how users can use smart cards to authenticate to Identity Management.

23.1. Managing Smart Card Links in the Identity Management Server

Before a user can use a smart card for authentication in the Identity Management domain, the administrator must link the certificate from the user's smart card with the corresponding user account in Identity Management. Linking a smart card certificate to a user account enables the user to authenticate with the smart card as the required role. This section describes how to manage links between a user smart card and one or more user accounts in the Identity Management server.

Before you can link the smart card to a user account, the smart card certificate must be available:

If you need to extract the certificate from the smart card, see Section 23.1.1, “Exporting a Certificate From a Smart Card”.

For details on creating the links between a certificate and a user account, see:

Section 23.1.2, “Linking User Accounts to Smart Card Certificates”

If you need to find a user account that corresponds to a certain smart card certificate, see:

Section 23.1.3, “Finding Users That Match a Specified Certificate”

23.1.1. Exporting a Certificate From a Smart Card

To export the certificate:

Place the smart card into the reader.

Use the following command to list the certificates on the smart card. In the output, locate the certificate to use for authentication, and note its nickname:

$ certutil -L -d /etc/pki/nssdb/ -h all
Certificate Nickname         Trust Attributes
                             SSL,S/MIME,JAR/XPI

my_certificate               CT,C,C

Extract the certificate to a file using the certificate nickname. For example, to extract the certificate in the Base64 format to a file named user.crt:
```
$ certutil -L -d /etc/pki/nssdb/ -n 'my_certificate' -r | base64 -w 0 > user.crt
```
The base64 utility is part of the coreutils package.

23.1.2. Linking User Accounts to Smart Card Certificates

As a security officer, you can manage links between a user's smart card and one or more user role accounts in the Identity Management Server. This enables the user to authenticate as a required role.

Create the link using one of the following options:

Using the full certificate blob:
- For Identity Management users, see Section 23.1.2.1, “Creating a Link Between a Certificate and a User Account”. You can also remove such link using Section 23.1.2.2, “Removing a Link Between a Certificate and a User Account”.
- For Active Directory users, see Section 23.1.2.3, “Linking an Active Directory User Account and a Smart Card”.
Using certificate mapping: Section 23.1.2.4, “Configuring Identity Mapping”

23.1.2.1. Creating a Link Between a Certificate and a User Account

To link an Identity Management user account and a certificate, store the certificate in the user account.

Perform these steps on any Identity Management system.

Command Line: Creating a Link Between a Certificate and a User Account

Log in as the Identity Management administrator:
```
$ kinit admin
```
Add the smart card certificate to the user account using the ipa user-add-cert command. For example:
```
$ cat cert.pem | tail -n +2 | head -n -1 | tr -d '\r\n' | ipa user-add-cert idm_user
```

Web UI: Creating a Link Between a Certificate and a User Account

Select Identity → Users, and click on the required user account.
Click Add next to the Certificates entry, and enter the certificate.
Click Save at the top of the user account page.

Additional Resources

For details on adding and removing certificates issued by an external certificate authority (CA), see Section 24.2, “Managing Certificates Issued by External CAs”.

23.1.2.2. Removing a Link Between a Certificate and a User Account

To remove a link between an Identity Management user account and a certificate, remove the certificate from the user account.

Perform these steps on any Identity Management system.

Command Line: Creating a Link Between a Certificate and a User Account

Find the required user account:

$ ipa user-show idm_user
User login: idm_user
  First name: first_name
  Last name: last_name
  ...
  Certificate: MIIC3...

Remove the certificate from the account:

$ ipa user-remove-cert idm_user --certificate MIIC3...

Web UI: Removing a Link Between a Certificate and a User Account

Select Identity → Users, and click on the required user account.
Click Actions next to the certificate to delete, and select Delete.

Additional Resources

For details on adding and removing certificates issued by an external certificate authority (CA), see Section 24.2, “Managing Certificates Issued by External CAs”.

23.1.2.3. Linking an Active Directory User Account and a Smart Card

If it is possible to modify the user entry in Active Directory, store the user certificate in the user entry in Active Directory. See Active Directory documentation for details. This ensures that Identity Management can read the smart card certificate from the user object in Active Directory.

If it is not possible to modify the user entry in Active Directory, store the user certificate in an ID view. You can use the Default Trust View in Identity Management to store the certificate, or you can create a new ID view. The information in the ID view overrides the information in the user object in Active Directory, which also enables you to set up different smart card links for systems enrolled in Active Directory and systems enrolled in Identity Management.

Perform these steps on an Identity Management server.

Command Line: Linking an Active Directory User Account and a Smart Card

Create an environment variable (CERT) for the user certificate:

$ CERT=`cat cert.pem | tail -n +2 | head -n -1 | tr -d '\r\n'`

Add the user certificate to the ID view by creating a new ID override. In this procedure, we are using the Default Trust View:
```
$ ipa idoverrideuser-add 'Default Trust View' ad_user@ad.example.com --certificate $CERT
```

Web UI: Linking an Active Directory User Account and a Smart Card

Select Identity → ID Views, and click on the required ID view.
Add the user certificate to the ID view by creating a new ID override. Click Add, and fill out the required information in the Add User ID override form.

Additional Resources

For details on managing ID views, see Chapter 18, ID Views.
For details on the Default Trust View, see Using ID Views in Active Directory Environments.

23.1.2.4. Configuring Identity Mapping

As a security officer, you can manage links between a user's smart card and one or more user role accounts using identity matching and mapping rules. This enables you to allow users to access to Identity Management even if it is not possible to store the smart card certificate in the user entry or in an ID override, for example if you do not have physical access to the smart card.

For a basic overview of identity mapping, see:

Section 23.1.2.4.1, “Identity Mapping in Identity Management”

For the procedures to configure identity mapping, see:

For various examples, see:

23.1.2.4.1. Identity Mapping in Identity Management

Identity mapping is configured by creating identity mapping rules. Identity Management supports the following components in identity mapping rules. All components are optional:

Mapping rule

A mapping rule associates (or maps) a certificate with one or more user accounts. The rule defines an LDAP search filter that associates a certificate with the intended user account.

Certificates issued by different certificate authorities (CAs) might have different properties and might be used in different domains. Therefore, Identity Management does not apply mapping rules unconditionally, but only to the appropriate certificates. The appropriate certificates are defined using matching rules.

Matching rule

A matching rule selects a certificate or CA to which you want to apply the mapping rule.

Domain list

The domain list specifies the DNS domain names in which you want Identity Management to search the users when processing identity mapping rules.

Note

If you do not specify any domains, Identity Management searches the users only in the local domain to which the client belongs.

Priority

When multiple rules are applicable to a certificate, the rule with the highest priority takes precedence. All other rules are ignored.

The lower the numerical value, the higher the priority of the identity mapping rule. For example, a rule with a priority 1 has higher priority than a rule with a priority 2.
If a rule has no priority value defined, it has the lowest priority.

23.1.2.4.2. Creating a Certificate Identity Mapping Rule

Creating a certificate identity mapping rule ensures that Identity Management can correctly map a smart card certificate to a user account.

Command Line: Creating a Certificate Identity Mapping Rule

Perform these steps on the server:

Log in as the administrator:
```
$ kinit admin
```
Create the rule by using the ipa certmaprule-add command. To specify the components for the identity mapping rule, use these options:
- --maprule defines the mapping rule
- --matchrule defines the matching rule
- --domain defines the domain in which you want to search the user entry
- --priority defines the priority of the identity mapping rule
For example, to create a simple identity mapping rule that consists only of a mapping rule and a matching rule:
```
$ ipa certmaprule-add rule_name --matchrule '<ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG' --maprule '(ipacertmapdata=X509:{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'
-------------------------------------------------------
Added Certificate Identity Mapping Rule "rule_name"
-------------------------------------------------------
 Rule name: rule_name
 Mapping rule: (ipacertmapdata=X509:{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
 Matching rule: <ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG
 Enabled: TRUE
```
This rule now links the subject and issuer from the smart card certificate to the value of the ipacertmapdata attribute in the user account.

Web UI: Creating a Certificate Identity Mapping Rule

Select Authentication → Certificate Identity Mapping Rules.
Click Add.
Fill out the components of the rule, and click Add.

Additional Resources

For details on the syntax of the certificate mapping and matching rules, see the sss-certmap(5) man page.
For details on using the ipa certmaprule-add command, execute it with the --help option.
For additional commands for managing identity mapping, use the ipa help certmap command.

23.1.2.4.3. Linking a User Account and a Smart Card Certificate

To link a specific user account with a smart card certificate, save the subject and issuer from the certificate in the ipacertmapdata attribute.

Command Line: Linking a User Account and a Smart Card Certificate

If you have access to the certificate, use the full certificate blob:

$ CERT=`cat cert.pem | tail -n +2| head -n -1 | tr -d '\r\n'`
$ ipa user-add-certmapdata idm_user --certificate $CERT
--------------------------------------------
Added certificate mappings to user "idm_user"
--------------------------------------------
  User login: idm_user
  Certificate mapping data: X509:<I>O=EXAMPLE.ORG,CN=Smart Card CA<S>CN=test,O=EXAMPLE.ORG

If you do not have access to the certificate, but know the subject and issuer, use the --subject and --issuer options:

$ ipa user-add-certmapdata idm_user --subject "O=EXAMPLE.ORG,CN=test" --issuer "CN=Smart Card CA,O=EXAMPLE.ORG"
--------------------------------------------
Added certificate mappings to user "idm_user"
--------------------------------------------
  User login: idm_user
  Certificate mapping data: X509:<I>O=EXAMPLE.ORG,CN=Smart Card CA<S>CN=test,O=EXAMPLE.ORG

If you are comfortable with the mapping format, provide the mapping data directly:

$ ipa user-add-certmapdata idm_user 'X509:<I>O=EXAMPLE.ORG,CN=Smart Card CA<S>CN=test,O=EXAMPLE.ORG'
 --------------------------------------------
 Added certificate mappings to user "idm_user"
 --------------------------------------------
  User login: idm_user
  Certificate mapping data: X509:<I>O=EXAMPLE.ORG,CN=Smart Card CA<S>CN=test,O=EXAMPLE.ORG

The user can now use the smart card to log in to the Identity Management server.

Web UI: Linking a User Account and a Smart Card Certificate

Click Identity → Users, and click on the required user login.
Click Add next to the Certificate mapping data entry.
Figure 23.1. Adding certificate mapping data
In the Add Certificate Mapping Data form, fill out the required information. Specify one of the following:
- The full certificate blob under Certificate
- The subject and issuer under Issuer and subject
- The mapping data directly under Certificate mapping data

Additional Resources

For details on the ipa user-add-certmapdata command, execute it with the --help option.

23.1.2.4.4. Examples of Identity Mapping Rules

Example 23.1. Active Directory Certificates for Identity Management Users

$ ipa certmaprule-add ad_cert_for_ipa_users \
  --maprule='(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})' \
  --matchrule='<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' \
  --domain=idm.example.com

Example 23.2. Active Directory Certificates for Active Directory Users

$ ipa certmaprule-add ad_cert_for_ad_users \
  --maprule='(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})' \
  --matchrule='<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' \
  --domain=ad.example.com

Example 23.3. Active Directory Certificates for Both Identity Management and Active Directory Users

$ ipa certmaprule-add ad_cert_for_ipa_and_ad_users \
  --maprule='(|(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500}))' \
  --matchrule='<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' \
  --domain=ad.example.com

In the above example, the filter definition in the --maprule option includes these criteria:

ipacertmapdata=X509:{issuer_dn!nss_x500}<S>{subject_dn!nss_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the ipacertmapdata attribute in an Identity Management user account
altSecurityIdentities=X509:{issuer_dn!ad_x500}<S>{subject_dn!ad_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the altSecurityIdentities attribute in an Active Directory user account

The filter definition in the --maprule option accepts the logical operator | (or), so that you can specify multiple criteria. In this case, the rule maps all user accounts that meet at least one of the criteria.

Example 23.4. Identity Management Certificates for Identity Management and Active Directory Users

$ ipa certmaprule-add ipa_cert_for_ad_users \
  --maprule='(|(userCertificate;binary={cert!bin})(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500}))' \
  --matchrule='<ISSUER>CN=Certificate Authority,O=REALM.EXAMPLE.COM' \
  --domain=idm.example.com --domain=ad.example.com

In the above example, the filter definition in the --maprule option includes these criteria:

userCertificate;binary={cert!bin} is a filter that returns Identity Management or Active Directory user entries that include the whole certificate
ipacertmapdata=X509:{issuer_dn!nss_x500}<S>{subject_dn!nss_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the ipacertmapdata attribute in an Identity Management user account
altSecurityIdentities=X509:{issuer_dn!ad_x500}<S>{subject_dn!ad_x500} is a filter that links the subject and issuer from a smart card certificate to the value of the altSecurityIdentities attribute in an Active Directory user account

23.1.2.4.5. Examples of Translating the Issuer from a Certificate to a Matching Rule

To get the issuer format required by a matching rule, reverse the path, and replace the delimiters (/) with commas:

Example 23.5. Translating the Issuer from a Certificate Issued by Identity Management

Example of a certificate issued by Identity Management:

# openssl x509 -in user.crt -noout -issuer
issuer= /O=REALM.EXAMPLE.COM/CN=Certificate Authority

The issuer of this certificate expressed in the format required by a matching rule:

'<ISSUER>CN=Certificate Authority,O=REALM.EXAMPLE.COM'

Example 23.6. Translating the Issuer from a Certificate with an Email Included

Example of a certificate that includes an email address:

# openssl x509 -in expired_user.pem -noout -issuer
issuer= /C=US/ST=North Carolina/L=Raleigh/O=Red Hat/OU=QE/CN=ExampleCA/emailAddress=admin@example.com

The issuer of this certificate expressed in the format required by a matching rule:

'<ISSUER>emailAddress=admin@example.com,CN=ExampleCA,OU=QE,O=Red Hat,L=Raleigh,ST=North Carolina,C=US'

23.1.2.5. Additional Resources

To verify the smart-card certificate links, see Section 23.1.3, “Finding Users That Match a Specified Certificate”.
For more details on identity mapping for certificates, see Matching and Mapping Certificates in the upstream SSSD documentation.

23.1.3. Finding Users That Match a Specified Certificate

To list all employees whose role account matches the certificate, present the Identity Management server with an employee's smart card certificate.

Perform these steps on any Identity Management system.

Command Line: Finding Users That Match a Specified Certificate

To find the user, specify one of the following:

The name of the certificate file:

$ ipa certmap-match cert.pem
 --------------
 1 user matched
 --------------
  Domain: IDM.EXAMPLE.COM
  User logins: idm_user
 ----------------------------
 Number of entries returned 1
 ----------------------------

The contents of the certificate:

$ ipa certmap-match --certificate="MII...."
 --------------
 1 user matched
 --------------
  Domain: IDM.EXAMPLE.COM
  User logins: idm_user
 ----------------------------
 Number of entries returned 1
 ----------------------------

This command returns also users in a trusted Active Directory domain if their user entries contain the full certificate blob:

$ ipa certmap-match --certificate="MII...."
 ---------------
 2 users matched
 ---------------
  Domain: ad.domain.com
  User logins: ad_user

  Domain: IDM.EXAMPLE.COM
  User logins: idm_user
 ----------------------------
 Number of entries returned 2
 ----------------------------

Web UI: Finding Users That Match a Specified Certificate

Click Authentication → Certificate Identity Mapping Rules → Certificate Mapping Match.
Enter the contents of the certificate in the Certificate field, and click Match. Identity Management displays the users who match the certificate under Matched Users.
Figure 23.2. List of users who match a certificate

Additional Resources

For details on the commands for certificate identity mapping, use the ipa help certmap command.
For details on the ipa certmap-match command, execute it with the --help option.

23.1.4. Additional Resources

For information on managing personal certificates and keys using the Enterprise Security Client, an application for Red Hat Certificate System, see Managing Smart Cards with the Enterprise Security Client in the Certificate System documentation.

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.