> For the complete documentation index, see [llms.txt](https://docs-v3.toucantoco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/authentication/oidc.md).

# 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:

{% code title="yaml: sso-secret.yaml" overflow="wrap" %}

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

{% endcode %}

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

2. In the Helm Charts, set these parameters:

{% code title="yaml: values.override.yaml" %}

```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
```

{% endcode %}

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-v3.toucantoco.com/self-hosted-toucan/configuration/authentication/oidc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.