OpenID Connect SSO configuration

The property realm is only required if you use a Keycloak server as OIDC provider or if you want to benefit from the templating in the *-url properties ({realm-name} will be replaced with the realm value). If you use a Keycloak server, make sure you set it with the name of the realm in which your Bonita OIDC client is/will be created.

resource is the OIDC client Id given to your Bonita installation. You can change it if you want but you need to provide it to your OIDC provider.

auth-server-url is the base URL of the OIDC provider server. All other service endpoints URL values can reuse this base URL with the placeholder{auth-server-url}.

auth-url needs to be set with the URL of your OIDC provider Authorization endpoint. It can be prefixed with {auth-server-url} to only indicate the path of the end point or be a full absolute URL. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

token-url needs to be set with the URL of your OIDC provider Token endpoint. It can be prefixed with {auth-server-url} to only indicate the path of the end point or be a full absolute URL. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

logout-url needs to be set with the URL of your OIDC provider Logout endpoint. It can be prefixed with {auth-server-url} to only indicate the path of the end point or be a full absolute URL. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

token-issuer-uri needs to be set with the URL that will be used as issuer in the JWT tokens (iss claim). It can be prefixed with {auth-server-url} to only indicate the path of the issuer URI or be a full absolute URI. For example using Google’s OIDC provider, the issuer is https://accounts.google.com. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

user-info-url needs to be set with the URL of your OIDC provider userInfo end point. It is only used when accessing a resource with a Bearer Authorization header with an access token that is opaque (not a JWT) and cannot be validated or used to retrieve the logged in user claims. It can be prefixed with {auth-server-url} to only indicate the path of the end point or be a full absolute URL. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

jwks-url needs to be set with the URL of your OIDC provider JSON Web Key Set endpoint. It can be prefixed with {auth-server-url} to only indicate the path of the end point or be a full absolute URL. For example with Google as OIDC provider, this URL is https://www.googleapis.com/oauth2/v3/certs. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

jwt-access-token indicates if the access token is a JWT and should be validated. If false, it will be considered by Bonita OIDC module as an opaque token, its validation won’t be performed (but the ID token will, however, be validated) and the retrieval of the logged in user principal name will be delegated to the userInfo endpoint (see user-info-url) when accessing a resource with a Bearer Authorization header. Even if the access token is a JWT, this property should be set to false when the OIDC clients are not supposed/able to validate it. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

scope-values can be used to set the value of the scope parameter sent to the OIDC provider in the authentication request. The scope value openid is automatically added if it is no present, but you can add other scope values like email or profile depending on your OIDC provider configuration and the claims you need in the JWTs to match Bonita username. This property is specific to Bonita OIDC module and is not supported/documented by Keycloak.

Some OpenID Connect providers do not support having a pattern of valid redirecting URIs. It is the case with Google’s for example. With those providers you can use the state parameter to pass the target URL (the URL you initially requested and want to be redirected to). In order to do that, set the property save-target-url-in-state to true. When you do that, the redirect_URI query parameter will always be the same. Its default value is the path /bonita/keycloak on Bonita server, but you can set a different value using the property redirect-uri-path. Make sure this URL is part of the valid redirect URIs in you OIDC provider configuration for the Bonita client. When save-target-url-in-state is set to false or not present, the redirect_URI query parameter is used to save the target URL. Those properties are specific to Bonita OIDC module and are not supported/documented by Keycloak.

the ssl-required property value may need to be changed if Bonita Runtime and the IdP are not both accessed via HTTPS. Possible values for this property are: all, external, and none. For all, all requests must come in via HTTPS. For external, only non-private IP addresses must come over via HTTPS. For none, no requests are required to come over via HTTPS (not recommended for production). For instance, using Azure AD as OIDC provider requires this property to be set to all.

the principal-attribute value indicates the OIDC Tokens attribute/claim to use to be considered as user identifier in the client application. It should match the username in Bonita. Possible values are: sub, preferred_username, email, name, nickname, given_name, family_name, middle_name, profile. Using another claim is also possible as long as it is not part of the specified OIDC token standard claims (which are reserved). If the OIDC provider defines a custom claim whose value matches the username of Bonita accounts, just use this claim’s name as value for principal-attribute.

public-client needs to be set to false if the OIDC provider requires the client requests to be authenticated (with a client secret for example). In this case you also need to use the credentials property. If this property is set to true, then no client Authentication header will be sent to the OIDC provider.

enable-cors is required only if you want to be able to use Bonita REST API from a web application located on a different domain from your Bonita installation’s. It comes with additional options cors-max-age, cors-allowed-methods, cors-allowed-headers, cors-exposed-headers. You can check the Keycloak client adapter config documentation for more information.

credentials defines the authentication method used for token requests to the OIDC provider when Bonita client is configured with a confidential access type to the OIDC provider (public-client is set to false). You can set this property with an object containing just a secret (in this case client_secret_basic authentication method is used) or, since Bonita 2022.1-u6, you can specify the authentication method explicitly (for older versions see the Keycloak client authentication documentation for the configuration of this property). Supported keys are: client-secret-basic, client-secret-post, client-secret-jwt (or secret-jwt), private-key-jwt (or jwt). Here are some examples:

  "credentials" : {
    "secret" : "****"
  }

  "credentials" : {
    "client-secret-post": {
      "secret" : "****"
     }
  }

  "credentials" : {
    "client-secret-jwt": {
      "secret" : "****"
      "algorithm": "HS512"
     }
  }

  "credentials" : {
    "private-key-jwt": {
      "client-keystore-file": "classpath:keystore-client.jks",
      "client-keystore-type": "JKS",
      "client-keystore-password": "storepass",
      "client-key-password": "keypass",
      "client-key-alias": "clientkey",
      "token-expiration": 10
    }
  }

Some additional properties not present in the default file can be useful: