Authentication

Use an authentication method to control access within the Directory Server.

Access control within the Directory Server is based on the distinguished name (DN) associated with a given connection. That DN is established as the result of a bind to (logging into) the Directory Server.

When the Directory Server is first configured, the following identities can be used to authenticate to the server:

Anonymous
The directory administrator (cn=administrator by default)
A projected IBM® i user profile

It is a good idea to create additional users that can be given authority to manage different parts of the directory without requiring that you share the directory administrator identity.

From an LDAP perspective, the frameworks for authenticating to LDAP follow:

Simple bind, in which an application provides a DN and the clear text password for that DN.
Simple Authentication and Security Layer (SASL), which provides several additional authentication methods, including CRAM-MD5, DIGEST-MD5, EXTERNAL, GSSAPI, and OS400-PRFTKN.

Simple bind, DIGEST-MD5, and CRAM-MD5

To use a simple bind, the client must supply the DN of an existing LDAP entry and a password which matches the userPassword attribute for that entry. For example, you could create an entry for John Smith as follows:

sample.ldif:
        dn: cn=John Smith,cn=users,o=acme,c=us
        objectclass: inetorgperson
        cn: John Smith
        sn: smith
        userPassword: mypassword

ldapadd -D cn=administrator -w secret -f sample.ldif

You can now use the DN "cn=John Smith,cn=users,o=acme,c=us" in access control, or make it a member of a group used in access control.

Several predefined objectclasses allow userPassword to be specified, including (but not limited to): person, organizationalperson, inetorgperson, organization, organizationalunit, and others.

The Directory Server passwords are case sensitive. If you create an entry with the userPassword value secret, a bind that specifies the password SECRET will fail.

When using a simple bind, the client sends the clear text password to the server as part of the bind request. This makes the password susceptible to protocol level snooping. An SSL connection could be used to protect the password (all information sent over an SSL connection is encrypted). Or the DIGEST-MD5 or CRAM-MD5 SASL methods can be used.

The CRAM-MD5 method requires that the server have access to the clear text password (password protection is set to none, which really means the password is stored in decryptable form and returned on searches as clear text), and the QRETSVRSEC (Retain server security data) system value must be 1 (Retain data). The client sends the DN to the server. The server retrieves the userPassword value for the entry and generates a random string. The random string is sent to the client. Both the client and the server hash the random string using the password as the key, and the client sends the result to the server. If the two hashed strings match, the bind request is successful, and the password was never sent to the server.

The DIGEST-MD5 method is similar to CRAM-MD5. It requires that the server have access to the clear text password (password protection is set to none) and that the QRETSVRSEC system value be set to 1. Instead of sending the DN to the server, DIGEST-MD5 requires that the client send a username value to the server. To be able to use DIGEST-MD5 for a regular user (not an admin) requires that no other entries in the directory have the same value for the username attribute. Other differences with DIGEST-MD5 include more configuration options: server realm, username attribute, and adminstrator password. Directory Server allows users to bind as projected or published users, where the server verifies the supplied password against a user profile's password on the system. Since the clear text password for user profiles is not available to the server, DIGEST-MD5 cannot be used with projected or published users.

Binding as a published user

The Directory Server provides a means to have an LDAP entry whose password is that of an the operating system user profile on the same system. To do this, the entry must:

Have a UID attribute, whose value is the name of an the operating system user profile
Not have a userPassword attribute

When the server receives a bind request for an entry that has a UID value but no userPassword, the server calls the operating system security to validate that the UID is a valid user profile name and that the specified password is the correct password for that user profile. Such an entry is called a published user in reference to publishing of the system distribution directory (SDD) to LDAP, which creates such entries.

Binding as a projected user

An LDAP entry representing an operating system user profile is referred to as a projected user. You can use the DN of a projected user along with the correct password for that user profile in a simple bind. For example, the DN for user JSMITH on system my-system.acme.com would be:

os400-profile=JSMITH,cn=accounts,os400-sys=my-system.acme.com

SASL EXTERNAL bind

