Users authentication with OpenID and KeyCloak

The instructions below are only valid for Allure TestOps 4.x.

Allure TestOps implements standard Spring Boot OpenId client.

Prerequisites

To successfully configure and use OpenID with Keycloak you need to meet the following requirements.

1. You need to have administrative access to KeyCloak or a Keycloak admin near you during the configuration process.
2. You need the access to Allure TestOps configuration files.
3. You need to be able to apply the changes in the configuration, which could require some downtime.
4. Both KeyCloak and Allure TestOps need to use the same protocol for the communication, i.e. if one of the systems works behind HTTPS, then both systems need to work behind HTTPS, i.e. there must be something like reverse proxy that will allow using of HTTP between Allure TestOps and KeyCloak servers. Please consult your network administrator or DevOps to ensure proper configuration on the network side.

Integration of Allure TestOps and KeyCloak

Further examples will use fake addresses that in your case will differ.

Let's assume the following.

1. Allure TestOps is deployed and accessible on http://allure.local
2. KeyCloak is deployed and accessible on http://keycloak.local

Sequence

What needs to be done assuming we need to sync KeyCloak groups with Allure TestOps global roles.

1. Create a new realm on KeyCloak side (optional).
2. Create OpenID client on KeyCloak side in the realm you are going to use (mandatory).
3. Define realm roles and groups.
4. Define client scopes.
5. Add users and assign roles and groups.
6. Perform the configuration on Allure TestOps side.

Setting up KeyCloak side

Optionally, create a new realm on KeyCloak

Create a new realm, if you want Allure TestOps uses to reside in a separate Realm.

Create new OpenID client for Allure TestOps

Allure TestOps will be a OpenID client for KeyCloak.

1. Switch to the realm that is intended to work with Allure TestOps.
2. Go to Clients section in KeyCloak UI and click Create client

3. When creating a new client, set Valid Redirect URIs: http://allure.local/login/oauth2/code/keycloak

4. Finalise the configuration by saving the newly created client's data.

Define realm roles and groups

This step is required if you want to sync KeyCloak's groups with Allure TestOps global roles, i.e. the members of a certain group in KeyCloak will get Allure TestOps global roles ROLE_ADMIN or ROLE_USER.

Allure TestOps syncs global roles with the groups on KeyCloak side.

On KeyCloak side, create two roles, one for the group of users who will be admins on Allure TestOps side and another for the group. In our example we'll use role and ato_admins for the Allure TestOps users who supposed to be administrators (ROLE_ADMIN) and ato_users for those who are going to get a simple user role (ROLE_USER).

1. Go to Realm roles in the Realm where Allure TestOps is registered as OpenID client.
2. Create 2 roles
   • ato_admins
   • ato_users
3. Go to Groups
4. Create 2 groups
   • ato_admins
   • ato_users
5. Go to ato_admins setting Role mappings
   • add ato_admins role to the list of roles
6. Go to ato_users setting Role mappings
   • add ato_users role to the list of roles

Now, we have 2 groups which have assigned roles.

Define client scopes

For the information about assigned groups for a certain user to be accessible for Allure TestOps, we need to add a new scope to Allure TestOps as OpenId client on KeyCloak side.

