TestOps logo
Try TestOps

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 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

  1. Allure TestOps connects to the LDAP server using a service account.

  2. On the sign-in page, a user enters their credentials: a username (or email address) and password.

    Depending on the configuration, Allure TestOps may convert the username to lowercase before proceeding.

  3. 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 may be used for this query. Please note that these two options are mutually exclusive, therefore you can't configure them at the same time.

  4. The LDAP server returns the full account data, including its unique identifier (UID) and the groups it belongs to.

    At this stage, Allure TestOps attempts to load a previously created internal account that corresponds to the UID. If the account does not exist, Allure TestOps creates it automatically. Local authentication is disabled for LDAP accounts, and an account cannot use both standard and LDAP authentication methods.

    Depending on the configuration, Allure TestOps may or may not update existing accounts to match the data from the LDAP server. It can update the full name, email, avatar image, and roles.

  5. Allure TestOps redirects the user to the page they wanted to visit or to the main page.

Configuration

Edit the parameters in the values.yaml file:

  • LDAP server connection:

    • auth.ldap.enabled — must be true;
    • auth.ldap.url — LDAP server location;
    • auth.ldap.auth.user — query for loading the service account;
    • auth.ldap.auth.pass — service account password.

  • LDAP attribute names:

    • auth.ldap.uidAttribute — name of the attribute that stores each user's UID;
    • auth.ldap.passwordAttribute — name of the attribute that stores each user's password;
    • auth.ldap.usernamesToLowercase — if true, the username will be converted to lower case before searching;
    • auth.ldap.group.roleAttribute — name of the attribute that stores each group's role.

  • group mapping:

    • auth.ldap.syncRoles — if true, Allure TestOps will assign user roles according to group information from LDAP;

    • auth.ldap.userGroupName — comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;

    • auth.ldap.adminGroupName — comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;

    • allure.auth.defaultRole — the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.

      Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.

      If auth.ldap.syncRoles is true, the value must be ROLE_GUEST.

  • user search parameters:

    • auth.ldap.user.searchBase — starting point for searching users;

    • auth.ldap.user.searchFilter — filter for searching users;

    • auth.ldap.user.dnPatterns — comma-separated list of patterns for searching users.

      Do not set searchFilter and dnPatterns parameters together.

  • group search parameters:

    • auth.ldap.group.searchBase — starting point for searching groups;
    • auth.ldap.group.searchFilter — filter for searching groups.

Edit the parameters in the .env file:

  • LDAP server connection:

    • LDAP_URL — LDAP server location;
    • LDAP_LOGIN_SA — query for loading the service account;
    • LDAP_LOGIN_SA_PASS — service account password.

  • LDAP attribute names:

    • LDAP_UID_ATTRIBUTE — name of the attribute that stores each user's UID;
    • LDAP_LOWERCASEUSERNAMES — if true, the username will be converted to lower case before searching;
    • LDAP_GROUP_ROLE_ATTRIBUTE — name of the attribute that stores each user's role.

  • group mapping:

    • LDAP_SYNC_ROLES — if true, Allure TestOps will assign user roles according to group information from LDAP;

    • LDAP_MAPPING_ROLE_USERS — comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;

    • LDAP_MAPPING_ROLE_ADMINS — comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;

    • LDAP_DEFAULT_ROLE — the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.

      Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.

      If LDAP_SYNC_ROLES is true, the value must be ROLE_GUEST.

  • user search parameters:

    • LDAP_USER_SEARCH_BASE — starting point for searching users;
    • LDAP_USER_SEARCH_FILTER — filter for searching users.

  • group search parameters:

    • LDAP_GROUP_SEARCH_BASE — starting point for searching groups;
    • LDAP_GROUP_SEARCH_FILTER — filter for searching groups.

