Search
SupportConsoleDevelopersStart a trialContact

Chapter 9. Configuring certificate mapping rules in Identity Management

download PDF

Certificate mapping rules are a convenient way of allowing users to authenticate using certificates in scenarios when the Identity Management (IdM) administrator does not have access to certain users' certificates. This is typically because the certificates have been issued by an external certificate authority.

9.1. Certificate mapping rules for configuring authentication

You might need to configure certificate mapping rules in the following scenarios:

  • Certificates have been issued by the Certificate System of the Active Directory (AD) with which the IdM domain is in a trust relationship.
  • Certificates have been issued by an external certificate authority.
  • The IdM environment is large with many users using smart cards. In this case, adding full certificates can be complicated. The subject and issuer are predictable in most scenarios and therefore easier to add ahead of time than the full certificate.

As a system administrator, you can create a certificate mapping rule and add certificate mapping data to a user entry even before a certificate is issued to a particular user. Once the certificate is issued, the user can log in using the certificate even though the full certificate has not yet been uploaded to the user entry.

In addition, as certificates are renewed at regular intervals, certificate mapping rules reduce administrative overhead. When a user’s certificate is renewed, the administrator does not have to update the user entry. For example, if the mapping is based on the Subject and Issuer values, and if the new certificate has the same subject and issuer as the old one, the mapping still applies. If, in contrast, the full certificate was used, then the administrator would have to upload the new certificate to the user entry to replace the old one.

To set up certificate mapping:

  1. An administrator has to load the certificate mapping data or the full certificate into a user account.
  2. An administrator has to create a certificate mapping rule to allow successful logging into IdM for a user whose account contains a certificate mapping data entry that matches the information on the certificate.

Once the certificate mapping rules have been created, when the end-user presents the certificate, stored either on a filesystem or a smart card, authentication is successful.

Note

The Key Distribution Center (KDC) has a cache for certificate mapping rules. The cache is populated on the first certauth request and it has a hard-coded timeout of 300 seconds. KDC will not see any changes to certificate mapping rules unless it is restarted or the cache expires.

For details on the individual components that make up a mapping rule and how to obtain and use them, see Components of an identity mapping rule in IdM and Obtaining the issuer from a certificate for use in a matching rule.

Note

Your certificate mapping rules can depend on the use case for which you are using the certificate. For example, if you are using SSH with certificates, you must have the full certificate to extract the public key from the certificate.

9.2. Components of an identity mapping rule in IdM

You configure different components when creating an identity mapping rule in IdM. Each component has a default value that you can override. You can define the components in either the web UI or the CLI. In the CLI, the identity mapping rule is created using the ipa certmaprule-add command.

Mapping rule

The mapping rule component 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, IdM does not apply mapping rules unconditionally, but only to the appropriate certificates. The appropriate certificates are defined using matching rules.

Note that if you leave the mapping rule option empty, the certificates are searched in the userCertificate attribute as a DER encoded binary file.

Define the mapping rule in the CLI using the --maprule option.

Matching rule

The matching rule component selects a certificate to which you want to apply the mapping rule. The default matching rule matches certificates with the digitalSignature key usage and clientAuth extended key usage.

Define the matching rule in the CLI using the --matchrule option.

Domain list

The domain list specifies the identity domains in which you want IdM to search the users when processing identity mapping rules. If you leave the option unspecified, IdM searches the users only in the local domain to which the IdM client belongs.

Define the domain in the CLI using the --domain option.

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.

Define the mapping rule priority in the CLI using the --priority option.

Certificate mapping rule example

To define, using the CLI, a certificate mapping rule called simple_rule that allows authentication for a certificate issued by the Smart Card CA of the EXAMPLE.ORG organization if the Subject on that certificate matches a certmapdata entry in a user account in IdM: 

# ipa certmaprule-add simple_rule --matchrule '<ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'

9.3. Obtaining data from a certificate for use in a matching rule

This procedure describes how to obtain data from a certificate so that you can copy and paste it into the matching rule of a certificate mapping rule. To get data required by a matching rule, use the sssctl cert-show or sssctl cert-eval-rule commands.

