> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC with Keycloak

> Configure OpenID Connect single sign-on between TrueFoundry and a Keycloak realm.

This guide walks you through setting up OpenID Connect (OIDC) single sign-on between TrueFoundry and a Keycloak realm. Once finished, members of the realm can sign in to TrueFoundry through a **Login with Keycloak** button.

## Prerequisites

* A TrueFoundry tenant with **Admin** access to **Settings → Security & Access → SSO**.
* A Keycloak deployment (self-hosted or managed) with admin access to the realm you want to federate.
* The Keycloak realm reachable from TrueFoundry's login service over HTTPS.

<Tip>
  You'll bounce between the **Keycloak admin console** and the **TrueFoundry SSO settings**. Keep both open in adjacent tabs to copy-paste values quickly.
</Tip>

## Configuration overview

<Steps>
  <Step title="Create an OIDC client in Keycloak">
    Register a confidential client in the realm you want users to sign in with.
  </Step>

  <Step title="Copy the client credentials">
    Grab the Client ID and Client Secret that TrueFoundry will use.
  </Step>

  <Step title="Build the Issuer URL">
    Construct the OpenID issuer for your realm.
  </Step>

  <Step title="Configure and test TrueFoundry">
    Paste everything into the TrueFoundry SSO form and sign in.
  </Step>
</Steps>

## Step 1 — Register a client in Keycloak

