LDAP

When using an LDAP datasource, the hostname and port must be configured, as well as an indication whether the connection is an ldaps connection or a regular ldap connection. When it’s ldaps, there are TLS-settings available to specify acceptable server certificates, as well as reference they key material that can be used for client authentication. It is possible to indicate that an LDAP server is Microsoft Active Directory by setting the ldap-server-type configuration option to active-directory.

Note

When configuring a datasource as active-directory, there are specific settings that will be applied. For one, an Active Directory schema will be used to find and store account-related attributes (i.e. sAMAccountName is used to represent an accountId, userAccountControl is used to enable or disable accounts, users are created with user objectClass, etc.). Also, when password modification is enabled, the strategy to store passwords will use a specific way that Active Directory requires (i.e. target the unicodePwd-attribute with the correct encoding).

By default, LDAP connections are managed in a connection pool. The connection pool behaviour can be tweaked to adjust for the environment and usage of the server.

Connections to the LDAP datasource can be based on anonymous binding, or alternatively use a client-id and client-secret to specify the administrative account to use for binding to the LDAP server.

Hint

Use the full qualified directory entry name to indicate the client_id, i.e. cn=Directory Admin,dc=curity,dc=se.

To search the directory, a default root must be specified that is used to base searches on. Each search is then performed using a sub scope. You can change the search scope in the configuration . Please see the configuration of LDAP for more on the available options.

The LDAP datasource can be used for different purposes. It applies default settings based on the server-type or the server-type’s schema. There is one filter that needs to be explicitly configured though, which is the search-filter-account-id query. This filter is used to find an account entry, based on the configured default-root of the directory tree. If there are no special conditions, this setting could be configured like (uid={}).

Note that an attribute provider can override the search-filter-account-id by explicitly configuring the search-filter in the account section of the data-source configuration.

Search filters are standard LDAP search filters, which are specified through RFC 4515. Each search-filter can take an argument, which is documented along the configuration option in the reference. This argument is substituted for the {}-placeholder of the configured search-filter. Examples are (uid={}), (&(phoneNumber={})(objectClass=inetOrgPerson)), etc. Note that you can write a filter without brackets, if it contains a single predicate, for example uid={} is a valid search-filter and is the same as (uid={}).

When a search query for an account or for an attribute-provider returns many attributes that are not needed or used, it is possible to configure a whitelist of attributes that is sent with the request to the LDAP server. The LDAP server can use this whitelist when sending back a response. This whitelist can be independently configured for an account provider as well as for an attribute provider, by adding adding the attribute names to the ldap-attribute-to-fetch setting. If no attribute names are configured, the LDAP server is expected to return all attributes as part of the response.

LDAP for Account- and Credential Data Access

In case the LDAP datasource is used to access account-information (i.e. see Account Manager), or as authentication backend (i.e. through a Credential Manager), the default configuration only requires configuring search-filter-account-id. When needed, it is possible to override default search-filters for account-related queries that are based on email-address or phone-number.

The account-id-attribute is an optional configuration setting that you can use to specifically set the attribute that represents the Account Identifier, the unique id of the account. In case this is not configured, the value of the EntryDN is used for this.

Account Status

Each account has a status that indicates whether an account is enabled or not. One place where this is used, is through the self service registration procedure, which can enforce a workflow where an account needs to be activated through email or phone number verification.

In case of a generic ldap-server-type, the InetOrgPerson schema is used. This does not define default attributes for holding this property, so an existing attribute is “repurposed” to store this information. By default, the audio attribute is used for this. If this collides somehow, it is possible to configure an alternative LDAP attribute for this purpose, by setting the active-state-attribute value in the account-section of the LDAP datasource configuration.

In case of Active Directory however, there is exists an attribute to manage account status. The userAccountControl attribute holds multiple flags of the user account. Curity Identity Server will use this attribute to test whether an account is active or not (by testing the enabled flag). In case an account is activated (i.e. an e-mail address is confirmed, etc.), the AccountManager will overwrite the userAccountControl value such that it represents an enabled and normal user.

Phone number and email

The mobile phone number is used when authenticating using the SMS authenticator. The default location used to retrieve the number is telephoneNumber. If that is not where the mobile phone number is stored this can be updated in the config.

The same exists for the email. If it is not stored in the regular mail location, it also needs to be remapped if the operations involving emails, such as reset password, activate account and login using email hyperlink are to work.

Example of remapping email and phone:

