Tutorial: Login Using LDAP Integration

Login Using LDAP Integration

Flitter Auth includes first-class support for LDAP authentication (including registration of new users). The module:flitter-auth/ldap/LdapProvider~LdapProvider auth provider handles the logic for this.

Configuration

The config/auth.config.js file has an example LDAP configuration in the sources key:

// LDAP-backed auth provider
example_ldap: {
    type: 'LdapProvider',
    enable: env('AUTH_LDAP_ENABLE', false),

    host: env('AUTH_LDAP_HOST', 'localhost'),
    port: env('AUTH_LDAP_PORT', 389),
    secure: env('AUTH_LDAP_BIND_SECURE', false),
    bind_dn: env('AUTH_LDAP_BIND_DN', 'uid=auth_agent,ou=people,dc=domain,dc=local'),
    bind_secret: env('AUTH_LDAP_BIND_PW'),

    user_search_base: env('AUTH_LDAP_SEARCH_BASE', 'ou=people,dc=domain,dc=local'),
    user_filter: env('AUTH_LDAP_USER_FILTER', '(uid=%u)'), // %u is the login provided username

    min_password_length: env('AUTH_MIN_PASSWORD_LENGTH', 8),

    // Maps flitter-auth roles to LDAP groups
    role_groups: {
        // Should correspond to existing auth roles
        // role_name: 'cn=somegroup,ou=groups,dc=domain,dc=local',
    },

    // Maps user attributes to LDAP data attributes
    attributes: {
        uid: env('AUTH_LDAP_ATTR_UID', 'uid'),
        first_name: env('AUTH_LDAP_ATTR_FIRST_NAME', 'cn'),
        last_name: env('AUTH_LDAP_ATTR_LAST_NAME', 'sn'),
        email: env('AUTH_LDAP_ATTR_EMAIL', 'mail'),

        // Special case - used to determine group memberships
        group_membership: env('AUTH_LDAP_ATTR_GROUPS', 'memberOf'),
    },

    registration: env('AUTH_LDAP_REGISTRATION', false),

    // Default attributes for new registered users
    // %u can be used to interpolate the registered user's uid
    registration_merge_attributes: {
        objectClass: ['posixAccount', 'shadowAccount', 'inetOrgPerson'],
        sn: '%u',
        cn: '%u',
        gecos: '%u',
        uidNumber: -1,
        gidNumber: -1,
        homeDirectory: '/dev/null',
    },
},

This creates an auth provider names example_ldap that loads most of its parameters from environment variables. Let's look at each of the parameters in turn:

LDAP Parameters

type (default: 'LdapProvider')

This is the type of auth provider. For LDAP, this is always LdapProvider.

enable (default: false)

If true, allow users to authenticate with this provider.

host (default: localhost)

The IP address or domain name of the LDAP server.

port (default: 389)

The port of the LDAP server on the host.

secure (default: false)

If true, Flitter Auth will attempt to bind to the LDAP server with ldaps.

bind_dn

Fully-qualified DN of the user that Flitter Auth will bind to the LDAP server with in order to query user information.

bind_secret

The password for the user specified by the bind_dn.

user_search_base

The base OU where users should be searched for.

user_filter

An LDAP query filter used to search for a user by username. This can contain any number of restrictions as it uses the standard LDAP filter syntax. The username entered by the user is interpolated into this filter in place of the %u string.

min_password_length (default: 8)

If registration is enabled, the minimum length of a password.

role_groups

An object mapping Flitter Auth roles to fully-qualified LDAP groups as they will appear in the user object's memberOf array. If a user has a particular LDAP group listed in this mapping, their Flitter user will automatically have the associated role.

attributes

An object mapping attributes on the user model flitter-auth/model/User~BaseUser to LDAP object attributes. This is used to build an instance of the user model once an LDAP user is authenticated.

attributes.group_membership

This is a special case of the attributes mapping. The associated LDAP field is the one Flitter Auth will use to determine group mappings.

registration (default: false)

Allow users to register with this LDAP provider. This means that new user accounts will be created on the LDAP server itself.

registration_merge_attributes

An object mapping LDAP object attributes to values used on insert. The same %u interpolator can be used for the registrant's username. The password is hashed automatically.