> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.
# OIDC
> OpenID Connect authentication setup
Configure Onyx with OpenID Connect (OIDC) authentication.
Available with common identity providers such as Okta and Microsoft Entra ID (Azure AD).
OIDC providers are managed at **Admin Panel** → **Organization** → [SSO
Providers](/deployment/authentication/sso_providers). No environment variables or restarts are needed,
and you can configure multiple providers (enabling more than one at the same time requires the Business plan,
see [Plan Availability](/deployment/authentication/sso_providers#plan-availability)).
This guide walks through the setup for Okta. Other identity providers follow a similar process.
Please contact us if you need help with a different identity provider.
## Guide
Navigate to the Okta **Admin Console** → **Applications** → **Create App Integration**.
Select **OIDC** and **Web Application**.
Name your application `Onyx`.
If you are white-labeling Onyx, you can freely name your application.
Add a **Sign-in redirect URI** using the name you will give the provider in Onyx (a lowercase slug, e.g. `okta`):
```
https://YOUR_ONYX_DOMAIN.com/api/auth/oidc/YOUR_PROVIDER_NAME/callback
```
Determine whether all users or select groups may access Onyx or skip this step and assign users later.
Create the new Application and save the **Client ID** and **Client Secret**.
Also note your **Okta Base URL** in the format of `https://.okta.com`.
After saving your application,
you can upload the Onyx logo or your white-labeled logo by clicking the gear icon next to the app title **Onyx**
Navigate to **Admin Panel** → **Organization** → [SSO Providers](/deployment/authentication/sso_providers)
and click **Add Provider**.
Select the **OIDC** provider type, enter the **Name** you used in the redirect URI, and paste the **Client ID**,
**Client Secret**, and the OpenID configuration URL:
```
https:///.well-known/openid-configuration
```
After creating the provider, its row shows the exact **Redirect URI**.
Confirm it matches what you registered in Okta, then sign in through the new option on the login page.
## Customizing requested scopes
By default, Onyx uses the standard OIDC base scopes when redirecting users to the identity provider.
Overriding the list is primarily useful when the access token issued at login should be passed through to tool calls
that need additional scopes from the identity provider.
Starting in `v4.5`, set **Scopes** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**)
to override the list per provider. A provider's **Scopes** take precedence. When left empty,
the deployment-wide environment variable applies, then the built-in defaults.
On `v4.4.x`, the only override is the deployment-wide `OIDC_SCOPE_OVERRIDE` environment variable,
a comma-separated list that applies to every OIDC provider:
```bash .env theme={null}
OIDC_SCOPE_OVERRIDE=openid,email,profile,groups
```
Onyx will always also request `offline_access` so refresh tokens are issued, even if it is not in the override list.
The override **replaces** the default scopes — make sure `openid`, `email`,
and `profile` are still included if you want standard login to keep working.
Any scopes you add here must also be enabled on the application in your identity provider.
Onyx only changes what is sent in the authorize request;
the IdP still rejects scopes that are not configured for the client.
## Enabling PKCE
PKCE is disabled by default to preserve backwards compatibility with existing OIDC deployments.
Starting in `v4.5`,
turn on **Enable PKCE** on the provider entry (**Admin Panel** → **Organization** → **SSO Providers**).
On `v4.4.x`, the deployment-wide `OIDC_PKCE_ENABLED` environment variable enables it for all providers:
```bash .env theme={null}
OIDC_PKCE_ENABLED=true
```
`OIDC_PKCE_ENABLED=true` forces PKCE on for every provider, including providers whose **Enable PKCE** toggle is off.
Unset it if you want the per-provider toggles to be the source of truth.
## Upgrading from v4.3 or Earlier
Versions before `v4.4.0` configured a single OIDC provider through environment variables,
using the redirect URI `https://YOUR_ONYX_DOMAIN.com/auth/oidc/callback`.
On `v4.4.0` and later these variables no longer enable OIDC login, and they are planned for full removal in `v4.5`.
New installs must use the admin panel flow above.
When you upgrade an existing deployment,
its environment-based configuration is imported into an SSO provider entry automatically,
and existing logins keep working. The import runs once, when the upgrade first runs against your existing database,
so keep the configuration in place through the upgrade.
The migrated provider keeps using the redirect URI already registered with your IdP,
so nothing changes on the IdP side. Once the migrated provider appears in the admin panel,
sign-ins and token refresh use the provider entry's credentials, and `AUTH_TYPE`, `OAUTH_CLIENT_ID`,
`OAUTH_CLIENT_SECRET`, and `OPENID_CONFIG_URL` can be removed.
The variables only act as a fallback for login accounts that no provider entry matches,
such as after deleting or renaming the migrated provider.
For reference, a pre-`v4.4.0` configuration looks like:
```bash .env theme={null}
AUTH_TYPE=oidc
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OPENID_CONFIG_URL=https:///.well-known/openid-configuration
```
```bash values.yaml theme={null}
auth:
secrets:
OAUTH_CLIENT_ID:
OAUTH_CLIENT_SECRET:
configMap:
AUTH_TYPE: oidc
OPENID_CONFIG_URL: https:///.well-known/openid-configuration
```