OpenID Connect

The following guide will setup and configure Kpow with any standard OpenID provider (for example Keycloak, Ping Identity, etc).

IdP configuration

When creating the Kpow application inside your IdP (eg, Keycloak, Ping Identity) set the following values:

• Callback/redirect URI: https://kpow.mycorp.com/oauth2/openid/callback
• Initiate/login URI: https://kpow.mycorp.com/oauth2/openid

Kpow configuration

The following is an example configuration to integrate Kpow with OpenID authentication:

AUTH_PROVIDER_TYPE="openid"
OPENID_ACCESS_TOKEN_URI="http://localhost:8080/realms/master/protocol/openid-connect/token"
OPENID_AUTH_URI="http://localhost:8080/realms/master/protocol/openid-connect/auth"
OPENID_CLIENT_ID="my-client"
OPENID_CLIENT_SECRET="aS50emK11A02i5lZovcBFu5MXWf93zeu"
OPENID_SCOPES="email,roles"
OPENID_USER_FIELD="sub" # Optional, defines which field in the access token maps to a user's name (default: sub)

Issuer

By default, Kpow will check if the domain of the OPENID_AUTH_URI matches the iss (issuer) field of the JWT token payload.

This is done to validate the claims of the JWT token.

If your iss field is something other than the domain of the IdP (for example a URN) then you can use the OPENID_ISSUER field.

For example:

OPENID_ISSUER=urn:isan:0000-0000-2CEA-0000-1-0000-0000-Y

Scopes

Use the OPENID_SCOPES environment variable to specify which resources will be available to Kpow during authentication.

OPENID_SCOPES should be a comma separated list of scopes you wish to give Kpow.

At a minimum we recommend email or profile scopes and a roles scope for User authorization.

Note: the name of these scopes will vary depending on your OpenID provider. Refer to their documentation for more information on scopes.

Custom SSL certificates

To use self-signed certificates for SSL in OpenID URLs, provide them in a truststore and override the JVM default truststore with the following JVM parameter on startup.

To alter JVM startup parameters on startup when using the Kpow Docker container, set the same but as the JAVA_TOOL_OPTIONS environment variable.

  -Djavax.net.ssl.trustStore=/etc/kpow-truststore/kpow-truststore.jks -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword=***

User authorization

The following is an example Role Based Access Control file that integrates with OpenID:

# Allow all users who can authenticate access to the app
authorized_roles:
  - "*"

# Specify the path in the JWT token that maps to the roles of a user
openid:
  role_path: ["realm_access", "roles"]
  roles_from: access_token # Optional. Either access_token or id_token (default: access_token)

# Specify that users with 'admin' role are Admins
admin_roles:
  - "admin"

# Define some RBAC policies
policies:
  - resource: ["cluster", "N9xnGujkR32eYxHICeaHuQ"]
    effect:   "Allow"
    actions:  ["TOPIC_INSPECT", "TOPIC_PRODUCE"]
    role:     "admin"

Roles mapping

By default, Kpow will use the roles field in the payload of the JWT token.

Use the RBAC yaml's role_path config to specify a different attribute in the JWT token payload to use for roles.

Use the RBAC yaml's roles_from config to specify which JWT token should be inspected for roles information, either access_token or id_token (default: access_token).

Examples

Custom field

If your JWT token payload is contains a scopes field you would like to use for roles:

{
  "scopes": ["admin-role", "kpow-role"],
  "client_id": "xxxxx",
  "iss": "xxxxx",
  "aud": "xxxx",
  "sub": "xxxx"
  "exp": 1667526313
}

Use the following RBAC configuration:

openid:
  role_path: ["scopes"]

Nested field

If your JWT token payload contians some nested path for roles:

{
  "realm_access": {"roles": ["admin-role", "kpow-role"]},
  "client_id": "xxxxx",
  "iss": "xxxxx",
  "aud": "xxxx",
  "sub": "xxxx"
  "exp": 1667526313
}

Use the following RBAC configuration:

openid:
  role_path: ["realm_access", "roles"]