Prerequisites

  • You have the user certificate in PEM format.

Procedure

  1. Create a variable pointing to your certificate that also ensures it is correctly encoded so you can retrieve the required data. 

    # CERT=$(openssl x509 -in /path/to/certificate -outform der|base64 -w0)

  2. Use the sssctl cert-eval-rule to determine the matching data. In the following example the certificate serial number is used. 

    # sssctl cert-eval-rule $CERT --match='<ISSUER>CN=adcs19-WIN1-CA,DC=AD,DC=EXAMPLE,DC=COM' --map='LDAPU1:(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<SR>{serial_number!hex_ur})'
Certificate matches rule.
Mapping filter:

    (altSecurityIdentities=X509:<I>DC=com,DC=example,DC=ad,CN=adcs19-WIN1-CA<SR>0F0000000000DB8852DD7B246C9C0F0000003B)

    In this case, add everything after altSecurityIdentities= to the altSecurityIdentities attribute in AD for the user. If using SKI mapping, use --map='LDAPU1:(altSecurityIdentities=X509:<SKI>{subject_key_id!hex_u})'.

  3. Optionally, to create a new mapping rule in the CLI based on a matching rule which specifies that the certificate issuer must match adcs19-WIN1-CA of the ad.example.com domain and the serial number of the certificate must match the altSecurityIdentities entry in a user account: 

    # ipa certmaprule-add simple_rule --matchrule '<ISSUER>CN=adcs19-WIN1-CA,DC=AD,DC=EXAMPLE,DC=COM' --maprule 'LDAPU1:(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<SR>{serial_number!hex_ur})'

9.4. Configuring certificate mapping for users stored in IdM

To enable certificate mapping in IdM if the user for whom certificate authentication is being configured is stored in IdM, a system administrator must complete the following tasks:

  • Set up a certificate mapping rule so that IdM users with certificates that match the conditions specified in the mapping rule and in their certificate mapping data entries can authenticate to IdM.
  • Enter certificate mapping data to an IdM user entry so that the user can authenticate using multiple certificates provided that they all contain the values specified in the certificate mapping data entry.

Prerequisites

  • The user has an account in IdM.
  • The administrator has either the whole certificate or the certificate mapping data to add to the user entry.

9.4.1. Adding a certificate mapping rule in the IdM web UI

  1. Log in to the IdM web UI as an administrator.
  2. Navigate to Authentication Certificate Identity Mapping Rules Certificate Identity Mapping Rules.

  3. Click Add.

    Figure 9.1. Adding a new certificate mapping rule in the IdM web UI

    Screenshot of the IdM Web UI displaying the "Certificate Identity Mapping Rules" sub-tab from the Authentication tab. The "Add" button at the right of the page is highlighted.
  4. Enter the rule name.

  5. Enter the mapping rule. For example, to make IdM search for the Issuer and Subject entries in any certificate presented to them, and base its decision to authenticate or not on the information found in these two entries of the presented certificate: 

    (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})

  6. Enter the matching rule. For example, to only allow certificates issued by the Smart Card CA of the EXAMPLE.ORG organization to authenticate users to IdM: 

    <ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG

    Figure 9.2. Entering the details for a certificate mapping rule in the IdM web UI

    Screenshot of the "Add Certificate Identity Mapping Rule" pop-up window with the following fields filled in: Rule name (which is required) - Mapping rule - Matching rule. The Priority field is blank and there is also an Add button next to the Domain name label.
  7. Click Add at the bottom of the dialog box to add the rule and close the box.

  8. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD: 

    # systemctl restart sssd

Now you have a certificate mapping rule set up that compares the type of data specified in the mapping rule that it finds on a smart card certificate with the certificate mapping data in your IdM user entries. Once it finds a match, it authenticates the matching user.

9.4.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Enter the mapping rule and the matching rule the mapping rule is based on. For example, to make IdM search for the Issuer and Subject entries in any certificate presented, and base its decision to authenticate or not on the information found in these two entries of the presented certificate, recognizing only certificates issued by the Smart Card CA of the EXAMPLE.ORG organization: 

    # ipa certmaprule-add rule_name --matchrule '<ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'
