OIDC Identity Provider(3.1)

OIDC Identity Provider

It is possible to configure Usage Engine to take on the role of the 'identity provider' (IdP) in the OpenID Connect Authorization Code Flow described in https://openid.net/specs/openid-connect-core-1_0.html.

The diagram below shows the flow.

Configuring OIDC Identity Provider

To enable this functionality, you configure the 'auth' section in the values.yaml file used when installing the Helm chart.

auth:
  oidc:
    # Activate/deactivate MediationZone as OIDC Identity Provider
    enabled: true
    # List of clients that are granted to use MediationZone as OIDC provider when authenticating
    clients:
      - clientName: <client1 name>
	 	# The clientId value should be the name of the secret in env-secrets that holds the real clientId. 
      	# If the secret does not already exist it will be automatically generated.
        clientId: <the secret holding client1 id>
	 	# The clientSecret value should be the name of the secret in env-secrets that holds the real clientSecret. 
      	# If the secret does not already exist it will be automatically generated.
        clientSecret: <the secret holding client1 secret>
      - clientName: <client2 name>
        clientId: <the secret holding client2 id>
        clientSecret: <the secret holding client2 secret>

A few additional system properties need to be set for the IdP to function correctly:

Property	Description
mzonline.baseUrl	Base URL where the MZOnline web interface can be accessed.
auth.oidc.oidcBaseUrl	Base URL for the OIDC APIs. Can be set to the same value as 'mzonline.base_url', but certain environments may require a different value because of network setup.

By default, the Helm chart automatically generates the values of these properties to:

mzonline.baseUrl: https://mzonline$(domain)
auth.oidc.oidcBaseUrl: https://oidc$(domain)

Where $(domain) is the system domain value specified in value 'global.domain'.

OIDC Client Configuration

For an OIDC client to use Usage Engine as an OIDC IdP, it needs some configuration to make it able to find and use the IdP APIs correctly. This can be done either through Endpoint Discovery or through Manually Configured Endpoints.

Endpoint Discovery

If the OIDC client supports Provider Configuration service discovery (https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig), it is enough to configure the issuer URL of the Usage Engine IdP for the client to be able to find the URL of all endpoints. The URL must be reachable from the OIDC client. Refer to the client documentation for details on how to set issuer URL.

Note!

The service discovery support in Usage Engine currently does not include Issuer Discovery ('/.well-known/webfinger'), only Provider Configuration Discovery ('/.well-known/openid-configuration').

Manually Configured Endpoints

If automatic endpoint discovery is not supported by the OIDC client or is not used, all endpoints must be manually configured in the OIDC client configuration.

The endpoints are listed in the table below together with information on whether they are mandatory or optional.

Endpoint path	Description	Mandatory/Optional
/authz	Performs Authentication of the End-User, as described in https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint	Mandatory
/token	Provides access and Id tokens in response to valid authentication_code, as described in https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint	Mandatory
/userinfo	Provides additional user information in response to a valid access token, as described in https://openid.net/specs/openid-connect-core-1_0.html#UserInfo	Optional
/jwks	Provides the public key of the issuer according to the JWK specification https://datatracker.ietf.org/doc/html/rfc7517#section-4	Optional

Client Identification Configuration

An OIDC client must be configured with the same identification configuration, that is the Client Id and Client Secret fields, as defined in the OIDC configuration.

Example OIDC Client Configuration - Grafana

The below configuration example configures a Grafana installation as OIDC client to the Usage Egnine Identity Provider available at the URL https://mediationzone.exampledomain.com. Note that this example uses manually configured endpoints and does not include the Issuer URL.

#################################### Generic OAuth #######################
[auth.generic_oauth]
enabled = true
allow_sign_up = true
name = MediationZone
client_id = <the value of grafanaClientId in env-secrets>
client_secret = <the value of grafanaClientSecret in env-secrets>
scopes = openid offline_access
auth_url = https://mediationzone.exampledomain.com/auth/authz
token_url = https://mediationzone.exampledomain.com/auth/token
api_url = https://mediationzone.exampledomain.com/auth/userinfo
role_attribute_path: contains("roles"[*], 'Administrator') && 'Admin' || contains("roles"[*], 'Editor') && 'Editor' || contains("roles"[*], 'Viewer') && 'Viewer'
[log]

The identity provider configuration to make this work is:

auth:
  oidc:
    # Activate/deactivate MediationZone as OIDC Identity Provider
    enabled: true
    # List of clients that are granted to use MediationZone as OIDC provider when authenticating
    clients:
      - clientName: Grafana
        clientId: grafanaClientId
        clientSecret: grafanaClientSecret
		roles:
		  - Administrator
		  - Editor
		  - Viewer