9.10. Setting up SASL Identity Mapping
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.10.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.10.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 suppliedauthid.nsSaslMapFilterTemplate: A template which applies the elements of thensSaslMapRegexStringto 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, ifnsslapd-sasl-mapping-fallbackis enabled incn=config. For details, see Section 9.10.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.11.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.10.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.10.3. Configuring SASL Identity Mapping
(Simple Authentication and Security Layer) 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.10.3.1. Configuring SASL Identity Mapping Using the Command Line
To configure SASL identity mapping from the command line, use the
dsconf utility to add the identity mapping scheme.
- Add the identity mapping scheme. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com sasl create --cn "example_map" --nsSaslMapRegexString "\(.*\)" --nsSaslMapBaseDNTemplate "ou=People,dc=example,dc=com" --nsSaslMapFilterTemplate "(cn=\1)" --nsSaslMapPriority 50 Successfully created example_map
This matches any user's common name and maps it to the result of the subtree search with baseou=People,dc=example,dc=com, based on the filtercn=userId. - Restart the instance:
# dsctl instance_name restart
Note
Adding the SASL map with
dsconf adds the mapping to the end of the list, regardless of its ASCII order.
9.10.3.2. Configuring SASL Identity Mapping Using the Web Console
To add a SASL identity mapping scheme:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open the menu, and select SASL Settings & Mappings.
- Click .
- Fill the form. For example:
- Click .
9.10.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:
# dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-sasl-mapping-fallback=on Successfully replaced "nsslapd-sasl-mapping-fallback"
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.10.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
