Chapter 4. Certificate mapping rules for configuring authentication on smart cards
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 lack of access is typically caused by the fact that the certificates have been issued by an external certificate authority. A special use case is represented by certificates issued by the Certificate System of an Active Directory (AD) with which the IdM domain is in a trust relationship.
Certificate mapping rules are also convenient if the IdM environment is large with a lot of users using smart cards. In this situation, adding full certificates can be complicated. The subject and issuer are predictable in most scenarios and thus 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 have to be renewed at regular intervals, certificate mapping rules reduce administrative overhead. When a user’s certificate gets 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:
- An administrator has to load the certificate mapping data (typically the issuer and subject) or the full certificate into a user account.
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
- whose certificate mapping data entry matches the information on the certificate
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.
Afterwards, when the end-user presents the certificate, stored either in the filesystem or on a smart card, authentication is successful.
4.1. Certificate mapping rules for trusts with Active Directory domains
This section outlines the different certificate mapping use cases that are possible if an IdM deployment is in a trust relationship with an Active Directory (AD) domain.
Certificate mapping rules are a convenient way to enable access to IdM resources for users who have smart card certificates that were issued by the trusted AD Certificate System. Depending on the AD configuration, the following scenarios are possible:
- If the certificate is issued by AD 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, 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 .
4.2. Components of an identity mapping rule in IdM
This section describes the components of an identity mapping rule in IdM and how to configure them. 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 andclientAuth 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
organisation as long as 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})'
4.3. Obtaining the issuer from a certificate for use in a matching rule
This procedure describes how to obtain the issuer information from a certificate so that you can copy and paste it into the matching rule of a certificate mapping rule. To get the issuer format required by a matching rule, use the openssl x509
utility.
Prerequisites
-
You have the user certificate in a
.pem
or.crt
format
Procedure
Obtain the user information from the certificate. Use the
openssl x509
certificate display and signing utility with:-
the
-noout
option to prevent the output of an encoded version of the request -
the
-issuer
option to output the issuer name -
the
-in
option to specify the input file name to read the certificate from the
-nameopt
option with theRFC2253
value to display the output with the most specific relative distinguished name (RDN) firstIf the input file contains an Identity Management certificate, the output of the command shows that the Issuer is defined using the
Organisation
information:# openssl x509 -noout -issuer -in idm_user.crt -nameopt RFC2253 issuer=CN=Certificate Authority,O=REALM.EXAMPLE.COM
If the input file contains an Active Directory certificate, the output of the command shows that the Issuer is defined using the
Domain Component
information:# openssl x509 -noout -issuer -in ad_user.crt -nameopt RFC2253 issuer=CN=AD-WIN2012R2-CA,DC=AD,DC=EXAMPLE,DC=COM
-
the
Optionally, to create a new mapping rule in the CLI based on a matching rule which specifies that the certificate issuer must be the extracted
AD-WIN2012R2-CA
of thead.example.com
domain and the subject on the certificate must match thecertmapdata
entry in a user account in IdM:# ipa certmaprule-add simple_rule --matchrule '<ISSUER>CN=AD-WIN2012R2-CA,DC=AD,DC=EXAMPLE,DC=COM' --maprule '(ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})'
4.4. Additional resources
-
See the
sss-certmap(5)
man page.