-------------------------------------------------------
Added Certificate Identity Mapping Rule "rule_name"
-------------------------------------------------------
  Rule name: rule_name
  Mapping rule: (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})
  Matching rule: <ISSUER>CN=Smart Card CA,O=EXAMPLE.ORG
  Enabled: TRUE

  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD: 

    # systemctl restart sssd

Now you have a certificate mapping rule set up that compares the type of data specified in the mapping rule that it finds on a smart card certificate with the certificate mapping data in your IdM user entries. Once it finds a match, it authenticates the matching user.

9.4.3. Adding certificate mapping data to a user entry in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to Users Active users idm_user.
  3. Find the Certificate mapping data option and click Add.

  4. Choose one of the following options:

    • If you have the certificate of idm_user:

      1. In the command-line interface, display the certificate using the cat utility or a text editor: 

        [root@server ~]# cat idm_user_certificate.pem
-----BEGIN CERTIFICATE-----
MIIFFTCCA/2gAwIBAgIBEjANBgkqhkiG9w0BAQsFADA6MRgwFgYDVQQKDA9JRE0u
RVhBTVBMRS5DT00xHjAcBgNVBAMMFUNlcnRpZmljYXRlIEF1dGhvcml0eTAeFw0x
ODA5MDIxODE1MzlaFw0yMDA5MDIxODE1MzlaMCwxGDAWBgNVBAoMD0lETS5FWEFN
[...output truncated...]
      2. Copy the certificate.

      3. In the IdM web UI, click Add next to Certificate and paste the certificate into the window that opens up.

        Figure 9.3. Adding a user’s certificate mapping data: certificate

        Screenshot of a page displaying settings for the user "demouser" with an Identity Settings column on the left with entries such as Job Title - First name - Last name - Full name - Display name. The "Account Settings" column is on the right with entries such as User login - Password - UID - GID. The "Add" button for the "Certificates" entry is highlighted.
        • If you do not have the certificate of idm_user at your disposal but know the Issuer and the Subject of the certificate, check the radio button of Issuer and subject and enter the values in the two respective boxes.

        Figure 9.4. Adding a user’s certificate mapping data: issuer and subject

        Screenshot of the "Add Certificate Mapping Data" pop-up window with two radial button options: "Certificate mapping data" and "Issuer and subject." "Issuer and subject" is selected and its two fields (Issuer and Subject) have been filled out.
  5. Click Add.

Verification steps

If you have access to the whole certificate in the .pem format, verify that the user and certificate are linked:

  1. Use the sss_cache utility to invalidate the record of idm_user in the SSSD cache and force a reload of the idm_user information: 

    # sss_cache -u idm_user

  2. Run the ipa certmap-match command with the name of the file containing the certificate of the IdM user: 

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

    The output confirms that now you have certificate mapping data added to idm_user and that a corresponding mapping rule exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as idm_user.

9.4.4. Adding certificate mapping data to a user entry in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Choose one of the following options:

    • If you have the certificate of idm_user, add the certificate to the user account using the ipa user-add-cert command: 
    # CERT=$(openssl x509 -in idm_user_cert.pem -outform der|base64 -w0)
# ipa user-add-certmapdata idm_user --certificate $CERT

    • If you do not have the certificate of idm_user but know the Issuer and the Subject of the user’s certificate: 

      # 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

Verification steps

If you have access to the whole certificate in the .pem format, verify that the user and certificate are linked:

  1. Use the sss_cache utility to invalidate the record of idm_user in the SSSD cache and force a reload of the idm_user information: 

    # sss_cache -u idm_user

  2. Run the ipa certmap-match command with the name of the file containing the certificate of the IdM user: 

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

    The output confirms that now you have certificate mapping data added to idm_user and that a corresponding mapping rule exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as idm_user.

9.5. Certificate mapping rules for trusts with Active Directory domains

Different certificate mapping use cases are possible if an IdM deployment is in a trust relationship with an Active Directory (AD) domain.

