Enable LDAP Login

Prerequisites

If you want to connect to an LDAP server with non-public certificates, follow Add Trusted CA Certificates.

Basic configuration

LDAP backend is defined in the ldapAuthDataSources: subsection of the usernamePasswordAuthBackends: section in the auth/auth/auth.yml file. First, you have to set up the basic parameters of your LDAP source, starting with its name—that can be whatever you like (myLDAP in this sample case)—and then configuring the connection as in the example below:

auth.yml

    ldapAuthDataSources:
      myLDAP:
        host: ldap.example.com
        port: 10636
        useLdaps: true
        useStartTls: false
        trustAll: false

The following table explains the parameters:

Parameter	Value
`host`	Address of your LDAP server
`port`	Port number of your LDAP server
`useLdaps`	Whether to use SSL on the socket layer (conflicts with `startTls` below)
`useStartTls`	Whether to use the `startTLS` command (conflicts with `useLdaps` above)
`trustAll`	Skip verification of the SSL server certificate (warning: do NOT do this on production!)

Authentication

The next step involves user authentication in your LDAP server. You can use a direct distinguished name (DN) of a user who is being authenticated (if you already know what the DN of a user looks like) or query LDAP for the DN. Either way, you have to specify only one method. This is done within the authentication: subsection of your LDAP server configuration.

Direct DN

If you want to use a direct DN of a user, you just set the withUserDn.userDnPattern attribute to a pattern which will allow to deduct a DN from a login username string, e.g., "uid={0},ou=users,dc=company,dc=com", where {0} will be substituted with a username:

auth.yml

        authentication:
          withUserDn:
            userDnPattern: "uid={0},ou=users,dc=example,dc=com"

DN query

When a DN of a user is not known, you can search the LDAP directory for the user entry using a so-called technical user for authentication. Once the user entry is found, their DN is used to authenticate with the provided credentials. A sample configuration of a DN query is as follows:

auth.yml

        authentication:
          withQueryDn:
            bindDn: "uid=xcc-dev,ou=users,dc=example,dc=com"
            bindPassword: "LDAP_bind_pw"
            userBase: "ou=users,dc=example,dc=com"
            userSearch: "(uid={0})"

The table below explains the parameters:

Parameter	Value
`bindDn`	The bind DN of the technical user that will be used to fetch the user information from the directory; both user and password can be omitted if the directory supports unauthenticated access
`bindPassword`	Password for the technical user
`userBase`	Specifies the subtree in the directory where user information is stored
`userSearch`	Template for user search query, e.g., - for OpenLDAP: `"(cn={0})"` - for Microsoft Active Directory: `"(sAMAccountName={0})"` where `{0}` will be replaced with the login username

Authorization

After a successful authentication, a user has to be authorized: their roles are read from the LDAP backend. In the authorization.query: subsection, you can configure the parameters of the role search using a nested search within a subtree of a directory as in the sample configuration below:

auth.yml

        authorization:
          query:
            roleBase: "ou=groups,dc=example,dc=com"
            roleSearch: "(member={0})"
            nestedRoleDepth: 2
            groupRoleAttribute: dn

The parameters are explained in the table below:

Parameter	Value
`roleBase`	Base of the role subtree
`roleSearch`	Filter to search for roles where - `{0}` is substituted with the DN of the user entry found with the prior user search - `{1}` is substituted with the username
`nestedRoleDepth`	Integer that specifies how many times to search the directory for nested roles (set to `0` to disable resolution of nested roles)
`groupRoleAttribute`	The role name to be used as an input for the `roleMapping` attribute; if this is not set, the DN of the role entry is used

Attribute mapping

In the next step you have to map (assign) attributes from the LDAP user entries to the user model in xorlab Security Platform. The mapping is described using Spring expression language and is configured under the attributeMapping: subsection. You can use these methods:

attr('<name>'): retrieve the attribute with the '<name>' name from attributes in the source authorization system
replace(<string or list of strings>, '<pattern>', 'replace'): replace every occurrence of '<pattern>' with 'replace' in an input string or a list of input strings
azureAdEmails(): read all email addresses from the Azure Active Directory proxyAddresses attribute.

