9.9. 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 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.

9.9.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 mappings which handle most common configurations, and customized maps can be created. By default, during a bind attempt, only the first matching mapping rule is applied if SASL mapping fallback is not enabled. For further details about SASL mapping fallback, see Section 9.9.4, “Enabling SASL Mapping Fallback”.
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 the following 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: Provides the search base or a specific entry DN to match against the constructed DN.
  • Optional: nsSaslMapPriority: Sets the priority of this SASL mapping. The priority value is used, if nsslapd-sasl-mapping-fallback is enabled in cn=config. For details, see Section 9.9.4.1, “Setting SASL Mapping Priorities”.
For further details, see the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.
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 9.10.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.
If a priority is not set for a SASL mapping using the nsSaslMapPriority parameter, 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.

9.9.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=&)

9.9.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.

9.9.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.

9.9.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.

9.9.4. Enabling SASL Mapping Fallback

Using the default settings, Directory Server verifies only the first matching SASL mapping. If this first matching mapping fails, the bind operation fails and no further matching mappings are verified.
However, you can configure Directory Server to verify all matching mappings by enabling the nsslapd-sasl-mapping-fallback parameter: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-sasl-mapping-fallback
nsslapd-sasl-mapping-fallback: on
If fallback is enabled and only one user identity is returned, the bind succeeds. If no user, or more than one user is returned, the bind fails.

9.9.4.1. Setting SASL Mapping Priorities

If you enabled SASL mapping fallback using the nsslapd-sasl-mapping-fallback attribute, you can optionally set the nsSaslMapPriority attribute in mapping configurations to prioritize them. The nsSaslMapPriority attribute supports values from 1 (highest priority) to 100 (lowest priority). The default is 100.
For example, to set the highest priority for the cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config mapping: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=Kerberos uid mapping,cn=mapping,cn=sasl,cn=config
changetype: modify
replace: nsSaslMapPriority
nsSaslMapPriority: 1