Configure OpenID Connect (OIDC) Authentication with Keycloak

This topic describes how to configure Keycloak to authenticate Release users and REST API calls (using the Bearer Token Authorization).

About Keycloak

Keycloak is an open source Identity and Access management solution. It is based on popular standards such as Security Assertion Markup Language (SAML) 2.0, OpenID Connect, and OAuth 2.0.


See the Keycloak documentation, for more information about the hardware requirements, distribution directory structure, and operation mode.

We use the docker-compose example from to setup keycloak.

Keycloak default screen

Set Up a Realm

First, we will create a new realm. On the top left, navigate to Master, open the dropdown menu, and click Add realm.

Add realm

Add a new digitalai-platform realm as shown below.

digitalai-platform realm

Realm details

Add Roles

We will add different roles in Keycloak as shown below.

Add role

All roles

Add Users

We will now add new users in Keycloak. Fill in all fields, such as Username, Email, First Name, and Last Name.

Add user

Select the appropriate role mappings for a user.

Map roles

All users

Create a Client

The next step is to create a client in our realm, as shown below.

Add client

Fill in all of the mandatory fields in the client form. Pay attention to Direct Grant Flow and set its value to direct grant. Change the Access Type to confidential.

Client details

Direct grant

Select builtin mappers for newly created client.

Client mappers

Make sure that username and groups mappings are present in both the id token and the access token.

Group mapping

Add New Client Scope

Next, we have to create a new client scope for REST APIs, as shown below.

Add client scope

Add New Protocol Mapper

Add a new protocol mapper to add audience information in the access token, as shown below.

Add protocol mapper

Set Default Client Scope

The final step is to add the client scope release-rest-api as the default for the release client, as shown below.

Add default client scope

Set Up Client Credentials

You must set up the client authentication method and configure the credentials for the client. You must do this on the Credentials tab. Release supports the following authentication methods in Keycloak.

  • Client ID and Secret
  • Client Secret JWT
  • Private Key JWT

For more information, see:

Generate the credentials and keep them handy for later use.

Client credentials

Set Up Release

Now let’s configure OpenID Connect (OIDC) authentication for Release. Follow the instructions at Set Up the OpenID Connect (OIDC) Authentication for Release.

Here’s an example OIDC configuration in the xl-release.conf file to authenticate using Client ID and Client Secret. See Set Up the OpenID Connect (OIDC) Authentication for Release to know more about other authentication methods such as Client Secret JWT and Private Key JWT.

xl {
    security {
        auth {
            providers {
                oidc {


                    scopes =["openid"]

Test your set up

Open your Release URL in the browser and you should be redirected to Keycloak login page. Enter credentials of any user created on keycloak.

Release login

User profile will be created for the new user in release.

After login

Test Public REST APIs

Generate an access token using the password grant type flow for your client. You can use the curl command, as shown below.

curl -L -X POST 'http://localhost/auth/realms/digitalai-platform/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=release' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_secret=61c5c3d6-5eb5-40cd-a396-32dd3d271f63' \
--data-urlencode 'scope=release-rest-api' \
--data-urlencode 'username=alice' \
--data-urlencode 'password=alice'

Alternatively, we can use REST API tools like Postman, as shown below.

Postman request

The response would be a valid JWT Token:

    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...Daw3OcJ2aPFzXY1cpHmH0W36TTfgfYGHgnDqB4w",
    "expires_in": 600,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldU...YlO6MzdDRhx_J3WShGXesjOmhY",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "d2c14e42-9bc3-4416-9bea-02aa6adb770e",
    "scope": "profile release-rest-api email"

We can now pass the access_token as a Bearer Token to authenticate the Release public REST APIs.

curl -L -X GET 'http://localhost:5516/api/v1/releases/' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...Daw3OcJ2aPFzXY1cpHmH0W36TTfgfYGHgnDqB4w'