<Steps>
  <Step title="Open Clients">
    Sign in to the Keycloak admin console and select the realm you want to federate from the realm dropdown in the top-left.

    In the left navigation, click **Clients**, then **Create client**.
  </Step>

  <Step title="Configure general settings">
    On the **General settings** step:

    * **Client type**: select **OpenID Connect**.
    * **Client ID**: enter `truefoundry` (or any other identifier you prefer).
    * **Name** *(optional)*: a display name such as `TrueFoundry`.

    Click **Next**.
  </Step>

  <Step title="Configure capability">
    On the **Capability config** step:

    * **Client authentication**: toggle **On** (this makes the client confidential and unlocks the Client Secret you'll need later).
    * **Authorization**: leave **Off** unless you specifically use Keycloak Authorization Services.
    * **Authentication flow**: check **Standard flow**, **Direct access grants**, and **OAuth 2.0 Device Authorization Grant**.

    Click **Next**.
  </Step>

  <Step title="Configure login settings">
    On the **Login settings** step:

    * **Root URL** *(optional)*: set to your TrueFoundry control plane URL, for example `https://app.your-company.truefoundry.cloud`.
    * **Valid Redirect URIs**: add

      ```
      https://login.truefoundry.com/oauth2/callback
      ```

          <Warning>
            The redirect URI must match exactly — including the scheme (`https`) and trailing path. Wildcards (`*`) are not required and not recommended.
          </Warning>

    Click **Save**.
  </Step>
</Steps>

## Step 2 — Copy the Client Secret

<Steps>
  <Step title="Open the Credentials tab">
    Inside your new client, switch to the **Credentials** tab.
  </Step>

  <Step title="Copy the Client secret">
    Click the copy icon next to **Client Secret** and store it somewhere safe — you'll paste it into TrueFoundry shortly.

    <Tip>
      If you ever need to rotate the secret, click **Regenerate** on this tab and update the value under **Settings → Security & Access → SSO** in TrueFoundry.
    </Tip>
  </Step>
</Steps>

## Step 3 — Build the Issuer URL

Keycloak's OIDC discovery URL for a realm follows this pattern:

```
https://<keycloak-host>/realms/<realm-name>
```

For example, if your Keycloak runs at `https://sso.acme.com` and the realm is named `engineering`, the issuer is:

```
https://sso.acme.com/realms/engineering
```

<Note>
  On older Keycloak (≤ 17) the path was `/auth/realms/<realm-name>`. Newer versions drop the `/auth` prefix by default. Use whichever path your deployment actually serves — you can verify by opening `https://<keycloak-host>/realms/<realm-name>/.well-known/openid-configuration` in a browser.
</Note>

## Step 4 — Configure TrueFoundry

<Steps>
  <Step title="Open SSO settings">
    In TrueFoundry, go to **Settings → Security & Access → SSO**.

    Click the **+** icon labeled **Add New SSO Config**.

    <Frame caption="SSO page in TrueFoundry — click the + icon to add a new SSO configuration">
      <img src="https://mintcdn.com/truefoundry/OlEFjoHwZJ0edSjd/images/sso/entra/saml-truefoundry-add-sso-config.png?fit=max&auto=format&n=OlEFjoHwZJ0edSjd&q=85&s=f768205b84d9f33ce04a8b8576ab0070" alt="TrueFoundry SSO settings page with the Add New SSO Config plus button highlighted" width="1024" height="263" data-path="images/sso/entra/saml-truefoundry-add-sso-config.png" />
    </Frame>
  </Step>

  <Step title="Fill in the SSO form">
    * **Enabled**: turn this on.
    * **Name**: a lowercase alphanumeric label — for example, `keycloakoidc`.
    * **SSO Provider**: select **Custom**.
    * **Authentication Configuration**: choose **OIDC**.
    * **Client ID**: the client ID you set in Keycloak (for example, `truefoundry`).
    * **Client Secret**: the secret copied from the **Credentials** tab.
    * **Discover endpoints**: leave enabled.
    * **Issuer URL**: the value you built in Step 3, for example `https://sso.acme.com/realms/engineering`.
    * **Scopes** *(optional)*: leave blank to use the default `openid email`. Add `profile` if you want first and last name in the token.
  </Step>

  <Step title="Save">
    Click **Save**. TrueFoundry will fetch the realm's OpenID discovery document and store the credentials.
  </Step>
</Steps>

## Encryption algorithm restrictions

<Warning>
  TrueFoundry does **not** support the **RSA-OAEP** encryption algorithm for ID tokens. If your Keycloak realm has an active key provider that uses `RSA-OAEP`, sign-in will fail with a token decryption error.

  Supported algorithms:

  `ES384`, `HS384`, `ES256`, `HS256`, `HS512`, `PS384`, `RS384`, `PS256`, `RS256`, `PS512`, `RS512`, `none`, `ES512`.
</Warning>

<AccordionGroup>
  <Accordion title="How to disable the RSA-OAEP key provider in Keycloak">
    1. In the Keycloak admin console, open the realm you're federating and click **Realm settings** in the left navigation.
    2. Switch to the **Keys** tab.
    3. Click the **Providers** sub-tab.
    4. Locate any provider whose **Algorithm** column shows `RSA-OAEP` (commonly named `rsa-enc-generated` or similar).
    5. Click the provider, set **Enabled** to **Off**, and click **Save**.

    Make sure at least one supported signing key remains **Enabled** and **Active** so Keycloak can still issue tokens.
  </Accordion>
</AccordionGroup>

## Step 5 — Test single sign-on

1. Open a private/incognito window and visit your TrueFoundry login page.
2. Click **Login with Keycloak** (or whichever button label you chose under **Show advanced fields → Button Text**).
3. Authenticate with a Keycloak user from the federated realm.

You should land in the TrueFoundry dashboard. New users are created automatically if [JIT provisioning](/docs/platform/user-management#user-provisioning) is enabled; otherwise the user must already exist in TrueFoundry or be invited.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Failed to discover endpoints' or HTTP 404 on the issuer">
    The realm name in the **Issuer URL** is wrong, or your Keycloak still uses the `/auth` prefix. Open `https://<keycloak-host>/realms/<realm-name>/.well-known/openid-configuration` in a browser:

    * If it returns JSON, copy the `issuer` field verbatim into TrueFoundry.
    * If you get a 404, try `https://<keycloak-host>/auth/realms/<realm-name>/.well-known/openid-configuration` and use that prefix instead.
  </Accordion>

  <Accordion title="'Invalid redirect_uri' from Keycloak">
    The exact URL `https://login.truefoundry.com/oauth2/callback` is missing from **Valid Redirect URIs** on the Keycloak client. Add it under **Clients → your client → Settings**, save, and retry.
  </Accordion>

  <Accordion title="'Failed to decrypt ID token' / 'unsupported algorithm RSA-OAEP'">
    Your realm is issuing tokens encrypted with `RSA-OAEP`, which TrueFoundry does not support. Follow the steps in the [encryption algorithm restrictions](#encryption-algorithm-restrictions) section above to disable the `RSA-OAEP` key provider, leaving only supported algorithms enabled.
  </Accordion>

  <Accordion title="'Invalid client credentials'">
    The **Client Secret** in TrueFoundry doesn't match Keycloak. Regenerate the secret on the client's **Credentials** tab, copy the new value, and update the SSO configuration under **Settings → Security & Access → SSO**.
  </Accordion>

  <Accordion title="Sign-in works but the user's email is empty">
    Make sure the **email** scope is being requested and that the user has an email in Keycloak. In the TrueFoundry SSO form, set **Scopes** to `openid email profile` and re-test. If you map email under a non-standard claim, expand **Show advanced fields** and set **Email Claim** accordingly.
  </Accordion>
</AccordionGroup>