🔑Configure OIDC authentication

Overview

This document outlines the steps to configure OpenID Connect (OIDC) authentication for a client application using the OIDC Discovery mechanism. The Discovery endpoint provides metadata for the OIDC Provider (OP), allowing dynamic configuration without manual entry of endpoints and other settings.

OpenID Connect (OIDC) is an authentication protocol based on the OAuth 2.0 framework. It adds a standardized identity layer on top of OAuth 2.0, enabling Single Sign-On (SSO) functionality. OIDC allows clients to verify the identity of users based on the authentication performed by an Authorization Server, and to obtain basic profile information about the user in an interoperable and REST-like manner.

Key terminology

To avoid confusion, let's define some key terms:

• The End User: The person who wants to log in.

• The Client (in this case, the Application, Keycloak): The entity that wants to authenticate users using OIDC.

• The Provider (also known as OpenID Connect Provider): The entity that provides the authentication services. It often has an Identity Provider associated with it, and is able to provide the user's identity information.

• The Identity Provider (in this case, the Provider): The entity that provides user identities and authentication services.

• The Discovery Document: A public JSON document that contains information about the Provider, including endpoints, supported scopes, and other metadata. Often accessible at https://<auth hostname>/.well-known/openid-configuration.

  • Example: https://accounts.google.com/.well-known/openid-configuration

Configuration

OIDC Provider side (Your Identity Provider)

Go to your OIDC Provider administration console and configure the necessary settings for OIDC authentication.

To configure OIDC authentication, you can follow these general steps:

1. Create an OAuth Client in your Identity Provider.

2. Set the Redirect URI to https://<app hostname>/api/auth/realms/7bf98083-e4ff-4769-baa7-da4fde86d932/broker/oidc/endpoint.

   • 7bf98083-e4ff-4769-baa7-da4fde86d932 correspond the the helm chart default value global.tenantID. In which, it has no other function beside naming the tenant. This used internally at Toucan.

   • oidc (before the /endpoint) correspond to the name of the OIDC authenticator (see below), in the OIDC client configuration. If you plan to use another name, replace oidc by the name of the authenticator.

3. Fetch the client ID and client secret. Also fetch the Provider's discovery URL.

That's should be it! Of course, some OIDC providers might require additional configuration, but this should be the minimal requirements.

OIDC Client side (Keycloak)

To configure OIDC authentication, follow these steps:

1. Create a secret with the client ID and client secret:

yaml: sso-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: sso-secret
  namespace: <namespace>
type: Opaque
stringData:
  client-secret: '<client secret>'

Deploy with kubectl apply -f sso-secret.yaml.

1. In the Helm Charts, set these parameters:

yaml: values.override.yaml

keycloak:
  config:
    sso:
      authenticators:
        - id: oidc
          displayName: 'My OIDC Provider'
          type: oidc
          issuer: 'https://sso.example.com'
          # Find the endpoints from your OIDC Provider discovery document
          authorization_endpoint: 'https://sso.example.com/auth'
          token_endpoint: 'https://sso.example.com/token'
          jwks_uri: 'https://sso.example.com/jwks'
          userinfo_endpoint: 'https://sso.example.com/userinfo'
          # optional
          introspection_endpoint: 'https://sso.example.com/token/introspect'
          # optional
          end_session_endpoint: 'https://sso.example.com/logout'
          scopes: openid email
          clientID: '<client id>' # From above
          clientSecret:
            secretName: sso-secret
            secretKey: client-secret

1. Deploy the Helm Charts (helm upgrade -f ./values.override.yaml ...).

That's it! The OIDC authentication should be configured and working now.