> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.