Literal values have to be quoted, e.g., key: 'literal value'. A sample configuration for attribute mapping, which simply retrieves attributes from the auth system, would look like this:

auth.yml

        attributeMapping:
          userName: "attr('uid')"
          displayName: "attr('cn')"
          emails: "attr('mail')"

Available attributes are explained in the table below:

Attribute	Description
`userName`	An attribute mapping for the username. The result of this mapping will be put into the `subject` attribute of the token issued to the consuming services
`displayName`	An attribute mapping for the display name of the user. It is optional and could be used by consuming services in places where a more descriptive name of the user is appreciated
`emails`	A mapping for the list of emails associated with the user. Consuming services might use this list to associate the user with a certain pool of email messages
`tenant`	Only required for multi-tenancy deployments: Make sure the value of the `tenant` attribute correspond to the `name` defined in the `guarded_tenants.yml`.

Role mapping

The last step is to configure role mapping. You must map all roles served by the LDAP directory to the corresponding xorlab roles under the roleMapping: subsection. Roles that are not mapped are ignored by default. Multiple xorlab roles can be mapped to the same LDAP role, e.g., xcc_login → company1-group1, xcc_admin → company1-group1.

The role mapping is case sensitive, therefore make sure that you specify the role names according to what is served by the LDAP directory.

A sample role mapping configuration is shown below:

auth.yml

        roleMapping:
          xcc_login: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_analyst: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_admin: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
          xcc_insights: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]

If the LDAP directory already serves roles compatible with xorlab (see Built-in Roles), you can also specify a “pass-through” role-mapping mode using roleMappingMode: PASS_THROUGH.

Please be aware that in the pass-through role-mapping mode, all roles served by the LDAP directory are added to the xorlab authorization context. If this context is becoming too large, i.e., too many irrelevant roles are added, then it might lead to errors and users being unable to access XCC. Therefore, it is advisable to only map the roles that are relevant to xorlab.

A sample role mapping configuration using the pass-through mode:

auth.yml

        roleMappingMode: PASS_THROUGH
        roleMapping:
          # You can still define a role mapping in pass-through mode
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]

Activate the configuration

After updating auth/auth/auth.yml, click Publish. The authentication configuration becomes active within about one minute.

Multi-Tenancy

The setup on this page applies unchanged in a multi-tenant deployment. Two things are added on top: a tenant entry in the Attribute mapping that matches the tenant name in guarded_tenants.yml, and a tenant-restricted user role in the Role mapping.

Enable Tenant Login

Complete per-tenant LDAP example, and the other login options available to tenants.

Example configuration

The final configuration for an LDAP backend should look like this:

auth.yml

tokenSigningKey: "xyz"

enabledAuthBackends:
  - usernamePassword

usernamePasswordAuthBackends:
  usernamePassword:
    ldapAuthDataSources:
      myLDAP:
        host: ldap.example.com
        port: 10636
        authentication:
          withQueryDn:
            bindDn: "uid=xcc-dev,ou=users,dc=example,dc=com"
            bindPassword: "LDAP_bind_pw"
            userBase: "ou=users,dc=example,dc=com"
            userSearch: "(uid={0})"
        authorization:
          query:
            roleBase: "ou=groups,dc=example,dc=com"
            roleSearch: "(member={0})"
            nestedRoleDepth: 2
        attributeMapping:
          userName: "attr('uid')"
          displayName: "attr('cn')"
          emails: "attr('mail')"
        roleMapping:
          xcc_login: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_analyst: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_admin: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]
          xcc_insights: [ "cn=dev_xcc_login,ou=groups,dc=example,dc=com" ]
          xcc_monitor: [ "cn=dev_xcc_soc_admin,ou=groups,dc=example,dc=com" ]

​Basic configuration

​Authentication

​Direct DN

​DN query

​Authorization

​Attribute mapping

​Role mapping

​Activate the configuration

​Multi-Tenancy

Enable Tenant Login

​Example configuration

Basic configuration

Authentication

Direct DN

DN query

Authorization

Attribute mapping

Role mapping

Activate the configuration

Multi-Tenancy

Example configuration