Listing 46 Active Directory LDAP data-source with email and phone remapped
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    <data-source>
      <id>ActiveDirectoryUserstore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>false</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <ldap-server-type>active-directory</ldap-server-type>
        <default-root>ou=Users,dc=curity,dc=se</default-root>
        <account>
          <search-filter-account-id>sAMAccountName={}</search-filter-account-id>
          <ldap-attribute-to-fetch>name</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>email</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>mobile</ldap-attribute-to-fetch>
          <mobile-phone-number-attribute>mobile</mobile-phone-number-attribute>
          <email-attribute>email</email-attribute>
        </account>
      </ldap>
    </data-source>

Credential Management

An LDAP datasource can also be used to both verify as well as manager credentials. The procedure of verifying credentials, authentication, is based on a two step process. The first step will take a username, and try to find the EntryDN for that username (using the search-filter-account-id query). The second step will perform a bind-operation, that uses the EntryDN that was found in the first step, and a provided password. When both steps succeed, authentication will be successful.

Apart from using LDAP to verify credentials, it is also possible to manage password. This is done through either an attribute replacement strategy or a modify password strategy. Which one to choose, depends completely on the particular LDAP server that is used. In case the ldap-server-type is set to active-directory, the strategy is to update the unicodePwd attribute using the encoding that is used by Active Directory, no further configuration is necessary. If ldap-server-type is generic, the default option is to try the modify password strategy. Because this is using the ModifyPassword LDAPv3 extended operation, not every LDAP server will support this. If that’s the case, the credentials section of the LDAP datasource allows you to explicitly indicate that the attribute replacement strategy must be used. The format in which the password attribute must be encoded, can be set through the password-encoding setting. The attribute will always be userPassword, which follows from the InetOrgPerson schema.

Note

The password-encoding settings that are available, are commonly used by LDAP server implementations. However, there is no guarantee that your LDAP server supports anything other than plaintext. Please see the particular LDAP server documentation to learn more about what your LDAP server supports.

Example configuration

The following configuration defines a generic LDAP data source with a whitelist for the account attributes that are retrieved for an Account Manager.

Listing 47 Generic LDAP data-source with attribute whitelist configuration example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
    <data-source>
      <id>LdapUserstore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>6636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>true</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <default-root>ou=People,dc=curity,dc=se</default-root>
        <account>
          <search-filter-account-id>uid={}</search-filter-account-id>
          <ldap-attribute-to-fetch>cn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>sn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>mail</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>telephoneNumber</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>description</ldap-attribute-to-fetch>
        </account>
      </ldap>
    </data-source>

The following configuration defines an Active Directory LDAP data source with a whitelist for the account attributes that are retrieved for an Account Manager. If this datasource is also used for storing credentials, the unicodePwd attribute is used on entries found in ou=Users,dc=curity,dc=se.

Listing 48 Active Directory LDAP data-source with attribute whitelist configuration example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
    <data-source>
      <id>ActiveDirectoryUserstore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>true</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <ldap-server-type>active-directory</ldap-server-type>
        <default-root>ou=Users,dc=curity,dc=se</default-root>
        <account>
          <search-filter-account-id>sAMAccountName={}</search-filter-account-id>
          <ldap-attribute-to-fetch>name</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>mail</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>telephoneNumber</ldap-attribute-to-fetch>
        </account>
      </ldap>
    </data-source>

The following configuration defines a generic LDAP data source, and includes specific configuration that defines that when storing a password, it should be saved to userPassword, as plaintext value.

Listing 49 Generic LDAP data-source with credential management configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
    <data-source>
      <id>LdapUserstore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>6636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>true</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <default-root>ou=People,dc=curity,dc=se</default-root>
        <account>
          <search-filter-account-id>uid={}</search-filter-account-id>
          <ldap-attribute-to-fetch>cn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>sn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>mail</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>telephoneNumber</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>description</ldap-attribute-to-fetch>
        </account>
        <credentials>
          <use-attribute-replacement>
            <password-encoding>plaintext</password-encoding>
          </use-attribute-replacement>
        </credentials>
      </ldap>
    </data-source>

LDAP for Attribute Data Access

The LDAP datasource can be used as Attribute Provider. By default, all the attributes that the LDAP server returns as part of executing the search-filter-account-id query will be made available. It is however possible for attribute providers to override both that query as well as the whitelist of attributes to request, The following example does just that.

Example configuration

Listing 50 Generic LDAP data-source with attribute configuration override example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    <data-source>
      <id>LdapAttributeStore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>6636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>true</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <default-root>ou=Attributes,dc=curity,dc=se</default-root>
        <search-scope>sub</search-scope>
        <account>
          <search-filter-account-id>uid={}</search-filter-account-id>
        </account>
        <attributes>
          <search-filter>(&amp;(uid={})(memberof=CN=employees,OU=groups,dc=curity,dc=se))</search-filter>
          <ldap-attribute-to-fetch>carLicense</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>roomNumber</ldap-attribute-to-fetch>
        </attributes>
      </ldap>
    </data-source>

Use-case for configuring an LDAP backend for HTML Forms authenticator

One way to use the LDAP backend is for user authentication. To achieve this, multiple parts of the system need to be configured to work together. The following diagram presents a high level perspective on the resulting system.

../../_images/ldap-for-htmlform-authentication-overview.png

To configure the whole system, use the following order:

  1. Setup the LDAP datasource
  2. Create the Credential Manager for the LDAP datasource
  3. Create an Account Manager with the Credential Manager
  4. Create the HTML Form authenticator, that uses the Account Manager
  5. Enable the authenticator for Service Providers (or Clients)

Setup the LDAP datasource

The way to setup the LDAP datasource is discussed in the LDAP section above. You will need some settings regarding how to connect to the LDAP backend, as well as the location of the users in the directory.

Example configuration in /facilities/data-sources :

Listing 51 LDAP data-source configuration for HTML forms authenticator using LDAP use-case
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    <data-source>
      <id>LdapUserstore</id>
      <ldap xmlns="https://curity.se/ns/conf/data-access/ldap">
        <hostname>ldap.curity.se</hostname>
        <port>6636</port>
        <ldaps>true</ldaps>
        <tls>
          <disable-hostname-verification>true</disable-hostname-verification>
          <use-truststore>true</use-truststore>
        </tls>
        <client-id>cn=Directory Manager,ou=admins,dc=curity,dc=se</client-id>
        <client-secret>password</client-secret>
        <default-root>ou=People,dc=curity,dc=se</default-root>
        <search-scope>sub</search-scope>
        <account>
          <search-filter-account-id>uid={}</search-filter-account-id>
          <ldap-attribute-to-fetch>cn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>sn</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>mail</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>telephoneNumber</ldap-attribute-to-fetch>
          <ldap-attribute-to-fetch>description</ldap-attribute-to-fetch>
        </account>
      </ldap>
    </data-source>

Create the Credential Manager for the LDAP datasource

A Credential Manager is always configured with a data-source. For more on configuring a Credential Manager, see Credential-manager.

Example configuration in /processing/credential-managers :

Listing 52 Credential Manager configuration for HTML forms authenticator using LDAP use-case
1
2
3
4
5
6
    <credential-manager>
      <id>LdapCredentialManager</id>
      <data-source-backed>
        <data-source-id>LdapUserstore</data-source-id>
      </data-source-backed>
    </credential-manager>

Create an Account Manager with the Credential Manager

An Account Manager binds together account management functionality, of which the Credential Manager is one part. More on configuring Account Managers can be read in section Account Manager.

Account Managers are configured inside an Authentication-profile.

Example configuration in /profiles/profile/*authentication-profile*/settings/authentication-service/account-managers :

Listing 53 Account Manager configuration for HTML forms authenticator using LDAP use-case
1
2
3
4
5
6
7
8
    <account-manager>
          <id>LdapAccountManager</id>
          <credential-manager>LdapCredentialManager</credential-manager>
          <account-data-source>LdapUserstore</account-data-source>
          <enable-registration>
                <account-verification-method>no-verification</account-verification-method>
          </enable-registration>
    </account-manager>

Create the HTML Form authenticator, that uses the Account Manager

Now it’s time to configure the HTML Form authenticator. There is nothing special LDAP, apart from pointing the authenticator’s Account Manager to the right one. More in the section HTML Forms authenticator.

Example configuration in /profiles/profile/*authentication-profile*/settings/authentication-service/authenticators :

Listing 54 HTML Forms authenticator configuration for HTML forms authenticator using LDAP use-case
1
2
3
4
5
6
7
    <authenticator>
          <id>htmlLdap</id>
          <description>A standard LDAP backed authenticator</description>
          <html-form xmlns="https://curity.se/ns/conf/authenticators/html-form">
                <account-manager>LdapAccountManager</account-manager>
          </html-form>
    </authenticator>

Enable the authenticator for Service Providers (or Clients)

Only when an authenticator is configured for a Service Provider (or Client), it will be made available. More on configuring Service Providers in the section Service Providers.

Example configuration in /profiles/profile/*authentication-profile*/settings/authentication-service/service-providers :

Listing 55 Service Provider configuration for HTML forms authenticator using LDAP use-case
1
2
3
4
5
6
7
    <service-provider>
          <id>se.curity.app</id>
          <allowed-authenticators>htmlLdap</allowed-authenticators>
          <context-info>Log into se.curity.app</context-info>
          <target-url>https://se.curity-app.com/cb</target-url>
          <template-area>html-only</template-area>
    </service-provider>