Zum Hauptinhalt springen

OIDC - JWT-basierte Authentifizierung

Verwenden Sie JWTs zur Authentifizierung von Admins / Benutzern / Projekten im Proxy.

Info

✨ JWT-basierte Authentifizierung ist Teil von LiteLLM Enterprise

Enterprise-Preise

Kontaktieren Sie uns hier für eine kostenlose Testversion

Verwendung​

Schritt 1. Proxy einrichten​

  • JWT_PUBLIC_KEY_URL: Dies ist der Endpunkt für öffentliche Schlüssel Ihres OpenID-Anbieters. Typischerweise ist es {openid-provider-base-url}/.well-known/openid-configuration/jwks. Für Keycloak ist es {keycloak_base_url}/realms/{your-realm}/protocol/openid-connect/certs.
  • JWT_AUDIENCE: Dies ist die Zielgruppe, die zur Dekodierung des JWT verwendet wird. Wenn nicht gesetzt, wird der Dekodierungsschritt die Zielgruppe nicht überprüfen.
export JWT_PUBLIC_KEY_URL="" # "https://demo.duendesoftware.com/.well-known/openid-configuration/jwks"
  • enable_jwt_auth in Ihrer Konfiguration. Dies weist den Proxy an, zu prüfen, ob ein Token ein JWT-Token ist.
general_settings:
  master_key: sk-1234
  enable_jwt_auth: True

model_list:
- model_name: azure-gpt-3.5 
  litellm_params:
      model: azure/<your-deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: "2023-07-01-preview"

Schritt 2. JWT mit Scopes erstellen​

Erstellen Sie einen Client-Scope namens litellm_proxy_admin in Ihrem OpenID-Anbieter (z. B. Keycloak).

Gewähren Sie Ihrem Benutzer den Scope litellm_proxy_admin, wenn Sie einen JWT generieren.

curl --location ' 'https://demo.duendesoftware.com/connect/token'' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={CLIENT_ID}' \
--data-urlencode 'client_secret={CLIENT_SECRET}' \
--data-urlencode 'username=test-{USERNAME}' \
--data-urlencode 'password={USER_PASSWORD}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=litellm_proxy_admin' # 👈 grant this scope

Schritt 3. Testen Sie Ihren JWT​

curl --location '{proxy_base_url}/key/generate' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiI...' \
--header 'Content-Type: application/json' \
--data '{}'

Erweitert​

Mehrere OIDC-Anbieter​

Verwenden Sie dies, wenn Sie möchten, dass LiteLLM Ihren JWT gegen mehrere OIDC-Anbieter validiert (z. B. Google Cloud, GitHub Auth).

Setzen Sie JWT_PUBLIC_KEY_URL in Ihrer Umgebung auf eine durch Kommas getrennte Liste von URLs für Ihre OIDC-Anbieter.

export JWT_PUBLIC_KEY_URL="https://demo.duendesoftware.com/.well-known/openid-configuration/jwks,https://#/.well-known/openid-configuration/jwks"

Akzeptierte JWT-Scope-Namen festlegen​

Ändern Sie den String in den JWT-Scopes, den LiteLLM auswertet, um zu sehen, ob ein Benutzer Admin-Zugriff hat.

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    admin_jwt_scope: "litellm-proxy-admin"

Nachverfolgung von Endbenutzern / internen Benutzern / Teams / Organisationen​

Setzen Sie das Feld im JWT-Token, das einem LiteLLM-Benutzer / -Team / -Organisation entspricht.

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    admin_jwt_scope: "litellm-proxy-admin"
    team_id_jwt_field: "client_id" # 👈 CAN BE ANY FIELD
    user_id_jwt_field: "sub" # 👈 CAN BE ANY FIELD
    org_id_jwt_field: "org_id" # 👈 CAN BE ANY FIELD
    end_user_id_jwt_field: "customer_id" # 👈 CAN BE ANY FIELD

Erwarteter JWT

{
  "client_id": "my-unique-team",
  "sub": "my-unique-user",
  "org_id": "my-unique-org",
}

Nun wird LiteLLM die Ausgaben für den Benutzer/das Team/die Organisation in der Datenbank für jeden Aufruf automatisch aktualisieren.

JWT Scopes​

So sehen Scopes auf JWT-Authentifizierungstoken aus

Kann eine Liste sein

scope: ["litellm-proxy-admin",...]

Kann ein durch Leerzeichen getrennter String sein

scope: "litellm-proxy-admin ..."

Modellzugriff mit Teams steuern​

  1. Geben Sie das JWT-Feld an, das die Team-IDs enthält, zu denen der Benutzer gehört.
general_settings:
  enable_jwt_auth: True
  litellm_jwtauth:
    user_id_jwt_field: "sub"
    team_ids_jwt_field: "groups" 
    user_id_upsert: true # add user_id to the db if they don't exist
    enforce_team_based_model_access: true # don't allow users to access models unless the team has access

Dies geht davon aus, dass Ihr Token wie folgt aussieht

{
  ...,
  "sub": "my-unique-user",
  "groups": ["team_id_1", "team_id_2"]
}
  1. Teams auf LiteLLM erstellen
