Configuring OIDC provider for solutions

Introduction

For authentication within solutions any arbitrary OIDC compliant Identity Provider can be configured and used. Please note that this only affects authentication within solutions, e.g. the verification of the sent JWT, and does not affect the Solution Designer or Solution Hub environment at all. If Keycloak is used as an identity provider all configuration can be setup automatically by enabling the autoconfiguration flag of the k5-project resource.

Gathering data and prerequisites of the Identity Provider

The following conditions must be met by your Identity Provider:

  • Supported authentication flows / grant types:
    • Authorization Code (login to dashboard)
    • Implicit (login via swagger-ui)
    • Client Credentials (service execution by agents triggered by an event)
    • Password (testing solutions in the pipeline)
  • The Identity Provider must be conformant to the OIDC protocol
  • The Identity Provider must provide its OIDC configuration via metadata at a URL, that is constructed by <ISSUER>.well-known/openid-configuration, whereby <ISSUER> is referring to the issuer, that is used in the resulting token
  • The issuer of the token must be the same regardless of the flow that was used to authenticate
    Note:

To achieve this in an Azure app registration, you have to update the manifest and set the property accessTokenAcceptedVersion to 2.

  • All authentication flows except Authorization Code must issue an id_token

Minimum required data:

  • client_id: the ID of an oauth-client
  • client_secret: a secret value, which is bound to the referenced oauth-client
  • issuer: The issuer which has issued the JWT
  • jwk uri: The URL of the Json Web Key Set
  • user authorization uri: The URL of the OAuth authorization endpoint
  • token uri: The URL of the OAuth token endpoint

Optional data - highly dependent on the Identity Provider:

  • audience: the audience that needs to be included within calls of the Client Credentials Flow
  • scope: the scope that needs to be included within calls of the Client Credentials Flow
  • name of the username attribute within the token - default preferred_username
  • name of the name attribute within the token - default name

Known restrictions:

  • A proper logout in the dashboard can only be performed, if the OIDC configuration metadata document provides a property named end_session_endpoint
  • Authentication calls are only sending scope=openid for the Implicit and Password flow. In case of Authorization Code flow all supported scopes will be sent
  • Currently, there is support only for one Identity Provider per k5-project, that is managed by the k5-project-operator.

Configuration settings

Note:

Please do not forget to update the truststore to contain the complete certificate chain for a proper communication with the Identity Provider

Create secrets manually:

This step has to be repeated for every k5-project. Please ensure that your k5-project resource does not have the autoconfiguration flag for IAM enabled. If you do not want to configure the secrets manually, there is also the option to administer those secrets within the Configuration Management. Please note that those secrets are built out only during the creation of a k5-project from the default configuration values.

Create the following secrets within the namespace of the k5-project and provide the necessary information for each:

Secret NameUsageSupported Authentication Flows
dashboard-oauth-client-secretused to provide the login information for the dashboard; also used in the swagger-ui.Authorization Code, Implicit
debugserver-oauth-client-secretused for debugging within the CLIPassword
event-manager-oauth-client-secretused for service execution of agents, that were triggered by eventsClient Credentials
solution-test-oauth-client-secretused for executing tests within the pipelinePassword

The secret should always contain the following properties:

KeyDescriptionExample
issuerThe issuer of the tokenhttps://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/v2.0
client.idThe client id to use8325d28e-840e-4420-928c-33382d4b92a9
client.secretThe client secretaaf83822-6beb-4ea7-ab78-6af08e81ca8d
token.endpointThe token url of the identity provider that is used to get tokenshttps://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token
baseurlThe base url of the identity provider (only needed for legacy reasons; should be similar to the issuer)https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/
realmThe realm that is used for authentication (only needed for legacy reasons)mySecurityRealm

Example call for create a secret:

This sample call will create a secret named dashboard-oauth-client-secret and specifies all required values.

oc create secret generic dashboard-oauth-client-secret \
--from-literal=issuer='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/v2.0'  \
--from-literal=client.id='8325d28e-840e-4420-928c-33382d4b92a9'  \
--from-literal=client.secret='aaf83822-6beb-4ea7-ab78-6af08e81ca8d'  \
--from-literal=token.endpoint='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token' \
--from-literal=baseurl='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/'  \
--from-literal=realm='mySecurityRealm'

Configuration settings for the Identity Provider

List of redirect-URIs

The application (dashboard and swagger-ui) will send the following redirect URIs. Please ensure that your Identity Provider does explicitly accept these.

  • <HOSTNAME>/login/oauth2/code/dashboard
  • <HOSTNAME>/swagger-ui/oauth2-redirect.html

Special configuration possibilities

For the Client Credentials Flow working properly, different Identity Providers need different properties to set. In order to give full flexibility, there are some configuration properties that can be set additionally. They can be specified via a solution configuration within the Configuration Management (see Solution default configuration).

In order to specify the needed values, you can put the values inside the configmap property:

configmap
extraConfiguration: |
  # Optional additional configuration
  de.knowis.cp.ds.action.helper.overwriteParameter.scope: "api://8325d28e-840e-4420-928c-33382d4b92a9/.default"
  de.knowis.cp.ds.action.helper.overwriteParameter.audience:

You can specify any arbitrary key value pairs, that are sent to the Identity Provider by just using the pattern de.knowis.cp.ds.action.helper.overwriteParameter.KEY: VALUE. Declaring a key with no value, will actually result in an empty form parameter with this specific key.

Attribute names for name and username

Since the tokens may look very different, there is the possibility to configure the attribute names under which the token sends the desired information. Despite the default attributes like sub, issuer, exp, there needs to be information present about name and username of the user. The names of these attributes can be configured, if the default (name, preferred_username) is not sufficient.

The settings can be applied via configuration of the k5-project resource in the section of dashboard.

spec:
  configuration:
    dashboard:
      configmap:
        extra:
          de.knowis.cp.dashboard.security.claim.username: nickname
          de.knowis.cp.dashboard.security.claim.name: fullname

Reference calls

This section aim to outline the actual calls that are sent to the Identity Provider.

Password

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "grant_type=password" \
   -d "client_id=8325d28e-840e-4420-928c-33382d4b92a9" \
   -d "scope=openid" \
   -d "username=User@mydomain.com" \
   -d "password=passw0rd" \
   -d "client_secret=aaf83822-6beb-4ea7-ab78-6af08e81ca8d" \
 'https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token'

Client Credentials

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials" \
   -d "client_id=8325d28e-840e-4420-928c-33382d4b92a9" \
   -d "client_secret=aaf83822-6beb-4ea7-ab78-6af08e81ca8d" \
 'https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token'

Please note that the overrideParameter as described above will be appended to this call as specified with -d key=value

Calls for Authorization Code or Implicit cannot be done on the command line, since they are only working with enabled redirects in the browser.