Edit the parameters in the /opt/testops/conf/testops.conf file:

  • general parameters:

    • ALLURE_LOGIN_PRIMARY — must be ldap;
    • ALLURE_LOGIN_LDAP_ENABLED — must be true.

  • LDAP server connection:

    • ALLURE_LOGIN_LDAP_URL — LDAP server location;
    • ALLURE_LOGIN_LDAP_USERDN — query for loading the service account;
    • ALLURE_LOGIN_LDAP_PASSWORD — service account password.

  • LDAP attribute names:

    • ALLURE_LOGIN_LDAP_UIDATTRIBUTE — name of the attribute that stores each user's UID;
    • ALLURE_LOGIN_LDAP_PASSWORDATTRIBUTE — name of the attribute that stores each user's password;
    • ALLURE_LOGIN_LDAP_LOWERCASEUSERNAMES — if true, the username will be converted to lower case before searching;
    • ALLURE_LOGIN_LDAP_GROUPROLEATTRIBUTE — name of the attribute that stores each group's role.

  • group mapping:

    • ALLURE_LOGIN_LDAP_SYNCROLES — if true, Allure TestOps will assign user roles according to group information from LDAP;

    • ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS — comma-separated list of the LDAP roles that correspond to the “User” role in Allure TestOps;

    • ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS — comma-separated list of the LDAP roles that correspond to the “Admin” role in Allure TestOps;

    • ALLURE_LOGIN_LDAP_DEFAULTROLE — the Allure TestOps role that should be used for LDAP users who do not belong to the "User" or "Administrator" roles.

      Allowed values: ROLE_ADMIN, ROLE_USER, ROLE_GUEST.

      If ALLURE_LOGIN_LDAP_SYNCROLES is true, the value must be ROLE_GUEST.

  • user search parameters:

    • ALLURE_LOGIN_LDAP_USERSEARCHBASE — starting point for searching users;

    • ALLURE_LOGIN_LDAP_USERSEARCHFILTER — filter for searching users;

    • ALLURE_LOGIN_LDAP_USERDNPATTERNS — comma-separated list of patterns for searching users.

      Do not set USERSEARCHFILTER and USERDNPATTERNS parameters together.

  • group search parameters:

    • ALLURE_LOGIN_LDAP_GROUPSEARCHBASE — starting point for searching groups;
    • ALLURE_LOGIN_LDAP_GROUPSEARCHFILTER — filter for searching groups.

Examples

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

LDAP_URL="ldaps://ldaps.space:636"
LDAP_USER_SEARCH_BASE="ou=People,dc=space"
LDAP_USER_SEARCH_FILTER="uid={0}"

LDAP_SYNC_ROLES=false
LDAP_GROUP_SEARCH_BASE="ou=group,dc=space"
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=space"
LDAP_LOGIN_SA_PASS=SeriviceAccountPassword

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=space"
ALLURE_LOGIN_LDAP_USERSEARCHFILTER="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=group,dc=space"
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=space"
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=johndoe))'

The arguments correspond to the following configuration parameters:

  • -H — auth.ldap.url,
  • -D — auth.ldap.auth.user,
  • -w — auth.ldap.auth.pass,
  • -b — auth.ldap.user.searchBase,
  • query — auth.ldap.user.searchFilter or auth.ldap.user.dnPatterns with the username instead of {0}.
  • -H — LDAP_URL,
  • -D — LDAP_LOGIN_SA,
  • -w — LDAP_LOGIN_SA_PASS,
  • -b — LDAP_USER_SEARCH_BASE,
  • query — LDAP_USER_SEARCH_FILTER or LDAP_USER_DN_PATTERNS with the username instead of {0}.
  • -H — ALLURE_LOGIN_LDAP_URL,
  • -D — ALLURE_LOGIN_LDAP_USERDN,
  • -w — ALLURE_LOGIN_LDAP_PASSWORD,
  • -b — ALLURE_LOGIN_LDAP_USERSEARCHBASE,
  • query — ALLURE_LOGIN_LDAP_USERSEARCHFILTER or ALLURE_LOGIN_LDAP_USERDNPATTERNS with the username instead of {0}.

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:

  1. Make sure the LDAP URL specified in the configuration file is correct.
  2. Make sure you use a valid SSL certificate.
  3. 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).
© Qameta Software Inc. All rights reserved.