LDAP configuration

Advanced configuration of Allure TestOps

Integration with LDAP is quite tricky, and it’s a smart man’s way to peep into the settings you already have for some other system in your environment.

Prerequisites

  1. You need to download ldapsearch tool and read its manual.
  2. It’s better to have someone related to the configuration of LDAP in your company close to you.

Checking the work with LDAP

Before incorporating the LDAP settings to Allure TestOps configuration, we need to check these settings are, indeed, correct.

To do so, we need to send a request to LDAP and get a sensible response.

Query parameters

To verify the settings we need to have the following data:

  1. LDAP URI - this is the host where LDAP reside, e.g.ldap://localhost:389
  2. Base DN - it is the starting point to search for user authentication within a directory, e.g. dc=springframework,dc=org
  3. User DN - it is the distinguishable name of the user, we are going to use to send the requests towards LDAP, e.g. cn=admin,dc=springframework,dc=org, this User’s DN will be used by Allure TestOps server.
  4. User Pass - is is the password of the user from #3, say it will be allure.
  5. Search - it is the search query we’re going to send to LDAP server, say we’re going to find a user with the name bob, i.e. uid=bob.

Executing the search command

The following template is to be used to send the query:

ldapsearch -x -H "<LDAP URI>" -b "<Base DN>" -D "<User DN>" -w "<User Pass>" "<Search>"

Here is an example:

ldapsearch -x -H "ldap://localhost:389" -b "dc=springframework,dc=org" -D "cn=admin,dc=springframework,dc=org" -w "allure" "(uid=bob)"

Validating the response

If you received something like the following example, you have correct settings, and you can proceed to the configuration of Allure TestOps, otherwise you need to consult your LDAP admin to check if the parameters you have are correct.

# extended LDIF
#
# LDAPv3
# base <dc=springframework,dc=org> with scope subtree
# filter: (uid=bob)
# requesting: ALL
#

# bob, people, springframework.org
dn: uid=bob,ou=people,dc=springframework,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Bob Hamilton
sn: Hamilton
uid: bob
userPassword:: Ym9i
mail: [email protected]
givenName: Bob

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Configuration parameters of Allure TestOps

On the previous steps we’ve got the following parameters which we’re going to link to Allure TestOps’ configuration settings.

  1. Ldap URI - ldap://localhost:389
  2. Base DN - dc=springframework,dc=org
  3. User DN - cn=admin,dc=springframework,dc=org
  4. User Pass - allure
  5. Search - (uid=bob)

Modifying the search query

Search query from the item #5 need to be transformed as follows:

(uid=bob) >>> (uid={0})

This is required to search in LDAP by the username for the authorization procedure.

You can alter the query and use other parameter instead of uid. But for the example sake we’re going to use uid.

Deployment in Kubernetes

The settings for the integration with LDAP are to be added to the environment parameters of uaa service in values.yaml as follows:

uaa:
  env:
    secret:
      # security
      ALLURE_LOGIN_LDAP_ENABLED: "true"
      ALLURE_LOGIN_LDAP_URL: "ldap://localhost:389/dc=springframework,dc=org"
      ALLURE_LOGIN_LDAP_USERDN: "cn=admin,dc=springframework,dc=org"
      ALLURE_LOGIN_LDAP_PASSWORD: "allure"
	  ALLURE_LOGIN_LDAP_USERSEARCHFILTER: "(uid={0})"
	  ALLURE_LOGIN_LDAP_UIDATTRIBUTE: "uid"

Now, you need to update your Allure TestOps configuration as usual for Kubernetes installation using Helm’s commands.

Checking integration with LDAP is working

After Allure TestOps configuration is updated and all the PODs are up and running, you need to check if the integration is working:

Try to login to https://<allure>/login/ldap, where <allure> is the URL of your Allure TestOps server.

If the integration is working as expected, you need to instruct Allure TestOps to switch to LDAP as the primary way to authenticate the users.

uaa:
  env:
    open:
      ALLURE_LOGIN_PRIMARY: ldap

Now, you need to update your Allure TestOps configuration as usual for Kubernetes installation using Helm’s commands.

Deployment via docker-compose

For the deployment done via docker-compose you need to update docker-compose.yaml configuration file by adding the parameters to uaa service.