curl -X POST '<PROXY_BASE_URL>/team/new' \
-H 'Authorization: Bearer <PROXY_MASTER_KEY>' \
-H 'Content-Type: application/json' \
-D '{
    "team_alias": "team_1",
    "team_id": "team_id_1" # 👈 MUST BE THE SAME AS THE SSO GROUP ID
}'
  1. Den Ablauf testen

SSO für UI: Walkthrough ansehen

OIDC-Authentifizierung für API: Walkthrough ansehen

Ablauf​

  • Prüfen, ob Benutzer-ID in der DB vorhanden ist (LiteLLM_UserTable)
  • Prüfen, ob eine der Gruppen in der DB vorhanden ist (LiteLLM_TeamTable)
  • Prüfen, ob eine Gruppe Modellzugriff hat
  • Wenn alle Prüfungen bestanden sind, die Anfrage zulassen

Benutzerdefinierte JWT-Validierung​

Validieren Sie einen JWT-Token mit benutzerdefinierter Logik, wenn Sie eine zusätzliche Möglichkeit benötigen, um zu überprüfen, ob Token für den LiteLLM-Proxy gültig sind.

1. Benutzerdefinierte Validierungsfunktion einrichten​

from typing import Literal

def my_custom_validate(token: str) -> Literal[True]:
  """
  Only allow tokens with tenant-id == "my-unique-tenant", and claims == ["proxy-admin"]
  """
  allowed_tenants = ["my-unique-tenant"]
  allowed_claims = ["proxy-admin"]

  if token["tenant_id"] not in allowed_tenants:
    raise Exception("Invalid JWT token")
  if token["claims"] not in allowed_claims:
    raise Exception("Invalid JWT token")
  return True

2. config.yaml einrichten​

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    user_id_jwt_field: "sub"
    team_id_jwt_field: "tenant_id"
    user_id_upsert: True
    custom_validate: custom_validate.my_custom_validate # 👈 custom validate function

3. Den Ablauf testen​

Erwarteter JWT

{
  "sub": "my-unique-user",
  "tenant_id": "INVALID_TENANT",
  "claims": ["proxy-admin"]
}

Erwartete Antwort

{
  "error": "Invalid JWT token"
}

Zulässige Routen​

Konfigurieren Sie, auf welche Routen ein JWT zugreifen kann, über die Konfiguration.

Standardmäßig

  • Admins: können nur Verwaltungsrouten aufrufen (/team/*, /key/*, /user/*)
  • Teams: können nur OpenAI-Routen aufrufen (/chat/completions, etc.) + Info-Routen (/*/info)

Code anzeigen

Admin-Routen

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    admin_jwt_scope: "litellm-proxy-admin"
    admin_allowed_routes: ["/v1/embeddings"]

Team-Routen

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    ...
    team_id_jwt_field: "litellm-team" # 👈 Set field in the JWT token that stores the team ID
    team_allowed_routes: ["/v1/chat/completions"] # 👈 Set accepted routes

Caching von öffentlichen Schlüsseln​

Steuern Sie, wie lange öffentliche Schlüssel zwischengespeichert werden (in Sekunden).

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    admin_jwt_scope: "litellm-proxy-admin"
    admin_allowed_routes: ["/v1/embeddings"]
    public_key_ttl: 600 # 👈 KEY CHANGE

Benutzerdefiniertes JWT-Feld​

Setzen Sie ein benutzerdefiniertes Feld, in dem sich die team_id befindet. Standardmäßig wird das Feld 'client_id' geprüft.

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    team_id_jwt_field: "client_id" # 👈 KEY CHANGE

Teams blockieren​

Um alle Anfragen für eine bestimmte Team-ID zu blockieren, verwenden Sie /team/block

Team blockieren

curl --location 'http://0.0.0.0:4000/team/block' \
--header 'Authorization: Bearer <admin-token>' \
--header 'Content-Type: application/json' \
--data '{
    "team_id": "litellm-test-client-id-new" # 👈 set team id
}'

Team entblockieren

curl --location 'http://0.0.0.0:4000/team/unblock' \
--header 'Authorization: Bearer <admin-token>' \
--header 'Content-Type: application/json' \
--data '{
    "team_id": "litellm-test-client-id-new" # 👈 set team id
}'

Benutzer und erlaubte E-Mail-Domänen hinzufügen/aktualisieren​

Erlauben Sie Benutzern, die zu einer bestimmten E-Mail-Domäne gehören, automatischen Zugriff auf den Proxy.

general_settings:
  master_key: sk-1234
  enable_jwt_auth: True
  litellm_jwtauth:
    user_email_jwt_field: "email" # 👈 checks 'email' field in jwt payload
    user_allowed_email_domain: "my-co.com" # allows user@my-co.com to call proxy
    user_id_upsert: true # 👈 upserts the user to db, if valid email but not in db

[BETA]Zugriff mit OIDC-Rollen steuern​

Erlauben Sie JWT-Token mit unterstützten Rollen den Zugriff auf den Proxy.