1. Go to the Client scopes
2. Click Create client scope
3. Name the scope (we'll name the scope groups for the sake of the example).
   • assign Default type to the scope being created.
   • Check Include in the token scope as we need this information to be available for Allure TestOps in the access token (see below).
4. Go to the settings of the created scope
   • Switch to the Mappers tab
5. Click Add mapper and in drop-down select from predefined mappers.
6. Check a mapper called groups and make this scope to default one.

Check the content of access token

You can try to get the access token from KeyCloak. This exercise could be useful during the troubleshooting if anything goes south with the roles synching. So, for now, you can easily skip this step.

Allure TestOps will receive the access token form KeyCloak upon the successful authentication attempt. The access token will contain the information about the user that logs in to Allure TestOps using KeyCloak as an Identity provider (or IAM).

Execute the API call using curl or any other tool you are accustomed to.

USERNAME=name of any user registered in Keycloak for Allure TestOps OpenId
U_PASSWORD=password for the user above
CLIENT_ID=testops

RESPONSE=$(curl -X POST 'http://keycloak.local/realms/testops/protocol/openid-connect/token' \
    --data-urlencode "client_id=${CLIENT_ID}" \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'scope=openid' \
    --data-urlencode "username=${USERNAME}" \
    --data-urlencode "password=${U_PASSWORD}")

ACCESS_TOKEN=$(echo $RESPONSE | jq .access_token)
echo "$ACCESS_TOKEN"

then you need to decode the received access token, e.g. using JWT debug tool.

Then perform formatting of the JSON content (we deleted content which has no interest for sake of clarity).

{
    "exp": 1703517143,
    "iat": 1703516843,
    "jti": "62b7bd96-a982-4063-9c97-f12dbe1553f8",
    "iss": "http://keycloak.local/realms/testops",
    "typ": "Bearer",
    "azp": "testops",
    "acr": "1",
    "scope": "openid profile email groups",
    "sid": "043242d3-3c67-4ad7-8795-46c0df9f745e",
    "email_verified": true,
    "name": "Bugs Bunny",
    "groups": [
        "default-roles-testops",
        "ato_admins",
        "offline_access",
        "uma_authorization"
    ],
    "preferred_username": "bugsbunny",
    "given_name": "Bugs",
    "family_name": "Bunny",
    "email": "[email protected]"
}

So, the scope groups contains the information on the group ato_admins, it'll be used for the sync roles feature.

Add users and assign roles and groups

Now, you need to add KeyCloak users and distribute them between the appropriate groups to synch their groups in KeyClock with Allure TestOps global roles.You can skip this step, if you are going to manage the global roles in Allure TestOps.

Perform the configuration on Allure TestOps side

Configuring Allure TestOps for using KeyCloak with OpenId

Depending on selected deployment type the configuration need to be performed in different files and the names of the parameters will look a bit differently from end user perspective.

Below we describe the parameters for the officially supported deployments and the configuration parameters described in the deployment section.

Client configuration

env:
  open:
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENTNAME: KeyCloak
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENTID: testops
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENTSECRET: bar
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_REDIRECTURI: http://testops.local/login/oauth2/code/keycloak
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUERURI: http://keycloak.local/realms/testops
    SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_USERNAMEATTRIBUTE: preferred_username
    SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_SCOPE: openid,email,profile
    ALLURE_LOGIN_OPENID_SYNCROLES: false
    ALLURE_LOGIN_OPENID_GROUPROLEATTRIBUTE: groups
    ALLURE_LOGIN_OPENID_GROUPAUTHORITIES_ROLEUSERGROUPS: ato_users
    ALLURE_LOGIN_OPENID_GROUPAUTHORITIES_ROLEADMINGROUPS: ato_admins

auth:
  primary: openid

allure:
< ... some (many) lines are deleted for the OpenID context sake ...>
  auth:
    <removed for better clarity of example>
    defaultRole: ROLE_GUEST    

allure:
< ... some (many) lines are deleted for the OpenID context sake ...>
  auth:
    < ... some lines are deleted for the OpenID context sake ...>
    oidc:
      enabled: true # <<< enable
      client:
        name: KeyCloak # <<< Name of OpenId provider
        id: testops # <<< Name of OpenId client as it's defined in KeyCloak
        secret: bar # <<< Leave empty if client authentication is not used
      redirectURI: http://testops.local/login/oauth2/code/keycloak # <<< Same as set in KeyCloak config
      issuerURI: http://keycloak.local/realms/testops # <<< See the comment below
      userNameAttribute: preferred_username # <<< As per your rules
      scope: openid,email,profile # <<< Leave as it is
      syncRoles: false # <<< Leave as it is if you manage Global Roles via Allure TestOps UI
      roleAttribute: groups # As defined in client scopes
      userGroupName: ato_users # <<< Group name for ROLE_USER
      adminGroupName: ato_admins # <<< Group name for ROLE_ADMIN

{"issuer":"http://keycloak.local/realms/testops","authorization_endpoint":"http://keycloak.local/realms/testops/protocol/openid-connect/auth","token_endpoint":"http://keycloak.local<DELETED>}

Sync Roles configuration

Motivation

Why do we need synching roles with KeyCloak?

Sync of the roles provides you better control over the licence consumption, and prevents end users getting unauthorised access to Allure TestOps projects and you can manage access to Allure TestOps using the features of your Identity Provider.

Sync roles configuration

1. On KeyCloak side you need to have Roles and Groups configured.
2. Groups must be present in client scopes

allure:
< ... some (many) lines are deleted for the OpenID context clarity sake ...>
  auth:
    < ... some lines are deleted for the OpenID context clarity sake ...>
    oidc:
      enabled: true
      client:
        name: KeyCloak
        id: testops
        secret:
      redirectURI: http://testops.local/login/oauth2/code/keycloak
      issuerURI: http://keycloak.local/realms/testops
      userNameAttribute: preferred_username
      scope: openid,email,profile
      # !!! We are setting following four parameters now !!!
      syncRoles: true
      roleAttribute: groups # As defined in client scopes
      userGroupName: ato_users # <<< Group name for ROLE_USER
      adminGroupName: ato_admins # <<< Group name for ROLE_ADMIN