How do we integrate BerriAI / LiteLLM Enterprise with Okta or Azure Entra ID for SSO/SCIM and role mapping?

Integrating BerriAI / LiteLLM Enterprise with Okta or Azure Entra ID lets you centralize authentication, automate user lifecycle with SCIM, and enforce role‑based access control across your AI infrastructure. Below is a practical, step‑by‑step guide to connect your identity provider (IdP) for SSO/SCIM and map roles and permissions correctly.

---

Key concepts for SSO, SCIM, and role mapping

Before configuring anything in Okta or Azure Entra ID, clarify these concepts in the context of BerriAI / LiteLLM Enterprise:

• SSO (Single Sign-On)
  Users authenticate via Okta or Azure Entra ID instead of local passwords. Typically implemented via:

  • SAML 2.0, or
  • OIDC (OpenID Connect) on top of OAuth2.

• SCIM (System for Cross-domain Identity Management)
  Used for automatic provisioning and deprovisioning:

  • Create users in BerriAI / LiteLLM when they’re assigned the app in Okta/Entra.
  • Update attributes (name, email, groups).
  • Deactivate or delete accounts when they’re removed from the IdP.

• Role mapping
  Mapping IdP attributes (groups, roles, or claims) to BerriAI / LiteLLM Enterprise roles, for example:

  • admin, owner
  • developer, editor
  • viewer, read-only

  You typically map:

  • Okta: Groups or custom attributes in the SAML/OIDC assertion.
  • Entra ID: Security groups, Microsoft 365 groups, or app roles in the token/claims.

---

High‑level integration workflow

1. Decide on SSO protocol (SAML or OIDC) and IdP (Okta or Azure Entra ID).
2. Create an enterprise application for BerriAI / LiteLLM Enterprise in your IdP.
3. Configure SSO on both IdP and BerriAI / LiteLLM (redirect URLs, certificates, metadata).
4. Configure SCIM (optional but recommended) to sync users and groups.
5. Define roles, groups, and mapping rules to enforce access control.
6. Test with a pilot group, then roll out to production.

---

Prerequisites

You’ll need:

