Configure OpenID Connect (OIDC) authentication with Keycloak

This topic describes how to configure Keycloak as an Identity provider for OpenId Connect to login in Release and protect the REST APIs using the Bearer Token Authorization.

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.

Installation

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

We use the docker-compose example from https://github.com/keycloak/keycloak-containers/blob/master/docker-compose-examples/keycloak-postgres-jdbc-ping.yml to setup keycloak.

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 a new digitalai-platform realm as shown below.

Add roles

We will add different roles in Keycloak as shown below.

Add users

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

Select the appropriate role mappings for a user.

Set up a client

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

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.

Select builtin mappers for newly created client.

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

Add new client scope

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

Add new protocol mapper

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

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.

Copy the client’s credentials which we will be using later.

Set up Digital.ai Release

Now let’s configure OpenID Connect (OIDC) authentication for Release. Follow the setup process from Release OIDC Setup Guide.

Below is our oidc configuration from xl-release.conf.

xl {
    security {
        auth {
            providers {
                oidc {
                    clientId="release"
                    clientSecret="61c5c3d6-5eb5-40cd-a396-32dd3d271f63"

                    issuer="http://localhost/auth/realms/digitalai-platform"
                    redirectUri="http://localhost:5516/oidc-login"
                    postLogoutRedirectUri="http://localhost:5516/oidc-login"

                    userNameClaim="preferred_username"
                    fullNameClaim="name"
                    emailClaim="email"
                    rolesClaim="groups"
                    externalIdClaim="sub"
                    scopes =["openid"]
                }
            }
        }
    }
}

Using Keycloak on Kubernetes Operator-based Deployment

If you are planning to use Keycloak with Digital.ai Release, you must set the oidc.enabled to True, and configure the value for the OIDC parameters in the cr.yaml file as described in the following table:

clientId=”<REDACTED>”
clientSecret=”<REDACTED>”

clientId=”<REDACTED>”
clientSecret=”<REDACTED>”

userNameClaim=“preferred_username”
fullNameClaim=“name”
emailClaim=“email”
rolesClaim=“groups”

issuer=”http://localhost:8080/auth/realms/digitalai-platform”
userAuthorizationUri=”http://localhost:8080/auth/realms/digitalai-platform/protocol/openid-connect/auth”
logoutUri=”http://localhost:8080/auth/realms/digitalai-platform/protocol/openid-connect/logout”

redirectUri=”http://localhost:5516/oidc-login”
postLogoutRedirectUri=”http://localhost:5516/oidc-login”

keyRetrievalUri=”http://keycloak:8080/auth/realms/digitalai-platform/protocol/openid-connect/certs”
accessTokenUri=”http://keycloak:8080/auth/realms/digitalai-platform/protocol/openid-connect/token”

Note: The path-based routing will not work if you use OIDC authentication. To enable path-based routing, you must modify the ingress specification in the cr.yaml file as follows:

• Set ingress.nginx.ingress.kubernetes.io/rewrite-target: /$2 to /
• Set ingress.path: /xl-release(/|$)(.*) to /

For more information about Kubernetes Operator, see Kubernetes Operator.

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.

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

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.

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'