Ermöglichen Sie Benutzern und Teams den Zugriff auf den Proxy, ohne sie in der Datenbank hinzufügen zu müssen.

Sehr wichtig: Setzen Sie enforce_rbac: true, um sicherzustellen, dass das RBAC-System aktiviert ist.

Hinweis: Dies ist eine Betaversion und kann sich unerwartet ändern.

general_settings:
  enable_jwt_auth: True
  litellm_jwtauth:
    object_id_jwt_field: "oid" # can be either user / team, inferred from the role mapping
    roles_jwt_field: "roles"
    role_mappings:
      - role: litellm.api.consumer
        internal_role: "team"
    enforce_rbac: true # 👈 VERY IMPORTANT

  role_permissions: # default model + endpoint permissions for a role. 
    - role: team
      models: ["anthropic-claude"]
      routes: ["/v1/chat/completions"]

environment_variables:
  JWT_AUDIENCE: "api://LiteLLM_Proxy" # ensures audience is validated

  • object_id_jwt_field: Das Feld im JWT-Token, das die Objekt-ID enthält. Diese ID kann entweder eine Benutzer-ID oder eine Team-ID sein. Verwenden Sie dies anstelle von user_id_jwt_field und team_id_jwt_field. Wenn dasselbe Feld beides sein kann.

  • roles_jwt_field: Das Feld im JWT-Token, das die Rollen enthält. Dieses Feld ist eine Liste von Rollen, die der Benutzer hat. Um auf ein verschachteltes Feld zuzugreifen, verwenden Sie die Punktnotation - z. B. resource_access.litellm-test-client-id.roles.

  • role_mappings: Eine Liste von Rollenzuordnungen. Ordnen Sie die empfangene Rolle im JWT-Token einer internen Rolle auf LiteLLM zu.

  • JWT_AUDIENCE: Die Zielgruppe des JWT-Tokens. Dies wird verwendet, um die Zielgruppe des JWT-Tokens zu validieren. Wird über eine Umgebungsvariable gesetzt.

Beispiel-Token​

{
  "aud": "api://LiteLLM_Proxy",
  "oid": "eec236bd-0135-4b28-9354-8fc4032d543e",
  "roles": ["litellm.api.consumer"] 
}

Rollenmapping-Spezifikation​

  • role: Die erwartete Rolle im JWT-Token.
  • internal_role: Die interne Rolle auf LiteLLM, die zur Steuerung des Zugriffs verwendet wird.

Unterstützte interne Rollen

  • team: Das Team-Objekt wird für die RBAC-Ausgabenverfolgung verwendet. Verwenden Sie dies für die Verfolgung der Ausgaben für einen "Anwendungsfall".
  • internal_user: Das Benutzerobjekt wird für die RBAC-Ausgabenverfolgung verwendet. Verwenden Sie dies für die Verfolgung der Ausgaben für einen "einzelnen Benutzer".
  • proxy_admin: Der Proxy-Admin wird für die RBAC-Ausgabenverfolgung verwendet. Verwenden Sie dies, um einem Token Admin-Zugriff zu gewähren.

Architekturdiagramm (Steuerung des Modellzugriffs)​

[BETA]Modellzugriff mit Scopes steuern​

Steuern Sie, auf welche Modelle ein JWT zugreifen kann. Setzen Sie enforce_scope_based_access: true, um eine Scope-basierte Zugriffskontrolle zu erzwingen.

1. config.yaml mit Scope-Mappings einrichten.​

model_list:
  - model_name: anthropic-claude
    litellm_params:
      model: anthropic/claude-3-5-sonnet
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: gpt-3.5-turbo-testing
    litellm_params:
      model: gpt-3.5-turbo
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  enable_jwt_auth: True
  litellm_jwtauth:
    team_id_jwt_field: "client_id" # 👈 set the field in the JWT token that contains the team id
    team_id_upsert: true # 👈 upsert the team to db, if team id is not found in db
    scope_mappings:
      - scope: litellm.api.consumer
        models: ["anthropic-claude"]
      - scope: litellm.api.gpt_3_5_turbo
        models: ["gpt-3.5-turbo-testing"]
    enforce_scope_based_access: true # 👈 enforce scope-based access control
    enforce_rbac: true # 👈 enforces only a Team/User/ProxyAdmin can access the proxy.

Scope-Mapping-Spezifikation​

  • scope: Der Scope, der für das JWT-Token verwendet werden soll.
  • models: Die Modelle, auf die das JWT-Token zugreifen kann. Der Wert ist der model_name in model_list. Hinweis: Wildcard-Routen werden derzeit nicht unterstützt.

2. Erstellen Sie einen JWT mit den richtigen Scopes.​

Erwartetes Token

{
  "scope": ["litellm.api.consumer", "litellm.api.gpt_3_5_turbo"] # can be a list or a space-separated string
}

3. Den Ablauf testen.​

curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGci...' \
-d '{
  "model": "gpt-3.5-turbo-testing",
  "messages": [
    {
      "role": "user",
      "content": "Hey, how'\''s it going 1234?"
    }
  ]
}'

Alle JWT-Parameter​

Code anzeigen