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 identity, automate user lifecycle via SCIM, and map groups or attributes to roles and permissions in your AI stack. This guide walks through the core patterns, configuration steps, and best practices to connect BerriAI / LiteLLM Enterprise to Okta or Azure Entra ID for secure SSO, SCIM provisioning, and robust role mapping.

---

Overview: What you’ll set up

When you integrate BerriAI / LiteLLM Enterprise with Okta or Azure Entra ID, you typically configure three layers:

1. SSO (Single Sign-On)

   • Use SAML 2.0 or OIDC to authenticate users via Okta or Entra.
   • Enforce company-wide security (MFA, device posture, conditional access).

2. SCIM (User and Group Provisioning)

   • Automatically create, update, and deactivate accounts in BerriAI / LiteLLM Enterprise.
   • Sync group membership from your IdP to control access at scale.

3. Role Mapping

   • Map IdP groups or claims (e.g., app_admins, ml_team, read_only) to LiteLLM roles and permissions.
   • Ensure that least-privilege access is consistently enforced.

The exact UI labels may differ between BerriAI and LiteLLM Enterprise consoles, but the architecture and steps are similar.

---

Prerequisites

Before you start integrating Okta or Azure Entra ID with BerriAI / LiteLLM Enterprise, make sure you have:

• BerriAI / LiteLLM Enterprise
  • Enterprise plan or self-hosted deployment with:
    • Admin access to the application dashboard
    • Support for SSO (SAML/OIDC) and SCIM (check your version)
• Okta or Azure Entra ID
  • Admin privileges to:
    • Create enterprise applications
    • Configure SSO (SAML or OIDC)
    • Configure SCIM provisioning
    • Manage groups and group assignments
• Network and security
  • Ability to reach the BerriAI / LiteLLM Enterprise URL from your IdP
  • SSL/TLS enabled on your LiteLLM Enterprise instance (HTTPS)
• Role model defined
  • A clear list of roles you want in LiteLLM (e.g., Owner, Admin, Developer, Viewer)
  • Matching IdP groups or claims that will map to these roles

---

Step 1: Decide on SSO protocol (SAML vs OIDC)

Both Okta and Azure Entra ID support SAML and OIDC. BerriAI / LiteLLM Enterprise typically works with either, but your choice should consider:

• SAML

  • Battle-tested for enterprise SSO
  • Supports rich assertion attributes and group-based claims
  • Widely used for SCIM + SAML combination

• OIDC (OpenID Connect)

  • Modern, OAuth 2.0-based
  • Often easier for API-centric platforms
  • Great if you already standardize on OIDC for other SaaS apps

If BerriAI / LiteLLM documentation specifies a preferred protocol, follow that guidance. Otherwise:

• Use SAML if you rely heavily on group-based SSO and SCIM patterns.
• Use OIDC if you have a standardized client configuration for internal enterprise apps.

The next sections outline both SAML and OIDC, so you can adapt to your chosen protocol.

---

Step 2: Configure SSO in BerriAI / LiteLLM Enterprise

2.1 Gather SSO metadata from LiteLLM Enterprise

In the BerriAI / LiteLLM Enterprise admin UI (typical pattern):

1. Go to Settings → Authentication / SSO.
2. Choose your protocol:
   • SAML SSO or OIDC SSO.
3. For SAML, note or download:
   • Assertion Consumer Service (ACS) URL (sometimes called Callback URL)
   • Entity ID / Audience URI
   • SP metadata URL (if available)
4. For OIDC, note:
   • Redirect URI / Callback URL
   • Expected client_id and client_secret placeholders (you’ll fill these after creating an app in Okta/Entra).

Keep this tab open for later when you paste IdP details back into LiteLLM Enterprise.

---

Step 3: Configure Okta SAML SSO

3.1 Create the Okta application

1. In Okta Admin, go to Applications → Applications → Create App Integration.
2. Select:
   • Sign-in method: SAML 2.0
3. Name the app (e.g., LiteLLM Enterprise or BerriAI LiteLLM).
4. Click Next.

3.2 Configure SAML settings

