Users authentication with OpenID and Keycloak
The instructions below are only valid for Allure TestOps version 5.6.4 and later.
Allure TestOps implements standard Spring Boot OpenId client.
Prerequisites
To successfully configure and use OpenID with Keycloak you need to meet the following requirements.
- You need to have administrative access to Keycloak or a Keycloak admin near you during the configuration process.
- You need the access to Allure TestOps configuration files.
- You need to be able to apply the changes in the configuration, which could require some downtime.
- 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.
- Allure TestOps is deployed and accessible on http://allure.local
- 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.
- Create a new realm on Keycloak side (optional).
- Create OpenID client on Keycloak side in the realm you are going to use (mandatory).
- Define realm roles and groups.
- Define client scopes.
- Add users and assign roles and groups.
- 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.
- Switch to the realm that is intended to work with Allure TestOps.
- Go to Clients section in Keycloak UI and click Create client
- When creating a new client, set Valid Redirect URIs: http://allure.local/login/oauth2/code/keycloak
- 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_ADMINorROLE_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).
- Go to Realm roles in the Realm where Allure TestOps is registered as OpenID client.
- Create 2 roles
ato_adminsato_users
- Go to Groups
- Create 2 groups
ato_adminsato_users
- Go to
ato_adminssetting Role mappings- add
ato_adminsrole to the list of roles
- add
- Go to
ato_userssetting Role mappings- add
ato_usersrole to the list of roles
- add
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.
- Go to the Client scopes
- Click Create client scope
- Name the scope (we'll name the scope
groupsfor 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).
- Go to the settings of the created scope
- Switch to the Mappers tab
- Click Add mapper and in drop-down select from predefined mappers.
- 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
Get OpenID provider endpoints
For proper integration between an OpenID provider and Allure TestOps as an OpenID client, only three endpoints need to be configured on the Allure TestOps side:
- tokenUri,
- jwksSetUri,
- authorizationUri.
To obtain these URI parameters, go to the Realm settings section in Keycloak. In the General tab, locate the Endpoints section and click the OpenID Endpoint Configuration link. This link will direct you to the page http://keycloak.local/realms/testops/.well-known/openid-configuration, which is a JSON file containing all the endpoints for the current Realm.
{
"issuer": "http://keycloak.local/realms/testops-realm",
"authorization_endpoint": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/auth",
"token_endpoint": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/token",
"introspection_endpoint": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/token/introspect",
"userinfo_endpoint": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/userinfo",
"end_session_endpoint": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/logout",
"frontchannel_logout_session_supported": true,
"frontchannel_logout_supported": true,
"jwks_uri": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/certs",
"check_session_iframe": "http://keycloak.local/realms/testops-realm/protocol/openid-connect/login-status-iframe.html",
"grant_types_supported": [
"authorization_code",
"implicit",
"refresh_token",
"password",
"client_credentials",
"urn:openid:params:grant-type:ciba",
"urn:ietf:params:oauth:grant-type:device_code"
],
"acr_values_supported": [
<...>
}
From the opened page, you will need the following endpoints:
- token_endpoint,
- jwks_uri,
- authorization_endpoint.
Configuring Allure TestOps to use Keycloak with OpenID
The configuration process varies depending on the selected deployment type, and the parameter names may differ slightly from the end user’s perspective.
Below, we describe the parameters for officially supported deployments and the configuration parameters described in the deployment section.
Client configuration
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.
How it works
On the Identity Provider side, you need to create a group. Then, on the Allure TestOps side, you need to configure the mapping of users to these groups. Based on the membership in these groups, Allure TestOps will assign a global role to the user.
You cannot map end uses to access groups with this synchronization.
Sync roles configuration
- On Keycloak side you need to have Roles and Groups configured.
- Groups must be present in client scopes