Depending on the AD configuration, the following scenarios are possible:

  • If the certificate is issued by AD Certificate System but the user and the certificate are stored in IdM, the mapping and the whole processing of the authentication request takes place on the IdM side. For details of configuring this scenario, see Configuring certificate mapping for users stored in IdM

  • If the user is stored in AD, the processing of the authentication request takes place in AD. There are three different subcases:

    • The AD user entry contains the whole certificate. For details how to configure IdM in this scenario, see Configuring certificate mapping for users whose AD user entry contains the whole certificate.
    • AD is configured to map user certificates to user accounts. In this case, the AD user entry does not contain the whole certificate but instead contains an attribute called altSecurityIdentities. For details how to configure IdM in this scenario, see Configuring certificate mapping if AD is configured to map user certificates to user accounts.

    • The AD user entry contains neither the whole certificate nor the mapping data. In this case, there are two options:

      • If the user certificate is issued by AD Certificate System, the certificate either contains the user principal name as the Subject Alternative Name (SAN) or, if the latest updates are applied to AD, the SID of the user in the SID extension of the certificate. Both of these can be used to map the certificate to the user.
      • If the user certificate is on a smart card, to enable SSH with smart cards, SSSD must derive the public SSH key from the certificate and therefore the full certificate is required. The only solution is to use the ipa idoverrideuser-add command to add the whole certificate to the AD user’s ID override in IdM. For details, see Configuring certificate mapping if AD user entry contains no certificate or mapping data.

AD domain administrators can manually map certificates to a user in AD using the altSecurityIdentities attribute. There are six supported values for this attribute, though three mappings are considered insecure. As part of May 10,2022 security update, once it is installed, all devices are in compatibility mode and if a certificate is weakly mapped to a user, authentication occurs as expected. However, warning messages are logged identifying any certificates that are not compatible with full enforcement mode. As of November 14, 2023 or later, all devices will be updated to full enforcement mode and if a certificate fails the strong mapping criteria, authentication will be denied.

For example, when an AD user requests an IdM Kerberos ticket with a certificate (PKINIT), AD needs to map the certificate to a user internally and uses the new mapping rules for this. However in IdM, the previous rules continue to work if IdM is used to map a certificate to a user on an IdM client, .

IdM supports the new mapping templates, making it easier for an AD administrator to use the new rules and not maintain both. IdM now supports the new mapping templates added to Active Directory to include:

  • Serial Number: LDAPU1:(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<SR>{serial_number!hex_ur})
  • Subject Key Id: LDAPU1:(altSecurityIdentities=X509:<SKI>{subject_key_id!hex_u})
  • User SID: LDAPU1:(objectsid={sid})

If you do not want to reissue certificates with the new SID extension, you can create a manual mapping by adding the appropriate mapping string to a user’s altSecurityIdentities attribute in AD.

9.6. Configuring certificate mapping for users whose AD user entry contains the whole certificate

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD and the user entry in AD contains the whole certificate.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains a certificate.
  • The IdM administrator has access to data on which the IdM certificate mapping rule can be based.
Note

To ensure PKINIT works for a user, one of the following conditions must apply:

  • The certificate in the user entry includes the user principal name or the SID extension for the user.
  • The user entry in AD has a suitable entry in the altSecurityIdentities attribute.

9.6.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to Authentication Certificate Identity Mapping Rules Certificate Identity Mapping Rules.

  3. Click Add.

    Figure 9.5. Adding a new certificate mapping rule in the IdM web UI

    Screenshot of the IdM Web UI displaying the "Certificate Identity Mapping Rules" sub-page from the Authentication tab. The "Add" button to the right is highlighted.
  4. Enter the rule name.

  5. Enter the mapping rule. To have the whole certificate that is presented to IdM for authentication compared to what is available in AD: 

    (userCertificate;binary={cert!bin})
    Note

    If mapping using the full certificate, if you renew the certificate, you must ensure that you add the new certificate to the AD user object.

  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate: 

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com

    Figure 9.6. Certificate mapping rule for a user with a certificate stored in AD

    Screenshot of the "Add Certificate Identity Mapping Rule" pop-up window with the following fields filled in: Rule name (which is required) - Mapping rule - Matching rule. The Priority field is blank and there is also an "Add" button next to the "Domain name" label.
  7. Click Add.

  8. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI:: 

    # systemctl restart sssd

