Authentication

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.

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.

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)

CLI
Helm

odigos pro central install \
  --set onPremToken=<token> \
  --set auth.externalUrl=https://central.example.com

auth:
  externalUrl: "https://central.example.com"

Or via --set:

helm upgrade --install odigos-central odigos/odigos-central \
  --namespace odigos-central \
  --create-namespace \
  --set onPremToken=<token> \
  --set auth.externalUrl=https://central.example.com

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.

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

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)

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.

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).

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

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.

To grant roles automatically based on Azure AD group membership, see Role Mappings.

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.

SAML Provider Setup (Okta, etc.)

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

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.

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

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

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.

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)

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.

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 and Connecting Remote Clusters.

If you’re looking to enable OIDC for the non-central Odigos UI (not Odigos Central), see the dedicated OIDC documentation: OIDC (OpenID Connect).

​Configuring the External URL

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

​Azure AD (Entra ID) network access

​SAML Provider Setup (Okta, etc.)

​Production Ingress Configuration

Configuring the External URL

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

Azure AD (Entra ID) network access

SAML Provider Setup (Okta, etc.)

Production Ingress Configuration