TestOps logo
Try TestOps

Authentication via LDAP

This integration works with on-premises deployment only. For SaaS solution integration with external IAM providers will be introduced in the beginning of 2024.

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.

Note that integration with an LDAP server is not the easiest authentication method to set up. A significant factor here is that the protocol is very flexible in terms of what queries and parameter names it uses. Different LDAP servers may have very different parameters, so there can never be a simple “copy, paste and run” example.

Please make sure that you have a good understanding of how your LDAP server is configured — or consult a colleague who has it.

How it works

The diagram above shows the steps of a typical successful interaction between a user, an Allure TestOps instance and an LDAP server. -->

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

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

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

  3. Allure TestOps makes an LDAP query to check if an account exists with the given credentials.

    Depending on the configuration, either a search filter or DN patterns may be used for this query. Note that these two options are mutually exclusive, and you must not configure both the search filter and the DN patterns 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 point, Allure TestOps tries to load a previously created internal account that corresponds to the given UID. If it does not exist, Allure TestOps creates it on the fly. Note that Allure TestOps disables the local authentication for the account, i.e. you cannot have an account with both the standard and LDAP methods allowed.

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

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

Parameters

Edit the following 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 unique identifier.
    • 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.
    • auth.ldap.syncRoles — if true, Allure TestOps will reload groups from LDAP during each login attempt.

  • Group mapping

    • auth.ldap.userGroupName — comma-separated list of the LDAP roles that correspond to the “Users” role in Allure TestOps.
    • auth.ldap.adminGroupName — comma-separated list of the LDAP roles that correspond to the “Admins” role in Allure TestOps.
    • allure.auth.defaultRole — the Allure TestOps role that should be used for LDAP users which belong to neither “Users” not “Admins”. Allowed values: “ROLE_ADMIN”, “ROLE_USER”, “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.

  • Group search parameters

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

Edit the following 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 unique identifier.
    • 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.
    • LDAP_SYNC_ROLES — if true, Allure TestOps will reload groups from LDAP during each login attempt.

  • Group mapping

    • LDAP_MAPPING_ROLE_USERS — comma-separated list of the LDAP roles that correspond to the “Users” role in Allure TestOps.
    • LDAP_MAPPING_ROLE_ADMINS — comma-separated list of the LDAP roles that correspond to the “Admins” role in Allure TestOps.
    • LDAP_DEFAULT_ROLE — the Allure TestOps role that should be used for LDAP users which belong to neither “Users” not “Admins”. Allowed values: “ROLE_ADMIN”, “ROLE_USER”, “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 following 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 unique identifier.
    • 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.
    • ALLURE_LOGIN_LDAP_SYNCROLES — if true, Allure TestOps will reload groups from LDAP during each login attempt.

  • Group mapping

    • ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEUSERGROUPS — comma-separated list of the LDAP roles that correspond to the “Users” role in Allure TestOps.
    • ALLURE_LOGIN_LDAP_GROUPAUTHORITIES_ROLEADMINGROUPS — comma-separated list of the LDAP roles that correspond to the “Admins” role in Allure TestOps.
    • ALLURE_LOGIN_LDAP_DEFAULTROLE — the Allure TestOps role that should be used for LDAP users which belong to neither “Users” not “Admins”. Allowed values: “ROLE_ADMIN”, “ROLE_USER”, “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.

  • 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: allure_users
    adminGroupName: allure_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/ROLE_ADMIN
LDAP_DEFAULT_ROLE=ROLE_GUEST

LDAP_LOGIN_SA="cn=admin,dc=space"
LDAP_LOGIN_SA_PASS=SeriviceAccountPassword_Here

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_USERDNPATTERNS= do not use with ALLURE_LOGIN_LDAP_USERSEARCHFILTER
ALLURE_LOGIN_LDAP_USERSEARCHBASE="ou=People,dc=space"
ALLURE_LOGIN_LDAP_USERSEARCHFILTER="uid={0}"
ALLURE_LOGIN_LDAP_DEFAULTROLE=${LDAP_DEFAULT_ROLE}
ALLURE_LOGIN_LDAP_UIDATTRIBUTE=uid
ALLURE_LOGIN_LDAP_SYNCROLES='true'
# these are to be enabled if ALLURE_LOGIN_LDAP_SYNCROLES='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
# service account data to log-in to LDAP
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 along with standard authentication

Normally, when a company configured LDAP authentication for Allure TestOps, that server is considered the source of truth about the users' accounts, and LDAP is set as primary way of authentication. However, situations may still occur when you need to use the local authentication, for example when you want to log in as the instance's administrator. For such cases Allure TestOps allows using the system authentication when LDAP is enabled as primary way of the authentication.

  • The /login page uses the method of authentication set as primary in the settings, which will be most likely LDAP since you are reading this very page,
  • The /login/system page always uses the system authentication.

To log in as the instance's administrator, go to http(s)://allure-url/login/system and use local user's credentials.

Troubleshooting

If you are receiving a "Request failed with status code 401" error when trying to login with LDAP, check the following:

  1. Make sure the LDAP URL specified in the configuration file is correct.
  2. Make sure you are using a valid SSL certificate.
  3. Check that the credentials specified in the configuration file (such as LDAP_LOGIN_SA and LDAP_LOGIN_SA_PASS) are correct and do not contain a space character at the end.
© Qameta Software Inc. All rights reserved.