Using the certmap.conf File
Certificate mapping determines how a server looks up a user entry in the LDAP directory. You can use certmap.conf to configure how a certificate, designated by name, is mapped to an LDAP entry. You edit this file and add entries to match the organization of your LDAP directory, and to list the certificates you want your users to have. Users can be authenticated based on user ID, e-mail, or any other value used in the subjectDN. Specifically, the mapping file defines the following information:
-
Where in the LDAP tree the server should begin the search
-
What certificate attributes the server should use as search criteria when searching for the entry in the LDAP directory
-
Whether the server goes through an additional verification process
The certificate mapping file is found in the following location:
server_root/userdb/certmap.conf
The file contains one or more named mappings, each applying to a different CA. A mapping has the following syntax:
certmap name issuerDNname:property [value]
The first line specifies a name for the entry and the attributes that form the distinguished name found in the CA certificate. The name is arbitrary and can be defined to whatever you prefer. However, issuerDN must exactly match the issuer DN of the CA that issued the client certificate. For example, the following two issuer DN lines differ only in the spaces separating the attributes, but the server treats these two entries as different:
certmap sun1 ou=Sun Certificate Authority,o=Sun,c=UScertmap sun2 ou=Sun Certificate Authority, o=Sun, c=US
Note –
If you are using Sun Java System Directory Server and experiencing problems in matching the issuer DN, check the Directory Server error logs for useful information.
The second and subsequent lines in the named mapping match properties with values. The certmap.conf file has six default properties (you can use the certificate API to customize your own properties):
-
DNComps is a list of comma-separated attributes used to determine where in the LDAP directory the server should start searching for entries that match the user’s information (that is, the owner of the client certificate). The server gathers values for these attributes from the client certificate and uses the values to form an LDAP DN, which then determines where the server starts its search in the LDAP directory. For example, if DNComps is set to use the o and c attributes of the DN, the server starts the search from the o=org, c= country entry in the LDAP directory, where org and country are replaced with values from the DN in the certificate.
Note the following situations:
-
If there is no DNComps entry in the mapping, the server uses either the CmapLdapAttr setting or the entire subject DN in the client certificate (that is, the end user’s information).
-
If the DNComps entry is present but has no value, the server searches the entire LDAP tree for entries matching the filter.
FilterComps is a list of comma-separated attributes used to create a filter by gathering information from the user’s DN in the client certificate. The server uses the values for these attributes to form the search criteria used to match entries in the LDAP directory. If the server finds one or more entries in the LDAP directory that match the user’s information gathered from the certificate, the search is successful and the server optionally performs a verification.
For example, if FilterComps is set to use the e-mail and user ID attributes (FilterComps=e,uid), the server searches the directory for an entry whose values for e-mail and user ID match the end user’s information gathered from the client certificate. E-mail addresses and user IDs are good filters because they are usually unique entries in the directory. The filter needs to be specific enough to match one and only one entry in the LDAP database.
The attribute names for the filters need to be attribute names from the certificate, not from the LDAP directory. For example, some certificates have an e attribute for the user’s e-mail address, whereas LDAP calls that attribute mail.
The following table lists the attributes for x509v3 certificates.
-
|
Attribute |
Description |
|---|---|
|
Country |
|
|
Organization |
|
|
Common name |
|
|
Location |
|
|
State |
|
|
Organizational unit |
|
|
UNIX/Linux userid |
|
|
E-mail address |
-
verifycert tells the server whether the client’s certificate should be compared with the certificate found in the LDAP directory. It takes two values: on and off. Use this property only if your LDAP directory contains certificates. This feature is useful to ensure that end users have a valid, unrevoked certificate.
-
CmapLdapAttr is a name for the attribute in the LDAP directory that contains subject DNs from all certificates belonging to the user. The default for this property is certSubjectDN. This attribute is not a standard LDAP attribute, so to use this property, you must extend the LDAP schema. For more information, see Introduction to SSL.
If this property exists in the certmap.conf file, the server searches the entire LDAP directory for an entry whose attribute (named with this property) matches the subject’s full DN (taken from the certificate). If no entries are found, the server retries the search using the DNComps and FilterComps mappings.
This approach to matching a certificate to an LDAP entry is useful when it’s difficult to match entries using DNComps and FilterComps.
-
Library is a property whose value is a path name to a shared library or DLL. Use this property only if you create your own properties using the certificate API.
-
InitFn is a property whose value is the name of an init function from a custom library. Use this property only if you create your own properties using the certificate API.
For more information about these properties, refer to the examples described in Sample Mappings.
Creating Custom Properties
The client certificate API can be used to create your own properties. Once you have a custom mapping, you reference the mapping as follows:
name:library path_to_shared_libraryname:InitFN name_of_init_function
For example:
certmap default1 o=Sun Microsystems, c=US default1:library /usr/sun/userdb/plugin.so default1:InitFn plugin_init_fn default1:DNComps ou o c default1:FilterComps l default1:verifycert on
Sample Mappings
The certmap.conf file should have at least one entry. The following examples illustrate the different ways certmap.conf can be used.
Example #1
This example represents a certmap.conf file with only one default mapping:
certmap default defaultdefault:DNComps ou, o, cdefault:FilterComps e, uiddefault:verifycert on
Using this example, the server starts its search at the LDAP branch point containing the entry ou=orgunit, o=org, c=country, where the italicized text is replaced with the values from the subject’s DN in the client certificate.
The server then uses the values for e-mail address and user ID from the certificate to search for a match in the LDAP directory. When an entry is found, the server verifies the certificate by comparing the one sent by the client to the one stored in the directory.
Example #2
The following example file has two mappings: one for default and another for the US Postal Service:
certmap default defaultdefault:DNCompsdefault:FilterComps e, uid
certmap usps ou=United States Postal Service, o=usps, c=USusps:DNComps ou,o,cusps:FilterComps eusps:verifycert on
When the server receives a certificate from anyone other than the US Postal Service, it uses the default mapping, which starts at the top of the LDAP tree and searches for an entry matching the client’s e-mail and user ID. If the certificate is from the US Postal Service, the server starts its search at the LDAP branch containing the organizational unit and searches for matching e-mail addresses. Also note that if the certificate is from the US Postal Service, the server verifies the certificate. Other certificates are not verified.
Caution – The issuer DN (that is, the CA’s information) in the certificate must be identical to the issuer DN listed in the first line of the mapping. In the previous example, a certificate from an issuer DN that is o=United States Postal Service,c=US will not match because there is not a space between the o and the c attributes.
Example #3
The following example uses the CmapLdapAttr property to search the LDAP database for an attribute called certSubjectDN, whose value exactly matches the entire subject DN taken from the client certificate.
certmap myco ou=My Company Inc, o=myco, c=USmyco:CmapLdapAttr certSubjectDNmyco:DNComps o, c myco:FilterComps mail, uid myco:verifycert on
If the client certificate subject is:
uid=Walt Whitman, o=LeavesOfGrass Inc, c=US
the server first searches for entries that contain the following information:
certSubjectDN=uid=Walt Whitman, o=LeavesOfGrass Inc, c=US
If one or more matching entries are found, the server proceeds to verify the entries. If no matching entries are found, the server uses DNComps and FilterComps to search for matching entries. In this example, the server searches for uid=Walt Whitman in all entries under o=LeavesOfGrass Inc, c=US.
Note –
This example assumes the LDAP directory contains entries with the attribute certSubjectDN.
- © 2010, Oracle Corporation and/or its affiliates