9.6.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Enter the mapping rule and the matching rule the mapping rule is based on. To have the whole certificate that is presented for authentication compared to what is available in AD, only allowing certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate: 

    # ipa certmaprule-add simpleADrule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(userCertificate;binary={cert!bin})' --domain ad.example.com
-------------------------------------------------------
Added Certificate Identity Mapping Rule "simpleADrule"
-------------------------------------------------------
  Rule name: simpleADrule
  Mapping rule: (userCertificate;binary={cert!bin})
  Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
  Domain name: ad.example.com
  Enabled: TRUE
    Note

    If mapping using the full certificate, if you renew the certificate, you must ensure that you add the new certificate to the AD user object.

  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD: 

    # systemctl restart sssd

9.7. Configuring certificate mapping if AD is configured to map user certificates to user accounts

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD, and the user entry in AD contains certificate mapping data.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains the altSecurityIdentities attribute, the AD equivalent of the IdM certmapdata attribute.
  • The IdM administrator has access to data on which the IdM certificate mapping rule can be based.

9.7.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to Authentication Certificate Identity Mapping Rules Certificate Identity Mapping Rules.

  3. Click Add.

    Figure 9.7. Adding a new certificate mapping rule in the IdM web UI

    Screenshot of the IdM Web UI displaying the "Certificate Identity Mapping Rules" sub-tab from the Authentication tab. The "Add" button at the right of the page is highlighted.
  4. Enter the rule name.

  5. Enter the mapping rule. For example, to make AD DC search for the Issuer and Subject entries in any certificate presented, and base its decision to authenticate or not on the information found in these two entries of the presented certificate: 

    (altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})

  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate users to IdM: 

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com

  7. Enter the domain: 

    ad.example.com

    Figure 9.8. Certificate mapping rule if AD is configured for mapping

    Screenshot of the "Add Certificate Identity Mapping Rule" pop-up window with the following fields filled in: Rule name (which is required) - Mapping rule - Matching rule. The "Priority" field is blank and there is also an "Add" button next to the "Domain name" label.
  8. Click Add.

  9. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI:: 

    # systemctl restart sssd

9.7.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Enter the mapping rule and the matching rule the mapping rule is based on. For example, to make AD search for the Issuer and Subject entries in any certificate presented, and only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain: 

    # ipa certmaprule-add ad_configured_for_mapping_rule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})' --domain=ad.example.com
-------------------------------------------------------
Added Certificate Identity Mapping Rule "ad_configured_for_mapping_rule"
-------------------------------------------------------
  Rule name: ad_configured_for_mapping_rule
  Mapping rule: (altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})
  Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
  Domain name: ad.example.com
  Enabled: TRUE

  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD: 

    # systemctl restart sssd

9.7.3. Checking certificate mapping data on the AD side

The altSecurityIdentities attribute is the Active Directory (AD) equivalent of certmapdata user attribute in IdM. When configuring certificate mapping in IdM in the scenario when a trusted AD domain is configured to map user certificates to user accounts, the IdM system administrator needs to check that the altSecurityIdentities attribute is set correctly in the user entries in AD.

Prerequisites

  • The user account must have user administration access.

Procedure

  • To check that AD contains the right information for the user stored in AD, use the ldapsearch command. For example, enter the command below to check with the adserver.ad.example.com server that the following conditions apply:

    • The altSecurityIdentities attribute is set in the user entry of ad_user.

    • The matchrule stipulates that the following conditions apply:

      • The certificate that ad_user uses to authenticate to AD was issued by AD-ROOT-CA of the ad.example.com domain.
      • The subject is <S>DC=com,DC=example,DC=ad,CN=Users,CN=ad_user: 
    $ ldapsearch -o ldif-wrap=no -LLL -h adserver.ad.example.com \
