> ## Documentation Index
> Fetch the complete documentation index at: https://odigos-dependabot-npm-and-yarn-docs-mintlify-4-2-866.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Configure authentication for Odigos Central using OIDC or SAML identity providers, including production ingress setup.

Odigos Central includes a bundled **Keycloak** instance as its identity provider. Keycloak is **not exposed externally** — the Central Backend acts as a reverse proxy, forwarding authentication requests (`/realms/*` and `/resources/*`) to Keycloak internally. This means you only need to expose the Central Backend and Central UI; no separate ingress or service is needed for Keycloak.

Odigos Central supports two types of external SSO providers:

* **OIDC** — for providers like Azure AD, Auth0, or any OpenID Connect-compatible IdP
* **SAML** — for providers like Okta that use SAML 2.0

Both are configured through the Central UI — Odigos will create the required Keycloak configuration automatically.

<Note>
  Helm `auth.adminUsername` and `auth.adminPassword` are the Keycloak master admin used by `central-backend`. They are not Central UI login credentials. Sign in with SSO (the first SSO user becomes an admin) or with users created in the UI. See [Troubleshooting](/central/troubleshooting#admin-credentials-vs-central-ui-login).
</Note>

## Configuring the External URL

For SSO redirects to work, Keycloak and the Central Backend must know the **browser-accessible URL** of the Central Backend. This is set via the `auth.externalUrl` Helm value. The Central UI URL used for OAuth `redirect_uri` (`/signin`) is configured separately via `auth.externalUIUrl` when it differs from the backend URL (e.g. local port-forward).

| Environment              | `auth.externalUrl` value           | `auth.externalUIUrl` value     |
| ------------------------ | ---------------------------------- | ------------------------------ |
| Local dev / port-forward | `http://localhost:8081` (default)  | `http://localhost:3000` (auto) |
| Ingress with HTTPS       | `https://central.example.com`      | same as `externalUrl` (auto)   |
| LoadBalancer service     | `https://central-lb.prod.internal` | same as `externalUrl` (auto)   |

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    odigos pro central install \
      --set onPremToken=<token> \
      --set auth.externalUrl=https://central.example.com
    ```
  </Tab>

  <Tab title="Helm">
    ```yaml theme={null}
    auth:
      externalUrl: "https://central.example.com"
    ```

    Or via `--set`:

    ```bash theme={null}
    helm upgrade --install odigos-central odigos/odigos-central \
      --namespace odigos-central \
      --create-namespace \
      --set onPremToken=<token> \
      --set auth.externalUrl=https://central.example.com
    ```
  </Tab>
</Tabs>

<Info>
  When `auth.externalUrl` is empty (the default), it falls back to `http://localhost:8081`, which works for local development with `odigos pro central ui` port-forwarding.
</Info>

## OIDC Provider Setup (Azure AD, Auth0, etc.)

<Steps>
  <Step title="Create the OIDC Identity Provider in the Central UI">
    Open the Central UI sign-in page, choose your OIDC provider (e.g., Azure AD), and fill in:

    * **Client ID** — from your IdP application
    * **Client Secret** — from your IdP application
    * **Discovery URL** — your IdP's OpenID Connect discovery endpoint
    * **Tenant ID** — required for Azure AD (Entra ID)

    <Info>
      Odigos Central will create/update the required configuration in the bundled Keycloak for you. Avoid configuring the identity provider directly in Keycloak unless you're troubleshooting.
    </Info>
  </Step>

  <Step title="Copy the Callback URL">
    After the provider is created successfully, the Central UI will display a **Callback URL**. Copy this URL and add it to your IdP application settings as the **Redirect URI** (or **Callback URL**).

    <Warning>
      The Login button is disabled until you copy the Callback URL. This ensures you configure your IdP correctly before attempting to sign in.
    </Warning>
  </Step>

  <Step title="Sign in via your OIDC provider">
    Click the **Login** button. You will be redirected to your IdP's sign-in page. After authenticating, you will be redirected back to Odigos Central and the first user account will be created as the admin.
  </Step>
</Steps>

<Info>
  To grant roles automatically based on Azure AD group membership, see [Role Mappings](./role-mappings).
</Info>

### Azure AD (Entra ID) network access

Keycloak must reach Microsoft from inside the cluster. Allow egress to at least:

* `login.microsoftonline.com` — authorization, token, JWKS, and OpenID discovery
* `graph.microsoft.com` — OIDC userinfo

Also allow any tenant-specific discovery or token URLs you configure. If domains are blocked, or the Entra app lacks permissions, Keycloak often shows only `couldNotSendAuthenticationRequestMessage` with no error class. See [Troubleshooting](/central/troubleshooting#azure-oauth).

## SAML Provider Setup (Okta, etc.)

<Steps>
  <Step title="Create the SAML Identity Provider in the Central UI">
    Open the Central UI sign-in page, choose SAML, and fill in the IdP details from your SAML provider:

    * **IdP Entity ID / Issuer**
    * **Single Sign-On Service URL**
    * **X.509 Signing Certificate**

    <Info>
      Odigos Central will create/update the required configuration in the bundled Keycloak for you. Avoid configuring the identity provider directly in Keycloak unless you're troubleshooting.
    </Info>
  </Step>

  <Step title="Copy the Callback URL (ACS URL)">
    After the provider is created, the Central UI will display the **Callback URL (ACS URL)**. Copy this URL and configure it in your SAML provider:

    * **Single sign-on URL** (ACS URL)
    * **Audience URI (SP Entity ID)** — use the same URL or the realm URL depending on your provider

    <Warning>
      The Login button is disabled until you copy the Callback URL. Make sure to add it to your SAML application before proceeding.
    </Warning>
  </Step>

  <Step title="Sign in via your SAML provider">
    Click the **Login with SAML** button. You will be redirected to your IdP's sign-in page. After authenticating, you will be redirected back to Odigos Central and the first user account will be created as the admin.
  </Step>
</Steps>

## Production Ingress Configuration

When deploying behind an ingress, route traffic to the Central Backend and Central UI services only. Keycloak does **not** need its own ingress — the Central Backend handles `/realms/*` and `/resources/*` internally.

`/resources/*` serves Keycloak theme and static assets (login page CSS, JS, and images). Browsers request it during sign-in; if it is routed to `central-ui`, login pages break.

Example routing (single hostname, path-based):

| Path        | Service           | Port | Notes                                                                                |
| ----------- | ----------------- | ---- | ------------------------------------------------------------------------------------ |
| `/`         | `central-ui`      | 3000 | Central UI. Next.js also rewrites some API paths when the request hits this service. |
| `/graphql`  | `central-backend` | 8081 | GraphQL API                                                                          |
| `/api/*`    | `central-backend` | 8081 | Sign-in / sign-out helpers                                                           |
| `/realms/*` | `central-backend` | 8081 | Keycloak OIDC/SAML (proxied)                                                         |

<Warning>
  The WebSocket path is `/ws/proxy`, not `/wss/proxy`. `wss` is the TLS **scheme**. Central Proxy uses `wss` when the backend URL host ends with `:443`; otherwise it uses `ws`. Enable WebSocket upgrades (HTTP `Upgrade`) on this path.
</Warning>

Set `auth.externalUrl` (and `auth.externalUIUrl` if the UI origin differs) to the public HTTPS URL of this hostname. Remote clusters should set `centralProxy.centralBackendURL` to the same reachable backend URL. See [Architecture](/central/architecture#backend-urls-helm-values) and [Connecting Remote Clusters](/central/adding-connections/remote-clusters).

<Info>
  If you're looking to enable OIDC for the **non-central** Odigos UI (not Odigos
  Central), see the dedicated OIDC documentation: [`OIDC (OpenID
      Connect)`](../../enterprise/features/oidc).
</Info>