7.11. Setting up SASL Identity Mapping

Red Hat Directory Server supports LDAP client authentication through the Simple Authentication and Security Layer (SASL), an alternative to TLS/SSL and a native way for some applications to share information securely.
Simple Authentication and Security Layer (SASL) is an abstraction layer between protocols like LDAP and authentication methods like GSS-API which allows any protocol which can interact with SASL to utilize any authentication mechanism which can work with SASL. Simply put, SASL is an intermediary that makes authenticating to applications using different mechanisms easier. SASL can also be used to establish an encrypted session between a client and server.
The SASL framework allows different mechanisms to be used to authenticate a user to the server, depending on what mechanism is enabled in both client and server applications. SASL also creates a layer for encrypted (secure) sessions. Using GSS-API, Directory Server utilizes Kerberos tickets to authenticate sessions and encrypt data.

7.11.1. About SASL Identity Mapping

When processing a SASL bind request, the server matches, or maps, the SASL authentication ID used to authenticate to the Directory Server with an LDAP entry stored within the server. When using Kerberos, the SASL user ID usually has the format userid@REALM, such as scarter@EXAMPLE.COM. This ID must be converted into the DN of the user's Directory Server entry, such as uid=scarter,ou=people,dc=example,dc=com.
If the authentication ID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication ID automatically to the entry DN. Directory Server has some pre-configured default maps which handle most common configurations, and customized maps can be created. During a bind attempt, the first matching mapping rule is applied. If only one user identity is returned, the bind is successful; if none or more than one are returned, then the bind fails.
Be sure to configure SASL maps so that only one mapping rule matches the authentication string.
SASL mappings are configured by entries under a container entry: 
dn: cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: sasl
SASL identity mapping entries are children of this entry: 
dn: cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: mapping
Mapping entries are defined by three attributes:
  • nsSaslMapRegexString, the regular expression which is used to map the elements of the supplied authid
  • nsSaslMapFilterTemplate, a template which applies the elements of the nsSaslMapRegexString to create the DN
  • nsSaslMapBaseDNTemplate, which provides the search base or a specific entry DN to match against the constructed DN
For example: 
dn: cn=mymap,cn=mapping,cn=sasl,cn=config
objectclass:top
objectclass:nsSaslMapping
cn: mymap
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapFilterTemplate: (objectclass=inetOrgPerson)
nsSaslMapBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3
The nsSaslMapRegexString attribute sets variables of the form \1, \2, \3 for bind IDs which are filled into the template attributes during a search. This example sets up a SASL identity mapping for any user in the ou=People,dc=example,dc=com subtree who belongs to the inetOrgPerson object class.
When a Directory Server receives a SASL bind request with mconnors@EXAMPLE.COM as the user ID (authid), the regular expression fills in the base DN template with uid=mconnors,ou=people,dc=EXAMPLE,dc=COM as the user ID, and authentication proceeds from there.

Note