-p 389 -D cn=Administrator,cn=users,dc=ad,dc=example,dc=com \
-W -b cn=users,dc=ad,dc=example,dc=com "(cn=ad_user)" \
altSecurityIdentities
Enter LDAP Password:
dn: CN=ad_user,CN=Users,DC=ad,DC=example,DC=com
altSecurityIdentities: X509:<I>DC=com,DC=example,DC=ad,CN=AD-ROOT-CA<S>DC=com,DC=example,DC=ad,CN=Users,CN=ad_user

9.8. Configuring certificate mapping if AD user entry contains no certificate or mapping data

This user story describes the steps necessary for enabling certificate mapping in IdM if the IdM deployment is in trust with Active Directory (AD), the user is stored in AD and the user entry in AD contains neither the whole certificate nor certificate mapping data.

Prerequisites

  • The user does not have an account in IdM.
  • The user has an account in AD which contains neither the whole certificate nor the altSecurityIdentities attribute, the AD equivalent of the IdM certmapdata attribute.

  • The IdM administrator has done one of the following:

    • Added the whole AD user certificate to the AD user’s user ID override in IdM.
    • Created a certificate mapping rule that maps to an alternative field in the certificate, such as Subject Alternative Name or the SID of the user.

9.8.1. Adding a certificate mapping rule in the IdM web UI

  1. Log into the IdM web UI as an administrator.
  2. Navigate to Authentication Certificate Identity Mapping Rules Certificate Identity Mapping Rules.

  3. Click Add.

    Figure 9.9. Adding a new certificate mapping rule in the IdM web UI

    Screenshot of the IdM Web UI displaying the "Certificate Identity Mapping Rules" sub-page from the Authentication tab. The "Add" button to the right is highlighted
  4. Enter the rule name.

  5. Enter the mapping rule. To have the whole certificate that is presented to IdM for authentication compared to the certificate stored in the user ID override entry of the AD user entry in IdM: 

    (userCertificate;binary={cert!bin})
    Note

    As the certificate also contains the user principal name as the SAN, or with the latest updates, the SID of the user in the SID extension of the certificate, you can also use these fields to map the certificate to the user. For example, if using the SID of the user, replace this mapping rule with LDAPU1:(objectsid={sid}). For more information on certificate mapping, see the sss-certmap man page.

  6. Enter the matching rule. For example, to only allow certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate: 

    <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com

  7. Enter the domain name. For example, to search for users in the ad.example.com domain:

    Figure 9.10. Certificate mapping rule for a user with no certificate or mapping data stored in AD

    Screenshot of the "Add Certificate Identity Mapping Rule" pop-up window with the following fields filled in: Rule name (which is required) - Mapping rule - Matching rule. The "Priority" field is blank and there is also an Add button next to the "Domain name" label.
  8. Click Add.

  9. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD in the CLI: 

    # systemctl restart sssd

9.8.2. Adding a certificate mapping rule in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Enter the mapping rule and the matching rule the mapping rule is based on. To have the whole certificate that is presented for authentication compared to the certificate stored in the user ID override entry of the AD user entry in IdM, only allowing certificates issued by the AD-ROOT-CA of the AD.EXAMPLE.COM domain to authenticate: 

    # ipa certmaprule-add simpleADrule --matchrule '<ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com' --maprule '(userCertificate;binary={cert!bin})' --domain ad.example.com
-------------------------------------------------------
Added Certificate Identity Mapping Rule "simpleADrule"
-------------------------------------------------------
  Rule name: simpleADrule
  Mapping rule: (userCertificate;binary={cert!bin})
  Matching rule: <ISSUER>CN=AD-ROOT-CA,DC=ad,DC=example,DC=com
  Domain name: ad.example.com
  Enabled: TRUE
    Note

    As the certificate also contains the user principal name as the SAN, or with the latest updates, the SID of the user in the SID extension of the certificate, you can also use these fields to map the certificate to the user. For example, if using the SID of the user, replace this mapping rule with LDAPU1:(objectsid={sid}). For more information on certificate mapping, see the sss-certmap man page.

  3. The System Security Services Daemon (SSSD) periodically re-reads the certificate mapping rules. To force the newly-created rule to be loaded immediately, restart SSSD: 

    # systemctl restart sssd

