Skip to main content
Version: 95.5
Enterprise

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"]

OpenID Connect v2​

Kpow provides a new OpenID Connect implementation from v96.5 with a simplified configuration model, user logout, and an improved user experience for session reauthentication that uses refresh tokens to avoid resetting the UI.

IdP configuration​

IdP configuration is largely the same, only the Initiate/login uri has been simplified.

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/

Kpow configuration​

Configuration for OpenID Connect v2 is different to our original OpenID Connect implementation.

  • The AUTH_RROVIDER_TYPE variable is set to 'oidc', not 'openid'.
  • Environment variables are preceded by OIDC_*, not OPENID_*
  • Configuration is simplified to support /.well-known/openid-configuration discovery via the OIDC_ISSUER
  • Session expiry is now optional (on by default)
  • Session reauthentication via refresh tokens is configurable (on with sensible defaults)

The following is the simplest configuration to integrate Kpow with OpenID authentication:

AUTH_PROVIDER_TYPE="oidc"
OIDC_ISSUER="http://your-idp/realms/master"
OIDC_CLIENT_ID="my-client"
OIDC_CLIENT_SECRET="your-client-secret"
HTTP_FORWARDED="true" # recommended for reverse-proxied installations, see note below

Advanced Configuration​

Specific Endpoints​

If your OIDC provider does not support metadata discovery via /.well-known/openid-configuration, you can configure specific authorization, token, and end-session endpoints:

OIDC_AUTHORIZATION_ENDPOINT="http://your-idp/realms/master/protocol/openid-connect/auth"
OIDC_TOKEN_ENDPOINT="http://your-idp/realms/master/protocol/openid-connect/token"
OIDC_END_SESSION_ENDPOINT="http://your-idp/realms/master/protocol/openid-connect/logout"

Scopes​

Provide a comma separated list of scopes you wish to give Kpow in addition to the required openid scope.

OIDC_SCOPES="profile,email" # This is the default configuration if none is provided

This configuration causes Kpow to request "openid,profile,email" scopes from your IdP, as 'openid' is a required scope for OpenID Connect.

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

Session Expiry​

A user's session will expire when the credentials provided in the OIDC JWT token expire.

You can disable session expiry by setting:

OIDC_RESPECT_EXPIRY="false"

Refresh Token Redemption​

Before a user's session expires Kpow will attempt to redeem the OIDC refresh token (when available) to refresh the user's credentials without requiring the user to be redirected back through the IdP for reauthentication.

Refresh token redemption has the advantage of not interrupting or refreshing the UI, as the interaction is managed by the Kpow back-end.

If there is no refresh token available, or refresh token redemption is unsuccessful, then the user will be redirected through the IdP for reauthentication on session expiry.

Refresh token redemption is attempted when a user is close to session expiry, you can adjust this period by specifying a duration in seconds, or disable refresh token redemption by setting the period to -1.

The default is 240, this has the effect of attempting session refresh when the user is four minutes from expiry.

Refresh is attempted every 30s within the refresh period, ending when a user's session expires.

OIDC_REFRESH_PERIOD=-1 # with this setting, refresh tokens are disabled

Refresh Token Availability​

Most OpenID Connect providers are configured to send a Refresh token along with the ID and Access token when your user authenticates.

Some OpenID Connect providers may require you to request an additional scope to make refresh tokens available to users, check your providers documentation for more.

User Authorization​

User authorization configuration is the same as our original OpenID Connect implementation, with the exception that the openid section is replace by a new oidc section with the following format:

oidc:
  user_id_source: id_token # Default, can also be access_token
  user_id_path: ["sub"] # Default, can be any path within the source token 
  user_roles_source: access_token # Default, can also be id_token
  user_roles_path: ["realm_access", "roles"] # Example, varies by IdP

Debugging​

To turn on debug logging, set the following enviornment variable:

DEBUG_AUTH="true"