✨ SSO for Admin UI

:::info From v1.76.0, SSO is now Free for up to 5 users. :::

:::info

✨ SSO is on LiteLLM Enterprise

Enterprise Pricing

Get free 7-day trial key

:::

Usage (Google, Microsoft, Okta, etc.)

Step 1: Create an OIDC Application in Okta

In your Okta Admin Console, create a new OIDC Web Application. See Okta's guide on creating OIDC app integrations for detailed instructions.

When configuring the application:

• Sign-in redirect URI: https://<your-proxy-base-url>/sso/callback
• Sign-out redirect URI (optional): https://<your-proxy-base-url>

After creating the app, copy your Client ID and Client Secret from the application's General tab:

Step 2: Assign Users to the Application

Ensure users are assigned to the app in the Assignments tab. If Federation Broker Mode is enabled, you may need to disable it to assign users manually.

Step 3: Set Environment Variables

Set the following environment variables. The only difference between the two Okta authorization servers is the endpoint URLs:

Org Authorization Server (available on all Okta plans, no additional SKU required):

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"

Custom Authorization Server (requires the Okta API Access Management SKU):

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"

:::tip You can find all OAuth endpoints at https://<your-okta-domain>/.well-known/openid-configuration :::

Step 3a: Configure Access Policy (Custom Authorization Server only)

If you are using the Custom Authorization Server, you must configure an Access Policy. Without it, users will get a no_matching_policy error. Skip this step if you are using the Org Authorization Server.

1. Go to Security → API

2. Select the default authorization server (or your custom one)

3. Click on Access Policies tab, create a new policy assigned to your LiteLLM app

4. Add a rule that allows the Authorization Code grant type

See Okta's Access Policy documentation for more details.

Step 4: Configure Okta Security Settings

GENERIC_CLIENT_STATE is recommended for Okta to prevent CSRF attacks:

GENERIC_CLIENT_STATE="random-string"

PKCE (Proof Key for Code Exchange) — If your Okta application is configured to require PKCE, enable it by setting:

GENERIC_CLIENT_USE_PKCE="true"

LiteLLM will automatically handle PKCE parameter generation and verification during the OAuth flow.

Step 5: Test the SSO Flow

1. Start your LiteLLM proxy
2. Navigate to https://<your-proxy-base-url>/ui
3. Click the SSO login button
4. Authenticate with Okta and verify you're redirected back to LiteLLM

Troubleshooting

• Create a new Oauth 2.0 Client on https://console.cloud.google.com/

Required .env variables on your Proxy

# for Google SSO Login
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

• Set Redirect URL on your Oauth 2.0 Client on https://console.cloud.google.com/

  • Set a redirect url = <your proxy base url>/sso/callback

  https://litellm-production-7002.up.railway.app/sso/callback
  

• Create a new App Registration on https://portal.azure.com/

• Create a client Secret for your App Registration

Required .env variables on your Proxy

MICROSOFT_CLIENT_ID="84583a4d-"
MICROSOFT_CLIENT_SECRET="nbk8Q~"
MICROSOFT_TENANT="5a39737"

Optional: Custom Microsoft SSO Endpoints

If you need to use custom Microsoft SSO endpoints (e.g., for a custom identity provider, sovereign cloud, or proxy), you can override the default endpoints:

MICROSOFT_AUTHORIZATION_ENDPOINT="https://your-custom-url.com/oauth2/v2.0/authorize"
MICROSOFT_TOKEN_ENDPOINT="https://your-custom-url.com/oauth2/v2.0/token"
MICROSOFT_USERINFO_ENDPOINT="https://your-custom-graph-api.com/v1.0/me"

If these are not set, the default Microsoft endpoints are used based on your tenant.

• Set Redirect URI on your App Registration on https://portal.azure.com/
  • Set a redirect url = <your proxy base url>/sso/callback

  http://localhost:4000/sso/callback
  

Using App Roles for User Permissions

You can assign user roles directly from Entra ID using App Roles. LiteLLM will automatically read the app roles from the JWT token and assign the corresponding role to the user.

Supported roles:

• proxy_admin - Admin over the platform
• proxy_admin_viewer - Can login, view all keys, view all spend (read-only)
• internal_user - Normal user. Can login, view spend and depending on team-member permissions - view/create/delete their own keys.

To set up app roles:

1. Navigate to your App Registration on https://portal.azure.com/
2. Go to "App roles" and create a new app role
3. Use one of the supported role names above (e.g., proxy_admin)
4. Assign users to these roles in your Enterprise Application
5. When users sign in via SSO, LiteLLM will automatically assign them the corresponding role

Advanced: Custom User Attribute Mapping

For certain Microsoft Entra ID configurations, you may need to override the default user attribute field names. This is useful when your organization uses custom claims or non-standard attribute names in the SSO response.

Step 1: Debug SSO Response

First, inspect the JWT fields returned by your Microsoft SSO provider using the SSO Debug Route.

1. Add /sso/debug/callback as a redirect URL in your Azure App Registration
2. Navigate to https://<proxy_base_url>/sso/debug/login
3. Complete the SSO flow to see the returned user attributes

Step 2: Identify Field Attribute Names

From the debug response, identify the field names used for email, display name, user ID, first name, and last name.

Step 3: Set Environment Variables

Override the default attribute names by setting these environment variables:

Step 4: Restart the Proxy

After setting the environment variables, restart the proxy:

litellm --config /path/to/config.yaml

A generic OAuth client that can be used to quickly create support for any OAuth provider with close to no code

Required .env variables on your Proxy

