JAAS Login Modules

Ldaptive provides several login modules for authentication and authorization against an LDAP. Each module accepts properties that correspond to the setters on objects in the ldaptive code base. If you are looking to set a specific configuration option that is available as a setter, the chances are that it will be accepted on the module. Any unknown options will logged at WARN level. Both the authentication and the connection documentation is useful for understanding JAAS configuration options.

LdapLoginModule

A JAAS module which authenticates against an LDAP.

Configuration

Authenticate a user using the ‘uid’ attribute and populate the user’s principals with the values of the ‘eduPersonAffiliation’ attribute.

ldaptive {
  org.ldaptive.jaas.LdapLoginModule required
    ldapUrl="ldap://ldaptive.directory.org:389"
    baseDn="ou=people,dc=ldaptive,dc=org"
    useStartTLS="true"
    userFilter="(uid={user})"
    userRoleAttribute="eduPersonAffiliation";
};

Performs the same function as the previous, but uses the bindDn and bindCredential to lookup to the user’s DN. In addition, the configured certificate will be used to trust the LDAP server.

ldaptive {
  org.ldaptive.jaas.LdapLoginModule required
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=people,dc=ldaptive,dc=org"
    bindDn="cn=priviledged_user,ou=services,dc=vt,dc=edu"
    bindCredential="notarealpassword"
    useStartTLS="true"
    credentialConfig="{trustCertificates=file:/path/to/certs.pem}"
    userFilter="(uid={user})"
    userRoleAttribute="eduPersonAffiliation";
};

bindCredential also supports reading from a resource so your password isn’t exposed in the JAAS configuration. Be careful not to include any trailing whitespace in the file, every byte is considered part of the credential.

    bindCredential="file:/path/to/bind.credential"

Module Options

Pooling

It is often desirable to use a pool of LDAP connections for both DN resolution and authentication. The stateless nature of JAAS modules makes this very difficult. Ldaptive provides a default AuthenticationFactory that supports caching to solve this problem.

ldaptive {
  org.ldaptive.jaas.LdapLoginModule required
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=people,dc=ldaptive,dc=org"
    bindDn="cn=priviledged_user,ou=services,dc=vt,dc=edu"
    bindCredential="notarealpassword"
    useStartTLS="true"
    userFilter="(uid={user})"
    userRoleAttribute="eduPersonAffiliation"
    dnResolver="org.ldaptive.auth.SearchDnResolver"
    authenticationHandler="org.ldaptive.auth.SimpleBindAuthenticationHandler"
    connectionFactory="org.ldaptive.PooledConnectionFactory"
    cacheId="ldaptive-pooled";
};

Note that both the dnResolver and the authenticationHandler will use a pool of connections in this example. The cacheId option is required for this configuration to work. Without it, the pools will be recreated for every request. It is the responsibility of the application to properly tear down the pools. This can be done by invoking: PropertiesAuthenticatorFactory#close().

Custom Configuration

It may be necessary to use a more powerful configuration mechanism than what can be achieved with JAAS options. For those cases the AuthenticatorFactory interface exists to allow developers a greater level of control for how objects are wired together. For instance, an AuthenticatorFactory could be written to leverage Spring IOC:

This allows you to break free of the restrictive format imposed by the JAAS config. A sample implementation that uses Spring can be seen here.

LdapRoleAuthorizationModule

A JAAS module which provides authorization data from an LDAP. This module is meant to be stacked with a module that has performed authentication.

Configuration

Authenticate a user using the ‘uid’ attribute and populate the user’s principals with the values of the ‘eduPersonAffiliation’ attribute. Populate the user’s principals with value of the ‘uugid’ attribute found on any entries in the ‘ou=groups,dc=ldaptive,dc=org’ branch which contain a member attribute value that includes this user’s DN.

ldaptive {
  org.ldaptive.jaas.LdapLoginModule required
    storePass="true"
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=people,dc=ldaptive,dc=org"
    useStartTLS="true"
    userFilter="(uid={user})"
    userRoleAttribute="eduPersonAffiliation";
  org.ldaptive.jaas.LdapRoleAuthorizationModule required
    useFirstPass="true"
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=groups,dc=vt,dc=edu"
    roleFilter="(member={dn})"
    roleAttribute="uugid";
};

Module Options

LdapDnAuthorizationModule

A JAAS module which injects the login name, login dn, and/or login password into shared state. This module is meant to be stacked with a module that has performed authentication.

Configuration

Uses Kerberos for authentication and then injects LDAP data into the subject. Note that the LdapDnAuthorizationModule is stacked before the LdapRoleAuthorizationModule so that the DN can be leveraged in the roleFilter query.

ldaptive {
  com.sun.security.auth.module.Krb5LoginModule required
    storePass="true"
    debug="true";
  org.ldaptive.jaas.LdapDnAuthorizationModule required
    useFirstPass="true"
    storePass="true"
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=people,dc=ldaptive,dc=org"
    useStartTLS="true"
    userFilter="(uid={user})";
  org.ldaptive.jaas.LdapRoleAuthorizationModule required
    useFirstPass="true"
    ldapUrl="ldap://directory.ldaptive.org:389"
    baseDn="ou=groups,dc=vt,dc=edu"
    roleFilter="(member={dn})"
    roleAttribute="uugid";
};

Module Options