9.10. Setting up SASL Identity Mapping
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: SASL identity mapping entries are children of this entry: 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.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: 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: 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: This mapping is identical to the 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 . 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: 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) . 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. 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. 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. 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: 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 . Restart the instance: 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 Server Settings menu, and select SASL Settings & Mappings . Click Create New Mapping . Fill the form. For example: Click Save . 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: 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:
dn: cn=sasl,cn=config objectClass: top objectClass: nsContainer cn: sasl dn: cn=mapping,cn=sasl,cn=config objectClass: top objectClass: nsContainer cn: mapping 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 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) 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) 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=*) 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=*) 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) 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=*) 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) dn: cn=uid mapping,cn=mapping,cn=sasl,cn=config objectClass: top objectClass: nsSaslMapping cn: uid mapping nsSaslMapRegexString: ^[^:@]+USD nsSaslMapBaseDNTemplate: dc=example,dc=com nsSaslMapFilterTemplate: (uid=&) 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 dsctl instance_name restart dsconf -D "cn=Directory Manager" ldap://server.example.com config replace nsslapd-sasl-mapping-fallback=on Successfully replaced "nsslapd-sasl-mapping-fallback" 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