Authentication via LDAP

LDAP authentication is available only for the server version of Allure TestOps.

LDAP is a popular protocol for searching user accounts on a special server, such as Active Directory or OpenLDAP. If you configure Allure TestOps to use an LDAP server, the users will be able to use their existing credentials without the need to register new accounts in Allure TestOps itself.

Please note that configuring integration with an LDAP server is a complex process. The protocol supports a wide range of queries and parameter names, leading to significant differences between servers. As a result, there is no universal configuration example.

Before proceeding with the setup, ensure you have a good understanding of your LDAP server's parameters or consult a colleague familiar with its configuration.

How it works

Allure TestOps connects to the LDAP server using a service account.
On the sign-in page, a user enters their credentials: a username (or email address) and password.

Depending on the configuration, Allure TestOps may automatically convert the username to lowercase before proceeding.
Allure TestOps sends an LDAP query to check if an account exists with the provided credentials.

Depending on the configuration, either a search filter or DN patterns will be used for this query. Please note that these two options are mutually exclusive, therefore you can't configure them at the same time.
If the account is found, the LDAP server returns the user information to Allure TestOps, including the unique identifier (UID) and the groups the user belongs to. Then Allure TestOps searches for an internal account that matches the specified UID. If the account does not exist, Allure TestOps creates it.

Depending on the configuration, Allure TestOps may update user information with data from the LDAP server (name, email, roles and avatar).
After successful authentication, Allure TestOps redirects the user to the page they wanted to visit or to the main page.

Configuration

We strongly recommend the following approach for configuring LDAP authentication:

Configure the basic functionality — your test user must be able to sign in to Allure TestOps.

If required, enable role synchronization with LDAP groups to complete the configuration.

Do not enable group synchronization until you have confirmed that a user can sign in to the Allure TestOps instance.

Search base and filter

A mandatory step in configuring LDAP integration is specifying the account search parameters: the search base (Base DN) and the search filter. You can clarify the values of these parameters with your LDAP server administrator or by using the ldapsearch utility (see below).

Search base usually matches the domain name of the server with an added organizational unit to narrow the search scope (for example, People to search for users). The resulting value typically looks like this:

ou=People,dc=example,dc=org

The search filter is used to select the LDAP entries needed by the application. Allure TestOps uses the user unique identifier that is granted access (usually the uid attribute). The value for search filter may look like this:

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

Final set of parameters for searching users will look like the following:

auth:
  ldap:
    ...
    user:
      searchBase: ou=People,dc=example,dc=org
      searchFilter: (&(objectClass=person)(uid={0}))

To check the attribute names on your LDAP server, you can use the ldapsearch utility:

ldapsearch -x -H <URL> -b <Base DN> -D <Bind DN> -w <Password> <Filter>

where:

URL — URL of your LDAP server (for example, ldap://ldap.example.org:389);
Base DN — search base (for example, dc=example,dc=org);
Bind DN — distinguished name of a user who is allowed to search the base DN (for example, cn=admin,dc=example,dc=org);
Password — password of the user who is allowed to search the base DN;
Filter — search filter. For example, to find a user with a common name (cn) Doe, you can use the filter (cn=*Doe*).

Example:

ldapsearch -x -H "ldap://ldap.example.org:389" -b "dc=example,dc=org" -D "cn=admin,dc=example,dc=org" -w "password" "(cn=*Doe*)"

After running the command, you should see output similar to this:

dn: cn=John Doe,ou=People,dc=example,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: person
cn: John Doe
givenName: John
sn: Doe
mail: [email protected]
uid: john

Based on this result, you can obtain the values for the search parameters:

dn: cn=John Doe,ou=People,dc=example,dc=org,

For the user search base in configuration files, specify ou=People,dc=example,dc=org.
objectClass: person and uid: john.

User accounts have the objectClass attribute with the value person, and the unique identifier is stored in the uid attribute. Therefore, you need to set the search filter parameter to (&(objectClass=person)(uid={0})).

Automatic role assignment

After receiving user information from the LDAP server, Allure TestOps creates a new user account and assigns it the default role specified in the configuration file. We recommend using the "Guest" role as the default. Guest accounts do not contribute to the total user count under your license, minimizing the risk of exceeding the license limit. You can change the role of a user at any time in the Administration section.

auth:
  defaultRole: ROLE_GUEST

Additionally, you can configure automatic role assignment for users. When enabled, Allure TestOps will assign roles to users according to their LDAP groups. To enable it, you need to configure LDAP group search parameters (similar to user search parameters before) and specify the names of the groups that will be used for role assignment.

Group search base and filter

To configure LDAP group search parameters:

Specify the organizational unit that is used for groups in your LDAP server (for example, Groups).

Example search base value: ou=Groups,dc=example,dc=org.
Find out and specify the attribute that is used to store user identifiers in a group (for example, memberUid).

Example search filter value: memberUid={1}.

Please note that memberUid is an example. In your implementation, this parameter is likely to have a different name.

Final set of parameters for searching groups will look like the following:

auth:
  ldap:
    ...
    group:
      searchBase: ou=Groups,dc=example,dc=org
      searchFilter: memberUid={1}

To check the attribute names on your LDAP server, you can use the ldapsearch utility:

ldapsearch -x -H <URL> -b <Base DN> -D <Bind DN> -w <Password> <Filter>

where:

URL — URL of your LDAP server (for example, ldap://ldap.example.org:389);
Base DN — search base (for example, dc=example,dc=org);
Bind DN — distinguished name of a user who is allowed to search the base DN (for example, cn=admin,dc=example,dc=org);
Password — password of the user who is allowed to search the base DN;
Filter — search filter. For example, to find a group with a common name (cn) admins, you can use the filter (cn=admins).

Example:

ldapsearch -x -H "ldap://ldap.example.org:389" -b "dc=example,dc=org" -D "cn=admin,dc=example,dc=org" -w "password" "(cn=admins)"

After running the command, you should see output similar to this:

dn: cn=admins,ou=Groups,dc=example,dc=org
objectClass: posixGroup
objectClass: top
cn: admins
memberUid: admin
memberUid: john

Based on this result, you can obtain the values for the search parameters:

dn: cn=admins,ou=Groups,dc=example,dc=org,

In the configuration files, specify ou=Groups,dc=example,dc=org as the base for group search.
memberUid: john.

Identifiers of the users in a group are stored in the memberUid attribute. Because of this, you need to set the search filter parameter to memberUid={1}.

Matching LDAP groups to Allure TestOps roles

After configuring the group search parameters, you need to specify the LDAP groups that will be used for automatic role assignment. To do this, list their names, separated by commas, in the following parameters of the configuration file:

# LDAP groups that correspond to the "User" role in Allure TestOps
userGroupName: testops_users1,testops_users2
# LDAP groups that correspond to the "Admin" role in Allure TestOps
adminGroupName: testops_admins

Only after you have verified all parameters we recommend enabling automatic role assignment. To do this, set the syncRoles parameter to true:

auth:
  ldap:
    ...
    syncRoles: true

Editing configuration files

Examples

auth:
  primary: ldap
  defaultRole: ROLE_GUEST
  ldap:
    enabled: false
    auth:
      user: user
      pass: SecretPaSSw0rd
    referral: follow
    url: ldap://ldap.example.org:389
    usernamesToLowercase: false
    passwordAttribute: userPassword
    user:
      dnPatterns: ""
      searchBase: ou=People,dc=example,dc=org
      searchFilter: (&(objectClass=person)(uid={0}))
    syncRoles: false
    uidAttribute: uid
    group:
      searchBase: ou=Groups,dc=example,dc=org
      searchFilter: memberUid={1}
      roleAttribute: cn
    userGroupName: testops_users
    adminGroupName: testops_admins

LDAP_URL="ldaps://ldap.example.org:636"
LDAP_USER_SEARCH_BASE="ou=People,dc=example,dc=org"
LDAP_USER_SEARCH_FILTER="(&(objectClass=person)(uid={0}))"

LDAP_SYNC_ROLES=false
LDAP_GROUP_SEARCH_BASE="ou=Groups,dc=example,dc=org"
LDAP_GROUP_SEARCH_FILTER="memberUid={1}"
LDAP_GROUP_ROLE_ATTRIBUTE=cn
LDAP_UID_ATTRIBUTE=uid

LDAP_MAPPING_ROLE_USERS=atousers,every_user_is_user
LDAP_MAPPING_ROLE_ADMINS=atoadmins,every_user_is_admin

# Default role. Can be ROLE_GUEST, ROLE_USER, or ROLE_ADMIN
LDAP_DEFAULT_ROLE=ROLE_GUEST

LDAP_LOGIN_SA="cn=admin,dc=example,dc=org"
LDAP_LOGIN_SA_PASS=ServiceAccountPassword

ALLURE_LOGIN_PRIMARY=ldap
ALLURE_LOGIN_LDAP_ENABLED='true'
ALLURE_LOGIN_LDAP_REFERRAL=follow
ALLURE_LOGIN_LDAP_URL=ldap://ldap.url.here:port
ALLURE_LOGIN_LDAP_USERSEARCHBASE="ou=People,dc=example,dc=org"
ALLURE_LOGIN_LDAP_USERSEARCHFILTER="(&(objectClass=person)(uid={0}))"
# ALLURE_LOGIN_LDAP_USERDNPATTERNS = Do not use with ALLURE_LOGIN_LDAP_USERSEARCHFILTER
ALLURE_LOGIN_LDAP_DEFAULTROLE=${LDAP_DEFAULT_ROLE}
ALLURE_LOGIN_LDAP_UIDATTRIBUTE=uid
ALLURE_LOGIN_LDAP_SYNCROLES='true'
# The following parameters must be set if ALLURE_LOGIN_LDAP_SYNCROLES is 'true'
ALLURE_LOGIN_LDAP_GROUPSEARCHBASE="ou=Groups,dc=example,dc=org"
ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER="memberUid={1}"
ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE=cn

ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS=group_with_ato_users,every_user_is_user
ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS=group_with_ato_admins,every_user_is_admin
# LDAP service account credentials
ALLURE_LOGIN_LDAP_USERDN="cn=admin,dc=example,dc=org"
ALLURE_LOGIN_LDAP_PASSWORD='ServiceAccountPasswordHere'
# Additional parameters, can be disabled by default
# ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES=true
# ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE=userPassword

Testing with ldapsearch

Before restarting Allure TestOps with the new parameters, we strongly recommend to check them manually with the ldapsearch utility. The utility may be part of the ldap-utils or ldap-clients package, depending on the operating system.

Once the utility is installed, try to find a user on the LDAP server by their UID:

ldapsearch \
    -H 'ldap://ldap.example.com:389' \
    -D 'cn=admin,dc=example,dc=com' \
    -w 'SecretPa$$w0rd' \
    -b 'dc=example,dc=com' \
    '(&(objectClass=person)(uid=john))'

The arguments correspond to the following configuration parameters:

Using LDAP together with standard authentication

Typically, when a company configures LDAP authentication for Allure TestOps, the LDAP server is considered the primary source of user account data, and LDAP is set as the primary authentication method. However, there may be cases where you need to use local authentication, such as when signing in as the instance administrator. For these cases, Allure TestOps allows system authentication when LDAP is set as the primary authentication method:

The /login page uses the authentication method defined as primary in the settings. In this case, it is LDAP.
The /login/system page always uses system authentication.

To sign in as the instance administrator, go to https://<URL>/login/system and use the credentials of a local user.

Troubleshooting

If you receive the "Request failed with status code 401" error when trying to sign in with LDAP, check the following:

Make sure the LDAP URL specified in the configuration file is correct.
Make sure you use a valid SSL certificate.
Check that the credentials specified in the configuration file are correct and do not contain a space character at the end (for example, LDAP_LOGIN_SA and LDAP_LOGIN_SA_PASS in Docker Compose).