Updating of the configuration requires downtime to properly stop and run the application.

version: '3.4'

services:
  ...
  uaa:
    ...
    environment:
      ALLURE_LOGIN_LDAP_ENABLED: "true"
      ALLURE_LOGIN_LDAP_URL: "ldap://localhost:389/dc=springframework,dc=org"
      ALLURE_LOGIN_LDAP_USERDN: "cn=admin,dc=springframework,dc=org"
      ALLURE_LOGIN_LDAP_PASSWORD: "allure"
	    ALLURE_LOGIN_LDAP_USERSEARCHFILTER: "(uid={0})"
	    ALLURE_LOGIN_LDAP_UIDATTRIBUTE: "uid"

To update Allure TestOps for the usage of LDAP as identity provider you need to perform the same actions you do for updating Allure TestOps using docker-compose commands, , i.e. 1) down, 2) then start the application using up -d

Checking integration with LDAP is working

After Allure TestOps configuration is updated and all services are up and running, you need to check if the integration is working:

Try to login to https://<allure>/login/ldap, where <allure> is the URL of your Allure TestOps server.

If the integration is working as expected, you need to instruct Allure TestOps to switch to LDAP as the primary way to authenticate the users.

version: '3.4'

services:
  ...
  uaa:
    ...
    environment:
    <snip>
      ALLURE_LOGIN_PRIMARY: ldap
    <snip>  

Deployment via packages

To instruct Allure TestOps using LDAP as identity provider you need to update properties file /opt/allure-ee/uaa/conf/allure-uaa.properties with the following strings:

<snip>
allure.login.ldap.enabled=true
allure.login.ldap.url=ldap://localhost:389/dc=springframework,dc=org
allure.login.ldap.userDN=cn=admin,dc=springframework,dc=org
allure.login.ldap.password=allure
allure.login.ldap.userSearchFilter=(uid={0})
allure.login.ldap.uidAttribute=uid
<snip>

To apply settings you need to restart Allure TestOps’ uaa service.

Checking integration with LDAP is working

After Allure TestOps configuration is updated and all services are up and running, you need to check if the integration is working:

Try to login to https://<allure>/login/ldap, where <allure> is the URL of your Allure TestOps server.

If the integration is working as expected, you need to instruct Allure TestOps to switch to LDAP as the primary way to authenticate the users.

To do so, you need to add one more string to uaa properties file /opt/allure-ee/uaa/conf/allure-uaa.properties as follows:

<snip>
allure.login.primary=ldap
<snip>

Advanced stuff

You can also tune the work with LDAP a little bit more. Use these configuration parameters only if you’ve already successfully integrated LDAP with Allure TestOps.

Default role

This is Allure TestOps’ default user role that will be assigned to all new users logging in to Allure TestOps using LDAP.

By default the role of a user is ROLE_USER which requires a license. To control the licenses consumption you can assign different role to the users logging in with LDAP, e.g. ROLE_AUDITOR.

Kubernetes and docker-compose

To override the default role of a user, you need to add the following environment variable:

ALLURE_LOGIN_LDAP_DEFAULTROLE:ROLE_AUDITOR

Packages installation

To override the default role of a user, you need to add the following parameter:

allure.login.ldap.defaultRole=ROLE_AUDITOR

Password Attribute

Password attribute is the attribute containing the password fo the user returned from LDAP, if you refer to the example of data returned from LDAP above you will see, the attribute’s name (key if you want) is userPassword. It is used by default.

If you need to use different attribute then you need to add the following configuration parameter to LDAP configuration environment variables:

For Kubernetes and docker-compose:

``yaml ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE: userPassword


For the packages installation: 