GENERIC_CLIENT_ID = "******"
GENERIC_CLIENT_SECRET = "G*******"
GENERIC_AUTHORIZATION_ENDPOINT = "http://localhost:9090/auth"
GENERIC_TOKEN_ENDPOINT = "http://localhost:9090/token"
GENERIC_USERINFO_ENDPOINT = "http://localhost:9090/me"

Optional .env variables The following can be used to customize attribute names when interacting with the generic OAuth provider. We will read these attributes from the SSO Provider result

GENERIC_USER_ID_ATTRIBUTE = "given_name"
GENERIC_USER_EMAIL_ATTRIBUTE = "family_name"
GENERIC_USER_DISPLAY_NAME_ATTRIBUTE = "display_name"
GENERIC_USER_FIRST_NAME_ATTRIBUTE = "first_name"
GENERIC_USER_LAST_NAME_ATTRIBUTE = "last_name"
GENERIC_USER_ROLE_ATTRIBUTE = "given_role"
GENERIC_USER_PROVIDER_ATTRIBUTE = "provider"
GENERIC_USER_EXTRA_ATTRIBUTES = "department,employee_id,manager" # comma-separated list of additional fields to extract from SSO response
GENERIC_CLIENT_STATE = "some-state" # if the provider needs a state parameter
GENERIC_INCLUDE_CLIENT_ID = "false" # some providers enforce that the client_id is not in the body
GENERIC_SCOPE = "openid profile email" # default scope openid is sometimes not enough to retrieve basic user info like first_name and last_name located in profile scope

Assigning User Roles via SSO

Use GENERIC_USER_ROLE_ATTRIBUTE to specify which attribute in the SSO token contains the user's role. The role value must be one of the following supported LiteLLM roles:

• proxy_admin - Admin over the platform
• proxy_admin_viewer - Can login, view all keys, view all spend (read-only)
• internal_user - Can login, view/create/delete their own keys, view their spend
• internal_user_view_only - Can login, view their own keys, view their own spend

Nested attribute paths are supported (e.g., claims.role or attributes.litellm_role).

Capturing Additional SSO Fields

Use GENERIC_USER_EXTRA_ATTRIBUTES to extract additional fields from the SSO provider response beyond the standard user attributes (id, email, name, etc.). This is useful when you need to access custom organization-specific data (e.g., department, employee ID, groups) in your custom SSO handler.

# Comma-separated list of field names to extract
GENERIC_USER_EXTRA_ATTRIBUTES="department,employee_id,manager,groups"

Accessing Extra Fields in Custom SSO Handler:

from litellm.proxy.management_endpoints.types import CustomOpenID

async def custom_sso_handler(userIDPInfo: CustomOpenID):
    # Access the extra fields
    extra_fields = getattr(userIDPInfo, 'extra_fields', None) or {}
    
    user_department = extra_fields.get("department")
    employee_id = extra_fields.get("employee_id")
    user_groups = extra_fields.get("groups", [])
    
    # Use these fields for custom logic (e.g., team assignment, access control)
    # ...

Nested Field Paths:

Dot notation is supported for nested fields:

GENERIC_USER_EXTRA_ATTRIBUTES="org_info.department,org_info.cost_center,metadata.employee_type"

• Set Redirect URI, if your provider requires it
  • Set a redirect url = <your proxy base url>/sso/callback

  http://localhost:4000/sso/callback
  

Default Login, Logout URLs

Some SSO providers require a specific redirect url for login and logout. You can input the following values.

• Login: <your-proxy-base-url>/sso/key/generate
• Logout: <your-proxy-base-url>

Here's the env var to set the logout url on the proxy

PROXY_LOGOUT_URL="https://www.google.com"

Step 3. Set PROXY_BASE_URL in your .env

Set this in your .env (so the proxy can set the correct redirect url)

PROXY_BASE_URL=https://litellm-api.up.railway.app

Step 4. Test flow

Restrict Email Subdomains w/ SSO

If you're using SSO and want to only allow users with a specific subdomain - e.g. (@berri.ai email accounts) to access the UI, do this:

This will check if the user email we receive from SSO contains this domain, before allowing access.

Set Proxy Admin

Set a Proxy Admin when SSO is enabled. Once SSO is enabled, the user_id for users is retrieved from the SSO provider. In order to set a Proxy Admin, you need to copy the user_id from the UI and set it in your .env as PROXY_ADMIN_ID.

Step 1: Copy your ID from the UI

Step 2: Set it in your .env as the PROXY_ADMIN_ID

This will update the user role in the LiteLLM_UserTable to proxy_admin.

If you plan to change this ID, please update the user role via API /user/update or UI (Internal Users page).

Step 3: See all proxy keys

:::info

If you don't see all your keys this could be due to a cached token. So just re-login and it should work.

:::

Disable Default Team on Admin UI

Use this if you want to hide the Default Team on the Admin UI

The following logic will apply

• If team assigned don't show Default Team
• If no team assigned then they should see Default Team

Set default_team_disabled: true on your litellm config.yaml

general_settings:
  master_key: sk-1234
  default_team_disabled: true # OR you can set env var PROXY_DEFAULT_TEAM_DISABLED="true"

Use Username, Password when SSO is on

If you need to access the UI via username/password when SSO is on navigate to /fallback/login. This route will allow you to sign in with your username/password credentials.

Restrict UI Access

You can restrict UI Access to just admins - includes you (proxy_admin) and people you give view only access to (proxy_admin_viewer) for seeing global spend.

Step 1. Set 'admin_only' access

general_settings:
    ui_access_mode: "admin_only"

Step 2. Invite view-only users

Custom Branding Admin UI

Use your companies custom branding on the LiteLLM Admin UI We allow you to

• Customize the UI Logo
• Customize the UI color scheme <Image img={require('../../img/litellm_custom_ai