9.8.3. Adding a certificate to an AD user’s ID override in the IdM web UI

  1. Navigate to Identity ID Views Default Trust View.

  2. Click Add.

    Figure 9.11. Adding a new user ID override in the IdM web UI

    Screenshot of the IdM Web UI displaying the "ID Views" page from the Identity tab. The Add button on the right is highlighted.
  3. In the User to override field, enter ad_user@ad.example.com.

  4. Copy and paste the certificate of ad_user into the Certificate field.

    Figure 9.12. Configuring the User ID override for an AD user

    Screenshot displaying the "Add User ID override" pop-up window with the following fields: User to override (which is required) - User login - GECOS - UID - GID - Certificate (which has been filled in with the plaintext version of a certificate).
  5. Click Add.

Verification steps

Verify that the user and certificate are linked:

  1. Use the sss_cache utility to invalidate the record of ad_user@ad.example.com in the SSSD cache and force a reload of the ad_user@ad.example.com information: 

    # sss_cache -u ad_user@ad.example.com

  2. Run the ipa certmap-match command with the name of the file containing the certificate of the AD user: 

    # ipa certmap-match ad_user_cert.pem
--------------
1 user matched
--------------
 Domain: AD.EXAMPLE.COM
 User logins: ad_user@ad.example.com
----------------------------
Number of entries returned 1
----------------------------

The output confirms that you have certificate mapping data added to ad_user@ad.example.com and that a corresponding mapping rule defined in Adding a certificate mapping rule if the AD user entry contains no certificate or mapping data exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as ad_user@ad.example.com.

Additional resources

Using ID views for Active Directory users

9.8.4. Adding a certificate to an AD user’s ID override in the IdM CLI

  1. Obtain the administrator’s credentials: 

    # kinit admin

  2. Store the certificate blob in a new variable called CERT: 

    # CERT=$(openssl x509 -in /path/to/certificate -outform der|base64 -w0)

  3. Add the certificate of ad_user@ad.example.com to the user account using the ipa idoverrideuser-add-cert command: 

    # ipa idoverrideuser-add-cert ad_user@ad.example.com --certificate $CERT

Verification steps

Verify that the user and certificate are linked:

  1. Use the sss_cache utility to invalidate the record of ad_user@ad.example.com in the SSSD cache and force a reload of the ad_user@ad.example.com information: 

    # sss_cache -u ad_user@ad.example.com

  2. Run the ipa certmap-match command with the name of the file containing the certificate of the AD user: 

    # ipa certmap-match ad_user_cert.pem
--------------
1 user matched
--------------
 Domain: AD.EXAMPLE.COM
 User logins: ad_user@ad.example.com
----------------------------
Number of entries returned 1
----------------------------

The output confirms that you have certificate mapping data added to ad_user@ad.example.com and that a corresponding mapping rule defined in Adding a certificate mapping rule if the AD user entry contains no certificate or mapping data exists. This means that you can use any certificate that matches the defined certificate mapping data to authenticate as ad_user@ad.example.com.

Additional resources

Using ID views for Active Directory users

9.9. Combining several identity mapping rules into one

To combine several identity mapping rules into one combined rule, use the | (or) character to precede the individual mapping rules, and separate them using () brackets, for example:

Certificate mapping filter example 1

$ 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:<I>{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 IdM user account, as described in Adding a certificate mapping rule in IdM
  • altSecurityIdentities=X509:<I>{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 AD user account, as described in Adding a certificate mapping rule if the trusted AD domain is configured to map user certificates
  • The addition of the --domain=ad.example.com option means that users mapped to a given certificate are not only searched in the local idm.example.com domain but also in the ad.example.com domain

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.

Certificate mapping filter example 2

$ 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:

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.

9.10. Additional resources

  • See the sss-certmap(5) man page.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.