```bash
userPassword:userPassword

Ignoring user atributes case

If your LDAP administrators really like to change names from [email protected] to [email protected] this could lead that these different user names will be treated by Allure TestOps as different while they are the same, To avoid this behaviour you can use the following parameter which needs to be added to uaa service configuration:

For the deployment via docker-compose or Kubernetes:

ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES: true

For the deployment with packages

allure.login.ldap.lowercaseUsernames = true

To avoid

DN pattern and user search filter should not be used together, this combination won’t work.

Full list of the parameters

Starting from 3.177.1 for LDAP configuration you need to use ALLURE_LOGIN_LDAP_ instead of LDAP_ used before.
The list of the configuration parameters described above is enough to provide the basic integration.

Docker-compose and Kubernetes installation

Environment variable Description Example
ALLURE_LOGIN_LDAP_ENABLED Is LDAP enabled? true
ALLURE_LOGIN_LDAP_REFERRAL Set the method to handle referrals. Default is ‘ignore’; setting this flag to ‘follow’ will enable referrals to be automatically followed. Note that this might require particular name server setup in order to work (the referred URLs will need to be automatically found using standard DNS resolution). follow
ALLURE_LOGIN_LDAP_URL URL of your LDAP server with base DN ldap://localhost:389/base_dn
ALLURE_LOGIN_LDAP_USERDN Set the user distinguished name (principal) to use for getting authenticated contexts. CN=Allure,OU=Users,DC=domain,DC=com
ALLURE_LOGIN_LDAP_PASSWORD the password (credentials) to use for getting authenticated contexts. your-password
ALLURE_LOGIN_LDAP_UIDATTRIBUTE Specifies the attribute name which contains the user name. Default is “uid”. uid
ALLURE_LOGIN_LDAP_USERDNPATTERNS allure.login.ldap.userDnPatterns If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN. It maps directly to the userDnPatterns property of AbstractLdapAuthenticator. The value is a specific pattern used to build the user’s DN, for example “uid={0},ou=people”. The key “{0}” must be present and will be substituted with the username.
ALLURE_LOGIN_LDAP_USERSEARCHBASE Search base for user searches. Defaults to "” ou=people
ALLURE_LOGIN_LDAP_USERSEARCHFILTER The LDAP filter used to search for users (optional). For example “(uid={0})". The substituted parameter is the user’s login name. (&(sAMAccountName={0})(objectClass=user))
ALLURE_LOGIN_LDAP_GROUPSEARCHBASE The search base for group membership searches. Defaults to “". ou=groups
ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER The LDAP filter to search for groups. Defaults to “(uniqueMember={0})". The substituted parameter is the DN of the user. (uniqueMember={0})
ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE Specifies the attribute name which contains the role name. Default is “cn”. cn
ALLURE_LOGIN_LDAP_DEFAULT_ROLE Default role in Allure TestOps assigned to new users. ROLE_AUDITOR or ROLE_USER or ROLE_ADMIN

Packages installation

Property Description Example
allure.login.ldap.enabled Is LDAP enabled? true
allure.login.ldap.referral Set the method to handle referrals. Default is ‘ignore’; setting this flag to ‘follow’ will enable referrals to be automatically followed. Note that this might require particular name server setup in order to work (the referred URLs will need to be automatically found using standard DNS resolution). follow
allure.login.ldap.url URL of your LDAP server with base DN ldap://localhost:389/base_dn
allure.login.ldap.userDn Set the user distinguished name (principal) to use for getting authenticated contexts. CN=Allure,OU=Users,DC=domain,DC=com
allure.login.ldap.password the password (credentials) to use for getting authenticated contexts. your-password
allure.login.ldap.uidAttribute Specifies the attribute name which contains the user name. Default is “uid”. uid
allure.login.ldap.userDnPatterns If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN. It maps directly to the userDnPatterns property of AbstractLdapAuthenticator. The value is a specific pattern used to build the user’s DN, for example “uid={0},ou=people”. The key “{0}” must be present and will be substituted with the username. uid={0},ou=people
allure.login.ldap.userSearchBase Search base for user searches. Defaults to "” ou=people
allure.login.ldap.userSearchFilter The LDAP filter used to search for users (optional). For example “(uid={0})". The substituted parameter is the user’s login name. (&(sAMAccountName={0})(objectClass=user))
allure.login.ldap.groupSearchBase The search base for group membership searches. Defaults to “". ou=groups
allure.login.ldap.groupSearchFilter The LDAP filter to search for groups. Defaults to “(uniqueMember={0})". The substituted parameter is the DN of the user. (uniqueMember={0})
allure.login.ldap.groupRoleAttribute Specifies the attribute name which contains the role name. Default is “cn”. cn
allure.login.ldap.defaultRole Default role in Allure TestOps assigned to new users. ROLE_AUDITOR or ROLE_USER or ROLE_ADMIN