In General Settings:

• Single sign on URL: Paste the LiteLLM ACS URL.
  • Check Use this for Recipient URL and Destination URL (if prompted).
• Audience URI (SP Entity ID): Paste the Entity ID from LiteLLM Enterprise.
• Name ID format: Typically EmailAddress.
• Application username: Usually Email.

3.3 Configure attribute statements

Under Attribute Statements (optional), map Okta user attributes to LiteLLM/BerriAI attributes, for example:

• email → user.email
• name → user.name (or firstName + lastName if LiteLLM supports them)
• groups → user.groups (with Filter: Groups assigned to the application)

Confirm the exact attribute keys expected by BerriAI / LiteLLM Enterprise (e.g., email, full_name, groups) in the product docs and align them.

3.4 Download or copy SAML metadata

Once the app is created:

1. Go to the app’s Sign On tab.
2. Under SAML 2.0, click View Setup Instructions.
3. Copy:
   • Identity Provider Single Sign-On URL
   • Identity Provider Issuer
   • X.509 Certificate
   • Or download the IdP metadata XML file.

---

Step 4: Configure Azure Entra ID SAML SSO

4.1 Create the Enterprise application

1. In Azure portal, go to Azure Active Directory → Enterprise applications.
2. Click New application → Create your own application.
3. Name it (e.g., LiteLLM Enterprise).
4. Choose Integrate any other application you don’t find in the gallery (Non-gallery).
5. Click Create.

4.2 Configure SAML

1. In the app’s overview, go to Single sign-on.
2. Choose SAML.

Under Basic SAML Configuration:

• Identifier (Entity ID): LiteLLM Enterprise Entity ID.
• Reply URL (Assertion Consumer Service URL): LiteLLM ACS URL.
• Sign-on URL (optional): LiteLLM Enterprise login URL, if requested.
• Save your changes.

4.3 User attributes and groups

In User Attributes & Claims, map:

• user.mail → email
• user.displayname → name
• user.groups or custom claims → groups (if you plan to do role mapping via groups)

To send groups:

1. Click Add a group claim.
2. Choose which groups to include (e.g., Groups assigned to the application).
3. Choose claim name (e.g., groups).

4.4 Export IdP metadata

Under SAML Signing Certificate:

• Download Federation Metadata XML, or
• Copy:
  • Login URL / SSO URL
  • Azure AD Identifier (Issuer)
  • Certificate (Base64)

---

Step 5: Configure OIDC SSO (Okta or Azure Entra ID)

If you prefer OIDC instead of SAML, use this high-level pattern.

5.1 Okta OIDC app

1. In Okta Admin, go to Applications → Applications → Create App Integration.
2. Sign-in method: OIDC – OpenID Connect
   Application type: Web or SPA (as recommended by BerriAI / LiteLLM).
3. Enter:
   • Sign-in redirect URI: LiteLLM Enterprise OIDC callback URL.
   • Sign-out redirect URI (optional): LiteLLM logout URL.

After creating the app, note:

• Client ID
• Client Secret
• Issuer / Authorization Server URL (e.g., https://yourdomain.okta.com/oauth2/default)

5.2 Azure Entra ID OIDC app registration

1. Go to Azure Active Directory → App registrations → New registration.
2. Enter name, choose supported account type.
3. Redirect URI: Web → LiteLLM Enterprise OIDC callback URL.
4. After registration:
   • Note the Application (client) ID and Directory (tenant) ID.
   • Create a Client secret under Certificates & secrets.
5. Under Endpoints, note:
   • Authorization endpoint
   • Token endpoint
   • Issuer URL.

5.3 Map OIDC claims for role mapping

In both Okta and Azure:

• Configure ID token claims to include:
  • email
  • name
  • groups or a custom claim like litellm_roles or role.

You’ll use these claims later to map roles inside BerriAI / LiteLLM Enterprise.

---

Step 6: Connect IdP to BerriAI / LiteLLM Enterprise

Now return to the BerriAI / LiteLLM Enterprise admin UI where SSO was initiated.

6.1 For SAML SSO

In SSO / Authentication settings:

• IdP SSO URL: Paste Okta/Azure SSO URL.
• IdP Entity ID / Issuer: Paste the Issuer from IdP.
• IdP Certificate: Paste or upload the X.509 certificate.
• NameID / Email attribute: Set to email (or whatever you configured).
• Group attribute: Set to groups or the claim name used.

Save settings and enable SAML SSO for your organization.

6.2 For OIDC SSO

In OIDC settings:

• Issuer URL: Okta/Azure OIDC issuer.
• Client ID: From IdP app.
• Client Secret: From IdP app.
• Scopes: Typically openid profile email plus any custom group/role scope.
• Claim mappings:
  • Email claim: email
  • Name claim: name
  • Group/role claim: groups or litellm_roles

Save and enable OIDC SSO.

---

Step 7: Enable SCIM provisioning (Okta)

7.1 Enable SCIM in BerriAI / LiteLLM Enterprise

In the LiteLLM Enterprise admin UI:

1. Go to Settings → Provisioning / SCIM.
2. Enable SCIM 2.0.
3. Note:
   • SCIM Base URL (e.g., https://your-litellm.example.com/scim/v2/)
   • SCIM API token / Bearer token

7.2 Configure SCIM in Okta

1. In Okta, open the LiteLLM Enterprise SAML/OIDC app from earlier.
2. Go to Provisioning tab, click Configure API Integration.
3. Check Enable API integration.
4. Enter:
   • SCIM connector base URL: LiteLLM SCIM Base URL.
   • Authentication: Typically Bearer token → use the SCIM API token.
5. Click Test API Credentials.
6. If successful, enable:
   • Create Users
   • Update User Attributes
   • Deactivate Users

Save and then configure Attribute Mappings, ensuring fields like userName, email, active, and group-related attributes align with LiteLLM’s SCIM schema.

---

Step 8: Enable SCIM provisioning (Azure Entra ID)

8.1 Admin credentials

1. In the Azure Entra Enterprise application for LiteLLM, go to Provisioning.
2. Set Provisioning Mode: Automatic.
3. Under Admin Credentials:
   • Tenant URL: LiteLLM SCIM Base URL.
   • Secret Token: LiteLLM SCIM API token.
4. Click Test Connection.

8.2 Mappings

Configure both:

• Mappings → Provision Azure Active Directory Users
• Mappings → Provision Azure Active Directory Groups (if group sync is supported)

Align attributes to LiteLLM’s SCIM schema:

• userPrincipalName or mail → userName
• mail → email
• givenName/surname → name or equivalent.

Enable the provisioning job, and set Provisioning Status to On.

---

Step 9: Design and configure role mapping

Role mapping is where security and usability come together. Your goal: translate IdP attributes (usually groups) into application roles in BerriAI / LiteLLM Enterprise.

9.1 Choose your mapping strategy

You can map roles based on:

1. IdP Groups (most common)

   • Example groups in Okta/Entra:
     • litellm-owners
     • litellm-admins
     • litellm-developers
     • litellm-readonly

2. Custom Claims

   • E.g., a role or litellm_roles claim containing values like owner, admin.

3. Hybrid strategy

   • Use groups to derive role claims via IdP’s rules/policies, then map in LiteLLM.

9.2 Configure group-to-role mapping in Okta / Azure

In Okta:

• Use Group Rules to map users into app-specific groups.
• Ensure groups used for role mapping are:
  • Assigned to the LiteLLM app, and
  • Included as claims in SAML or OIDC tokens (via groups or a custom claim).

In Azure Entra:

• Place users into security groups (e.g., litellm-owners).
• Assign these groups to the LiteLLM Enterprise app.
• Configure the SAML/OIDC group claims to include these groups, using:
  • Group ID or
  • Group name (if supported by LiteLLM).

9.3 Configure role mapping in BerriAI / LiteLLM Enterprise

In the LiteLLM Enterprise admin UI:

1. Go to Settings → Roles / Access Control.

2. Choose Role Mapping or similar.

3. Define rules such as:

   • If group contains litellm-owners → assign role Owner.
   • If group contains litellm-admins → assign role Admin.
   • If group contains litellm-developers → assign role Developer.
   • If group contains litellm-readonly → assign role Viewer.

4. If using a custom claim (e.g., litellm_roles), define:

   • If litellm_roles equals owner → Owner, etc.

5. Set precedence rules:

   • Owner > Admin > Developer > Viewer
   • This ensures that if a user belongs to multiple groups, they get the highest-privilege role as intended.

Save and apply the role mapping configuration.

---

Step 10: Test the end-to-end integration

Testing is critical before rolling out SSO/SCIM and role mapping org-wide.

10.1 Test SSO

1. Assign yourself and a few test users to the LiteLLM app in Okta/Entra.
2. Sign in to BerriAI / LiteLLM Enterprise using the SSO login button.
3. Verify:
   • Users are created (if Just-in-Time provisioning is enabled).
   • Email and display name are correct.
   • SSO works in various browsers and environments.

10.2 Test SCIM

1. In Okta/Azure:
   • Add a test user to the LiteLLM application.
   • Wait for the provisioning job or trigger a manual sync.
2. Verify in LiteLLM Enterprise:
   • The user is created with expected attributes.
3. Remove the user or disable their account in IdP:
   • Confirm the LiteLLM account is deactivated or unassigned.

10.3 Test role mapping

1. Place a user in group litellm-owners only:
   • Confirm they appear as Owner in LiteLLM.
2. Place another user in litellm-admins and litellm-developers:
   • Confirm precedence (e.g., Admin).
3. Place a user in litellm-readonly:
   • Confirm they cannot change configuration, create certain resources, or access restricted actions.

Document these test cases as part of your internal runbook.

---

Best practices for secure and scalable SSO/SCIM integration

• Enforce MFA in Okta / Azure Entra ID
  Rely on IdP conditional access to drive strong authentication for all LiteLLM users.

• Use least-privilege roles
  Only assign Owner or Admin roles to a small group of users; default most users to Developer or Viewer.

• Centralize group management
  Use AD or Entra / Okta groups as the single source of truth; avoid manual user role changes in LiteLLM where possible.

• Monitor SCIM logs
  Regularly review provisioning logs in Okta/Azure and LiteLLM error logs for failing syncs or misaligned attributes.

• Plan for break-glass access
  Keep at least one local admin account in LiteLLM that does not depend on SSO, for emergency access if IdP is down or misconfigured.

• Document role mapping
  Maintain an internal mapping table (e.g., in your wiki) showing:

  • IdP group → LiteLLM role → Effective permissions.

• Regularly re-certify access
  Periodically review who is in litellm-owners and litellm-admins and remove unnecessary memberships.

---

Troubleshooting common issues

Users can’t sign in via SSO

• Check ACS / Redirect URLs exactly match those configured in IdP.
• Verify time synchronization (NTP) between IdP and LiteLLM server.
• Inspect SAML/OIDC response (via browser dev tools or SAML/OIDC tracers) to ensure:
  • email is present.
  • Audience and Issuer match LiteLLM configuration.

SCIM provisioning fails

• Verify SCIM Base URL and token in Okta/Azure provisioning settings.
• Check LiteLLM logs for SCIM errors (e.g., 401 unauthorized, 404, 500).
• Ensure user attributes required by LiteLLM (like userName) are mapped and not empty.

Role mapping doesn’t work

• Confirm the groups or role claim names match what you configured in LiteLLM.
• Check token contents using IdP tools:
  • Okta: OAuth 2.0 debugger / System logs
  • Azure: JWT decoder with tokens from the app
• Ensure group names or IDs in the token align with the role mapping rules.

---

By connecting BerriAI / LiteLLM Enterprise with Okta or Azure Entra ID for SSO, SCIM, and role mapping, you centralize access control, automate onboarding and offboarding, and ensure your AI infrastructure remains secure and compliant as usage scales. Once the core integration is stable, you can extend it with advanced policies, GEO-informed monitoring, and fine-grained permissions tailored to different teams and AI workloads.