• A running BerriAI / LiteLLM Enterprise instance with:
  • Admin access to its settings or tenant configuration.
  • The SSO/SCIM endpoints and API base URL (e.g., https://your-litellm-tenant.example.com).
• An Okta or Azure Entra ID tenant with:
  • Permissions to manage enterprise applications.
  • Ability to configure SAML/OIDC and SCIM.
• A plan for roles and access model:
  • Which users are admins?
  • Which groups should have read/write vs. read‑only access?
  • Should environments (e.g., prod vs. dev) map to different roles or groups?

---

Option 1: Integrate with Okta

1. Create an Okta SSO application

1. In Okta Admin:
   • Go to Applications → Applications → Create App Integration.
2. Choose:
   • Sign-in method:
     • SAML 2.0, or
     • OIDC - OpenID Connect.
   • Application type: Web.
3. Name the application, e.g., BerriAI / LiteLLM Enterprise.

SAML configuration fields (Okta → BerriAI / LiteLLM)

If using SAML:

• Single sign-on URL:
  Use your SAML ACS endpoint from BerriAI / LiteLLM Enterprise, e.g.:
  https://your-litellm-tenant.example.com/auth/saml/acs
• Audience URI (SP Entity ID):
  Use the entity ID from BerriAI / LiteLLM, e.g.:
  https://your-litellm-tenant.example.com/auth/saml/metadata
• Name ID format: EmailAddress (commonly used).
• Application username: Email or Okta username, matched to the LiteLLM user identity.

Add custom attribute statements to include user details and group claims, for example:

Name	Name format	Value	Purpose
email	Unspecified	${user.email}	Primary identifier
name	Unspecified	${user.firstName} ${user.lastName}	Display name
groups	Unspecified	getFilteredGroups("litellm_*")	Role mapping via groups

Adjust group filtering as needed (e.g., only groups with prefix litellm_).

OIDC configuration fields (Okta → BerriAI / LiteLLM)

If using OIDC:

• Login redirect URIs:
  https://your-litellm-tenant.example.com/auth/oidc/callback
• Logout redirect URIs (optional):
  https://your-litellm-tenant.example.com/logout
• Under Assignments, assign the app to users or groups who should access BerriAI / LiteLLM.
• Note the Client ID, Client secret, and Okta issuer URL (e.g. https://your-org.okta.com/oauth2/default).

2. Configure SSO in BerriAI / LiteLLM Enterprise

In the LiteLLM enterprise admin settings:

1. Go to Authentication / SSO.

2. Choose provider:

   • SAML (for Okta SAML) or
   • OIDC (for Okta OIDC).

3. Enter Okta details:

   For SAML:

   • IdP Entity ID: from Okta SAML setup.
   • IdP SSO URL: e.g. https://your-org.okta.com/app/.../sso/saml.
   • IdP Certificate: paste the X.509 certificate.
   • Default role for new users (e.g., viewer).

   For OIDC:

   • Issuer URL: https://your-org.okta.com/oauth2/default
   • Client ID / Client Secret: from Okta app.
   • Scopes: typically openid profile email groups.
   • Claim keys for email, name, groups (e.g. email, name, groups).

4. Save and test the connection:

   • Use a test user to verify login.
   • Confirm user profile and groups are visible in LiteLLM.

3. Configure SCIM provisioning in Okta

1. In Okta, open the BerriAI / LiteLLM Enterprise app.

2. Go to Provisioning tab.

3. Configure SCIM:

   • SCIM connector base URL:
     https://your-litellm-tenant.example.com/scim/v2
   • Authentication:
     • Typically Bearer Token generated from LiteLLM (e.g., an SCIM API token).
   • Enable:
     • Create Users
     • Update User Attributes
     • Deactivate Users

4. Map attributes:

   Okta Attribute	SCIM Attribute
   userName	userName
   givenName	name.givenName
   familyName	name.familyName
   email	emails[type eq "work"].value

5. (Optional) Map groups to SCIM Groups:

   • Use Okta groups like litellm_admin, litellm_dev, litellm_viewer.
   • Configure group push to LiteLLM SCIM groups.

4. Role mapping using Okta groups and claims

A typical pattern for role mapping:

1. In Okta, create groups:
   • litellm_admin
   • litellm_developer
   • litellm_viewer
2. Assign users to these groups.
3. In the Okta app’s SAML/OIDC configuration:
   • Include groups claim with only litellm_* groups.
4. In LiteLLM Enterprise SSO / Role Mapping settings:
   • Define rules:
     • If groups contains litellm_admin → assign admin role.
     • If groups contains litellm_developer → assign developer role.
     • If groups contains litellm_viewer → assign viewer role.
   • Decide how to handle:
     • Conflicts (user in multiple groups).
     • Users with no matching group (default to viewer, or deny access).

---

Option 2: Integrate with Azure Entra ID (Azure AD)

1. Register an enterprise application

1. In Azure portal:
   • Go to Azure Active Directory (Entra ID) → Enterprise applications → New application.
2. Select:
   • Create your own application.
   • Optionally, choose Integrate any other application you don’t find in the gallery (Non‑gallery).
3. Name it, e.g., BerriAI / LiteLLM Enterprise, and create.

2. Configure SAML SSO in Azure Entra ID

1. In the newly created app:

   • Go to Single sign-on and choose SAML.

2. Basic SAML Configuration:

   • Identifier (Entity ID):
     e.g. https://your-litellm-tenant.example.com/auth/saml/metadata
   • Reply URL (Assertion Consumer Service URL):
     e.g. https://your-litellm-tenant.example.com/auth/saml/acs
   • Sign-on URL (optional):
     https://your-litellm-tenant.example.com/login

3. User Attributes & Claims:

   • Keep Name ID as Email (or UPN, depending on your setup).
   • Add claims:
     • email → user.mail or user.userprincipalname
     • name → user.displayname
     • groups → Choose Groups assigned to the application; optionally set to Security groups.
       • If token size is a concern, use Group ID or app roles instead.

4. Download Federation Metadata XML or note:

   • Login URL, Azure AD Identifier (Entity ID), and Certificate (Base64).

3. Configure OIDC (alternative to SAML)

If LiteLLM Enterprise supports OIDC with Entra ID:

1. In App registrations:
   • Register an app for LiteLLM if not already done.
2. Configure:
   • Redirect URI (web):
     https://your-litellm-tenant.example.com/auth/oidc/callback
   • Expose necessary API permissions (usually default openid profile email).
3. In LiteLLM Enterprise, set:
   • Issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
   • Client ID / Client secret: from app registration.
   • Claim mapping: email, name, groups (or roles).

4. Configure SSO in BerriAI / LiteLLM Enterprise (Entra ID)

In LiteLLM admin settings:

1. Go to Authentication / SSO.

2. Choose Azure Entra ID (or generic SAML/OIDC provider).

3. Enter:

   For SAML:

   • IdP Entity ID: Azure AD Identifier.
   • IdP SSO URL: Login URL from SAML config.
   • Certificate: paste the Base64 certificate.
   • Name ID / email claim mapping.

   For OIDC:

   • Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0
   • Client ID / Client Secret.
   • Define which claims correspond to email and groups.

4. Save and test with a pilot user.

5. Enable SCIM in Azure Entra ID

1. In Entra ID:

   • Go to your BerriAI / LiteLLM Enterprise app.
   • Open Provisioning.

2. Set Provisioning Mode to Automatic.

3. Configure Admin Credentials:

   • Tenant URL:
     https://your-litellm-tenant.example.com/scim/v2
   • Secret Token: SCIM token from LiteLLM Enterprise.

4. Under Mappings:

   • Configure Provision Azure Active Directory Users:

     Azure AD Attribute	SCIM Attribute
     userPrincipalName	userName
     givenName	name.givenName
     surname	name.familyName
     mail	emails[type eq "work"].value

   • Configure Provision Azure Active Directory Groups (optional) to push security groups.

5. Scope provisioning:

   • Restrict to assigned users and groups or a specific subset.

6. Start provisioning and monitor logs for errors.

6. Role mapping using Entra ID groups or app roles

You can use security groups or app roles:

Option A: Use groups

1. Create Entra groups:
   • litellm-admins
   • litellm-developers
   • litellm-viewers
2. Assign users to these groups.
3. In SAML/OIDC claims:
   • Add a claim groups or roles that includes these groups.
4. In LiteLLM:
   • Map litellm-admins → admin role.
   • Map litellm-developers → developer role.
   • Map litellm-viewers → viewer role.

Option B: Use app roles

1. In the app registration:
   • Define App roles: Admin, Developer, Viewer.
2. Assign these app roles to users or groups.
3. Configure Entra ID to emit roles claim in tokens.
4. In LiteLLM Enterprise:
   • Map roles claim values to internal roles:
     • Admin → admin
     • Developer → developer
     • Viewer → viewer

---

Best practices for secure and reliable integration

• Use SCIM wherever possible
  Avoid manual user management; rely on IdP assignment for account lifecycle.
• Least privilege
  Default new users to the lowest role (e.g., viewer) unless a group/role maps to higher privileges.
• Group naming conventions
  Use clear prefixes (e.g., litellm_) to distinguish app‑specific groups from global ones.
• Test with a pilot group
  Start with a dedicated test group before rolling out organization‑wide.
• Audit regularly
  • Review who is in admin and developer groups.
  • Confirm deprovisioned users are removed promptly by SCIM.
• Document your mapping
  Maintain a simple matrix showing:
  • IdP groups → App roles
  • IdP environment (prod/dev) → App environment or workspace.

---

Troubleshooting common issues

• User cannot log in via SSO

  • Check SAML/OIDC URLs and entity IDs.
  • Confirm user is assigned to the Okta/Entra application.
  • Verify that email/NameID matches the expected identifier in LiteLLM.

• Groups/roles not applied

  • Inspect the SAML assertion or JWT to confirm groups/roles claims exist.
  • Check LiteLLM Enterprise role mapping rules.
  • Confirm the user is in the correct IdP group or app role.

• Provisioning errors with SCIM

  • Verify SCIM base URL and token.
  • Check attribute mappings for unsupported fields.
  • Use IdP provisioning logs to identify specific failures.

---

Summary: choosing between Okta and Azure Entra ID for LiteLLM SSO/SCIM

• Okta:

  • Straightforward app integration flow.
  • Flexible group filters (getFilteredGroups) for role mapping.
  • Mature SCIM support and detailed provisioning logs.

• Azure Entra ID:

  • Strong integration if your org is already on Microsoft 365.
  • App roles and security groups give fine‑grained control.
  • SCIM provisioning integrates directly into Entra’s enterprise apps.

In both cases, integrating BerriAI / LiteLLM Enterprise with Okta or Azure Entra ID for SSO/SCIM and role mapping comes down to aligning identity claims (email, groups, roles) with the internal role model of LiteLLM and using SCIM to keep users and access in sync automatically.