Authentication (Binds)
Authentication is the act of confirming the identity of a principal. Authorization is the act of determining whether to grant or to deny access to a principal. Authentication is performed to make authorization decisions.
DS servers implement fine-grained access control for authorization. Authorization for an operation depends on who is requesting the operation. DS servers must authenticate the principal before making an authorization decision. In LDAP, the bind operation authenticates the principal.
Clients bind by providing a means to find their principal's entry, and credentials to check against the entry:
In a simple bind operation, the client provides an LDAP name, usually the DN identifying its entry, and the corresponding password stored in the entry.
In the simplest bind operation, the client provides a zero-length name and a zero-length password. This results in an anonymous bind, meaning the client is authenticated as an anonymous user of the directory. LDAP servers may allow anonymous binds to read public information, such as root DSE attributes.
Other bind mechanisms involve digital certificates, Kerberos tickets, or challenge response mechanisms that prove the client knows a password.
A user rarely knows, let alone enters, their DN. Instead, a user provides a client application with an identifying string stored in their entry, such as a user ID or an email address. The client application builds the DN directly from the user's identity string, or searches for the user entry based on the user's identity string to find the DN. The client application performs a simple bind with the resulting DN.
For example, suppose Babs Jensen enters her email address, bjensen@example.com, and password. The client application might search for the entry matching (mail=bjensen@example.com) under base DN dc=example,dc=com. Alternatively, the client application might extract the user ID bjensen from the address, then build the corresponding DN, uid=bjensen,ou=people,dc=example,dc=com, without a lookup.
Identity Mappers
When the mapping from the user identifier to the DN is known, DS servers can use an identity mapper to do the translation. Identity mappers are used to perform PLAIN SASL authentication (with a user name and password), SASL GSSAPI authentication (Kerberos V5), SASL CRAM MD5, and DIGEST MD5 authentication. They also map authorization IDs to DNs for password modify extended operations and proxied authorization.
One use of PLAIN SASL is to translate user names from HTTP Basic authentication to LDAP authentication. The following example shows PLAIN SASL authentication using the default exact match identity mapper. In this example, Babs Jensen has access to read the hashed value of her password. Notice the authentication ID is her user ID, u:bjensen, rather than the DN of her entry:
$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ --saslOption mech=PLAIN \ --saslOption authid=u:bjensen \ --bindPassword hifalutin \ "(cn=Babs Jensen)" \ userPassworddn: uid=bjensen,ou=People,dc=example,dc=com userPassword: {PBKDF2-HMAC-SHA256}10000:<hash>
The "Exact Match Identity Mapper" searches for a match between the string (here, bjensen), and the value of a specified attribute (by default, the uid attribute). By default, the identity mapper searches all public naming contexts local to the server. If duplicate entries exist, or if the required indexes are not available for all backends, this behavior can be restricted using the match-base-dn property.
You can configure multiple identity mappers, if necessary. When resolving the identity, the server uses the first identity mapper that finds a match. If multiple identity mappers match different entries, however, then the server returns LDAP error code 19, Constraint Violation.
If you know that users are entering their email addresses, you could create an exact match identity mapper for email addresses, then use that for PLAIN SASL authentication:
$dsconfig \ create-identity-mapper \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --mapper-name "Email Mapper" \ --type exact-match \ --set match-attribute:mail \ --set enabled:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt$dsconfig \ set-sasl-mechanism-handler-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --handler-name PLAIN \ --set identity-mapper:"Email Mapper" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ --saslOption mech=PLAIN \ --saslOption authid=u:bjensen@example.com \ --bindPassword hifalutin \ "(cn=Babs Jensen)" \ userPassworddn: uid=bjensen,ou=People,dc=example,dc=com userPassword: {PBKDF2-HMAC-SHA256}10000:<hash>
A "Regular Expression Identity Mapper" uses a regular expression to extract a substring from the string provided. The server searches for a match between the substring and the value of a specified attribute. When an email address is user ID + @ + domain, you can use the default regular expression identity mapper in the same way as the email mapper in the example above. The default regular expression pattern is ^([^@]+)@.+$, and the part of the identity string matching ([^@]+) is used to find the entry by user ID:
$dsconfig \ set-sasl-mechanism-handler-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword password \ --handler-name PLAIN \ --set identity-mapper:"Regular Expression" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --no-prompt$ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePasswordFile /path/to/opendj/config/keystore.pin \ --baseDN dc=example,dc=com \ --saslOption mech=PLAIN \ --saslOption authid=u:bjensen@example.com \ --bindPassword hifalutin \ "(cn=Babs Jensen)" \ userPassworddn: uid=bjensen,ou=People,dc=example,dc=com userPassword: {PBKDF2-HMAC-SHA256}10000:<hash>
Use the dsconfig command interactively to experiment with match-pattern and replace-pattern settings for the regular expression identity mapper. The match-pattern can be any javax.util.regex.Pattern regular expression.
Like the exact match identity mapper, the regular expression identity mapper searches all public naming contexts local to the server by default. If duplicate entries exist, this behavior can be restricted using the match-base-dn property.