If an SSL or TLS connection is used with client authentication (for example, the client has a private certificate), the SASL EXTERNAL method can be used. This method tells the server to get the client's identity from an external source, in this case the SSL connection. The server gets the public portion of the client certificate (sent to the server as part of establishing the SSL connection) and extracts the subject DN. That DN is assigned by the LDAP server to the connection.

For example, given a certificate assigned to:

common name: John Smith
organization unit: Engineering
organization: ACME
locality: Minneapolis
state: MN
country: US

The subject DN would be:

cn=John Smith,ou=Engineering,o=acme,l=Minneapolis,st=MN,c=US

Note that the cn, ou, o, l, st, and c elements are used in the order shown to generate the subject DN.

SASL GSSAPI bind

The SASL GSSAPI bind mechanism is used to authenticate to the server using a Kerberos ticket. This is useful when the client has done a KINIT or other form of Kerberos authentication (for example, Windows 2000 domain login). In this case, the server validates the client's ticket and then gets the Kerberos principal and realm names; for example, principal jsmith in realm acme.com, normally expressed as jsmith@acme.com. The server can be configured to map this identity to a DN in one of two ways:

Generate a pseudo DN of the form ibm-kn=jsmith@acme.com.
Search for an entry having the ibm-securityidentities auxiliary class and an altsecurityidenties value of the form KERBEROS:<principal>@<realm>.

An entry that could be used for jsmith@acme.com might look like:

dn: cn=John Smith,cn=users,o=acme,c=us
objectclass: inetorgperson
objectclass: ibm-securityidentities
cn: John Smith
sn: Smith
altsecurityidentities: kerberos:jsmith@acme.com

OS400-PRFTKN bind

The OS400-PRFTKN SASL bind mechanism is used to authenticate to the server using a profile token (refer to the Generate Profile Token API). When this mechanism is used, the server validates the profile token and associates the DN of the projected user profile with the connection (for example, os400-profile=JSMITH,cn=accounts,os400-system=my-as400.mycompany.com). If the application already has a profile token, this mechanism avoids the need to get the user profile name and user password to perform a simple bind. To use this mechanism, use the ldap_sasl_bind_s API, specifying a null DN, OS400-PRFTKN for the mechanism, and a berval (binary data that is encoded using simplified basic encoding rules) containing the 32-byte profile token for the credentials. When using the LDAP APIs in IBM i or using the QSH command utilities (such as ldapsearch) to access the local directory server, you can omit the password, and the client APIs will authenticate to the server as the current user profile for the job. For example:

> ldapsearch -m OS400-PRFTKN -b "o=ibm,c=us" "(uid=johndoe)"

will perform the search under the authority of the current user profile as if you had used:

> ldapsearch -D os400-profile=myprofile,cn=accounts,os400-sys=mysystem -w mypassword -b
"o=ibm,c=us" "(uid=johndoe)"

LDAP as an authentication service

LDAP is commonly used to provide an authentication service. You can configure a Web server to authenticate to LDAP. By setting up multiple Web servers (or other applications) to authenticate to LDAP, you can establish a single user registry for those applications, rather than defining users over and over for each application or Web server instance.

How does this work? In short, the Web server prompts the user for a user name and password. The Web server takes this information and then does a search in the LDAP directory for an entry with that user name (for example, you might configure the Web server to map the user name to the LDAP 'uid' or 'mail' attributes). If it finds exactly one entry, the Web server then sends a bind request to the server using the DN of the entry it just found and the user provided password. If the bind is successful, the user is now authenticated. SSL connections can be used to protect the password information from protocol level snooping.

The Web server can also keep track of the DN that was used so that a given application can use that DN, perhaps by storing customization data in that entry, another entry associated with it, or in a separate database using the DN as a key to find the information.

A common alternative to using a bind request is to use the LDAP compare operation. For example ldap_compare(ldap_session, dn, "userPassword", enteredPassword). This allows the application to use a single LDAP session, rather than starting and ending sessions for each authentication request.