Skip to main content

LDAP Integration

LDAP Integration

Overview

For user authentication could be used a company LDAP. In this case user authentication will be performed via LDAP. Administrator creates user with username matches from the LDAP.

The platform installation asks for the LDAP configuration during the procedure. It could be skipped during installation and changed after it.

Use LDAP configuration parameters in Control Server configuration to change the integration settings.

Configuration

ParameterDescriptionExamples
cs.ldap_urlLDAP connection URL with port and protocol. If this key is defined the LDAP Integration is on.

ldap://ad-ldap.org

ldaps://domino-ldap.org:636

cs.ldap_root_dnSearch base for user searches. The tree path, where persons are located.

CN=Users,DC=my,DC=org

o=org

cs.ldap_user_dn_patterns

Sets the pattern which will be used to supply a DN for the user.

The pattern should be the name relative to the root DN. The pattern argument {0} will contain the username.

cn={0}

uid={0}

mail={0}

cs.ldap_user_search_filter

Optional search object which can be used to locate a user when a simple DN match isn't sufficient.

The pattern should be the name relative to the root DN. The pattern argument {0} will contain the username. 

The filter expression used in the user search. This is an LDAP search filter (as defined in 'RFC 2254') with optional arguments. See the documentation for the search methods in DirContext for more information. In this case, the username is the only parameter. 

uid={0} - this would search for a username match on the uid attribute

mail={0}

sAMAccountName={0}

(&(objectClass=person)(sAMAccountName={0}))

(&(objectClass=person)(sn={0}))

cs.ldap_manager_dnLDAP technical access user account.

domain paplatform-bind-user

rpaplatform@rplaplatform.org

cs.ldap_manager_passwordLDAP technical access user account password.AnnddReww!234
cs.ldap_mail_attrAn LDAP person email attribute, to use in user email during platform user record creation. 

userPrincipalName

mail

cs.ldap_sn_attr

An LDAP person surname attribute, to use in user last name during platform user record creation.

sn
cs.ldap_fn_attr

An LDAP person name, to use in user name during platform user record creation.

givenName

givenname

cs.ldap_user_attr

An LDAP person attribute, to use in user username during platform user record creation.

sAMAccountName

mail

SSL 

If LDAP connection require SSL and self-signed certificate is used on LDAP server side. CA public certificate has to be added into control server trust store. It is automatically done during installation, but should be done manually after it.

Authentication flow

  1. If ldap_user_dn_patterns is defined, try to authenticate user directly. 
  2. If ldap_user_search_filter is defined, search using manager credential if found, try to authenticate located cn with given password.

Those two parameters (ldap_user_dn_patterns and ldap_user_search_filter) are mutually exclusive.

Switch on/off LDAP authentication 

The LDAP authentication is on if the If the cs.ldap_url parameter is exist in the configuration. All user created without LDAP will be authenticated via platform passwords, ever if the user with the same account exist in LDAP (f.e. admin).

The user created with LDAP enabled do not have passwords in platform and can not be authenticated when LDAP is switched off, but if the password ones set if switched on platform authentication.

Migrating existing local users to be authenticated externally

In a rare case of migrating existing local users to be authenticated externally, the following needs to be done in the Vault web application:

  • enable web access to the 'vault' docker application. The easiest way is to edit docker-compose.yaml and add the following port forwarding:
docker-compose.yaml
...
	vault:
	...
	ports:
	- "8200:8200"
...
  • run docker-compose up vault -d
  • open vault web application using the rpaplatform address with the port 8200
  • find the "token" field value in the '/opt/rpaplatform/data/vaultroot/vault_root.config' file
  • login with the token
  • open 'users' secret engine

  • under users find the user to be migrated
  • delete the user vault entry

  • run docker-compose up -d to unseal the vault

Alternatively Vault command line can be used to delete a user from the vault - from 'vault' docker container bash console.

Migrating existing LDAP users to be authenticated locally

In a rare case of migrating existing LDAP users to be authenticated locally, the reverse actions are required:

  • login to the 'vault' using web application or command line
  • under 'users', create a user entry with the LDAP user name and password
  • run docker-compose up -d to unseal the vault

Authorization

There are two authorization modes available when LDAP authentication is enabled:

  • platform does authorization - this is default mode when you just enabled LDAP authentication
  • LDAP does authorization - this mode should be explicitly enabled by adding extra CS configuration parameter cs.ldap_autorisation_enabled = true

In the second mode for each authenticated LDAP user LDAP roles will be extracted and translated into platform authorization groups.

The default strategy for obtaining user role information from the directory.

It obtains roles by performing a search for "groups" the user is a member of.

A typical group search scenario would be where each group/role is specified using the groupOfNames (or groupOfUniqueNames) LDAP objectClass and the user's DN is listed in the member (or uniqueMember) attribute to indicate that they should be assigned that role. The following LDIF sample has the groups stored under the DN ou=groups,dc=springframework,dc=org and a group called"developers" with "ben" and "luke" as members: 


 dn: ou=groups,dc=springframework,dc=org
 objectClass: top
 objectClass: organizationalUnit
 ou: groups

 dn: cn=developers,ou=groups,dc=springframework,dc=org
 objectClass: groupOfNames
 objectClass: top
 cn: developers
 description: Spring Security Developers
 member: uid=ben,ou=people,dc=springframework,dc=org
 member: uid=luke,ou=people,dc=springframework,dc=org
 ou: developer
 

The group search is performed within a DN specified by the cs.ldap_group_search_base parameter, which should be relative to the root DN of its ContextSource. The filter used in the search is defined by the cs.ldap_group_search_filter property, with the filter argument {0} being the full DN of the user. You can also optionally use the parameter {1}, which will be substituted with the username. You can also specify which attribute defines the rolename by setting the cs.ldap_group_role_attr property (the default is "cn"). 

A search for roles for user "uid=ben,ou=people,dc=springframework,dc=org" would return the single granted authority "developer". 
The single-level search is performed by default. Setting the cs.ldap_group_search_subtree to true will enable a search of the entire subtree under cs.ldap_group_search_base.


Setting up LDAP role mappings for platform groups and priorities for default user group calculation.

To setup LDAP role mappings for platform groups and priorities for default user group calculation please use Group Management  CS UI.

Each group has the following related fields:

  • External Roles - a list of strings that will be used to map granted LDAP roles of an LDAP user to the group. Please note that the role is case sensitive.
  • Priority - a positive integer that is used to calculate LDAP user default group from all granted groups - bigger priority means higher chance for this group to be chosen as default.






Table of contents