The dc values are not case sensitive, so dc=EXAMPLE and dc=example are equivalent.
The Directory Server can also use a more inclusive mapping scheme, such as the following: 
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This matches any user ID and map it an entry under the ou=People,dc=example,dc=com subtree which meets the filter cn=userId.
Mappings can be confined to a single realm by specifying the realm in the nsSaslMapRegexString attribute. For example: 
dn: cn=example map,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)@US.EXAMPLE.COM  
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This mapping is identical to the previous mapping, except that it only applies to users authenticating from the US.EXAMPLE.COM realm. (Realms are described in Section 7.12.2.1, “About Principals and Realms”.)
When a server connects to another server, such as during replication or with chaining, the default mappings for the will not properly map the identities. This is because the principal (SASL identity) for one server does not match the principal on the server where authentication is taking place, so it does not match the mapping entries.
To allow server to server authentication using SASL, create a mapping for the specific server principal to a specific user entry. For example, this mapping matches the ldap1.example.com server to the cn=replication manager,cn=config entry. The mapping entry itself is created on the second server, such as ldap2.example.com. 
dn: cn=z,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: z
nsSaslMapRegexString: ldap/ldap1.example.com@EXAMPLE.COM
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Sometimes, the realm name is not included in the principal name in SASL GSS-API configuration. A second mapping can be created which is identical to the first, only without specifying the realm in the principal name. For example: 
dn: cn=y,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: y
nsSaslMapRegexString: ldap/ldap1.example.com
nsSaslMapBaseDNTemplate: cn=replication manager,cn=config
nsSaslMapFilterTemplate: (objectclass=*)
Because the realm is not specified, the second mapping is more general (meaning, it has the potential to match more entries than the first. The best practice is to have more specific mappings processed first and gradually progress through more general mappings.
There is no way to specify the order that mappings are processed. However, there is a way to control how SASL mappings are processed: the name. The Directory Server processes SASL mappings in reverse ASCII order. In the past two example, then the cn=z mapping (the first example) is processed first. If there is no match, the server processes the cn=y mapping (the second example).

Note

SASL mappings can be added when an instance is created during a silent installation by specifying the mappings in an LDIF file and adding the LDIF file with the ConfigFile directive. Using silent installation is described in the Installation Guide.

7.11.2. Default SASL Mappings for Directory Server

The Directory Server has pre-defined SASL mapping rules to handle some of the most common usage.
Kerberos UID Mapping

This matches a Kerberos principal using a two part realm, such as user@example.com. The realm is then used to define the search base, and the user ID (authid) defines the filter. The search base is dc=example,dc=com and the filter of (uid=user). 

dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: Kerberos uid mapping
nsSaslMapRegexString: \(.*\)@\(.*\)\.\(.*\)
nsSaslMapBaseDNTemplate: dc=\2,dc=\3
nsSaslMapFilterTemplate: (uid=\1)
RFC 2829 DN Syntax

This mapping matches an authid that is a valid DN (defined in RFC 2829) prefixed by dn:. The authid maps directly to the specified DN. 

dn: cn=rfc 2829 dn syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 dn syntax
nsSaslMapRegexString: ^dn:\(.*\)
nsSaslMapBaseDNTemplate: \1
nsSaslMapFilterTemplate: (objectclass=*)
RFC 2829 U Syntax

This mapping matches an authid that is a UID prefixed by u:. The value specified after the prefix defines a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database. 

dn: cn=rfc 2829 u syntax,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: rfc 2829 u syntax
nsSaslMapRegexString: ^u:\(.*\)
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=\1)
UID Mapping

This mapping matches an authid that is any plain string that does not match the other default mapping rules. It use this value to define a filter of (uid=value). The search base is hard-coded to be the suffix of the default userRoot database. 

dn: cn=uid mapping,cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsSaslMapping
cn: uid mapping
nsSaslMapRegexString: ^[^:@]+$
nsSaslMapBaseDNTemplate: dc=example,dc=com
nsSaslMapFilterTemplate: (uid=&)

7.11.3. Configuring SASL Identity Mapping

SASL identity mapping can be configured from either the Directory Server or the command line. For SASL identity mapping to work for SASL authentication, the mapping must return one, and only one, entry that matches and Kerberos must be configured on the host machine.

7.11.3.1. Configuring SASL Identity Mapping from the Console

  1. In the Directory Server Console, open the Configuration tab.
  2. Select the SASL Mapping tab.
  3. To add a new SASL identity mapping, select the Add button, and fill in the required values.
    • Name. This field sets the unique name of the SASL mapping.
    • Regular expression. This field sets the regular expression used to match the DN components, such as \(.*\). This field corresponds to the nsSaslMapRegexString value in the SASL mapping LDIF entry.
    • Search base DN. This field gives the base DN to search to map entries, such as ou=People,dc=example,dc=com. This field corresponds to the nsSaslMapBaseDNTemplate value in the SASL mapping LDIF entry.
    • Search filter. This field gives the search filter for the components to replace, such as (objectclass=*). This field corresponds to the nsSaslMapFilterTemplate value in the SASL mapping LDIF entry.
To edit a SASL identity mapping, highlight that identity in the SASL Mapping tab, and click Modify. Change any values, and save.
To delete a SASL identity mapping, highlight it and hit Delete. A dialog box comes up to confirm the deletion.

7.11.3.2. Configuring SASL Identity Mapping from the Command Line

To configure SASL identity mapping from the command line, use the ldapmodify utility to add the identity mapping scheme. For example: 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=example map,cn=mapping,cn=sasl,cn=config
changetype: add
objectclass: top
objectclass: nsSaslMapping
cn: example map
nsSaslMapRegexString: \(.*\)
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=\1)
This matches any user's common name and maps it to the result of the subtree search with base ou=People,dc=example,dc=com, based on the filter cn=userId.

Note

When SASL maps are added over LDAP, they are not used by the server until it is restarted. Adding the SASL map with ldapmodify adds the mapping to the end of the list, regardless of its ASCII order.