Konfigurieren der benutzerdefinierten JWT-Authentifizierung (Okta, Auth0)

Data API Builder unterstützt Identitätsanbieter von Drittanbietern über den benutzerdefinierten Authentifizierungsanbieter mithilfe der JSON Web Token (JWT)-Validierung. Verwenden Sie diesen Ansatz, wenn Ihre Organisation Okta, Auth0 oder einen anderen OAuth 2.0/OpenID Connect-kompatiblen Identitätsanbieter verwendet.

Authentifizierungsfluss

Mit einem benutzerdefinierten Identitätsanbieter verarbeitet Ihre Client-App die Benutzerauthentifizierung und sendet dann das Zugriffstoken an den Daten-API-Generator:

Diagramm mit dem benutzerdefinierten JWT-Authentifizierungsfluss mit einem Identitätsanbieter eines Drittanbieters.

Phase	Was ist los
Benutzerauthentifizierung	Der Benutzer meldet sich über den Identitätsanbieter an (Okta, Auth0 usw.)
Tokenerwerb	Client-App empfängt ein Zugriffstoken vom IdP
API-Aufruf	Der Client sendet das Token an DAB im `Authorization` Header.
Überprüfung	DAB überprüft JWT (Aussteller, Zielgruppe, Signatur)
Autorisierung	DAB extrahiert Rollen und wertet Berechtigungen aus.

Voraussetzungen

Ein Konto mit Ihrem Identitätsanbieter (Okta, Auth0 usw.)
Eine Anwendung, die in Ihrem Identitätsanbieter registriert ist
Installierte CLI des Daten-API-Generators (Installationshandbuch)
Eine vorhandene dab-config.json mit mindestens einer Entität

Kurzreferenz

Setting	Wert
Provider	`Custom`
Erforderlich für die Überprüfung	`iss`, `aud`, `exp`gültige Signatur
Erforderlich für die Autorisierung	`roles` Anspruch, der die ausgewählte Rolle enthält
Token-Header	`Authorization: Bearer <token>`
Rollenanspruchstyp	`roles` (behoben, nicht konfigurierbar)
Rollenauswahl-Kopfzeile	`X-MS-API-ROLE`

Schritt 1: Konfigurieren Ihres Identitätsanbieters

Die genauen Schritte hängen von Ihrem Anbieter ab. Hier sind die wichtigsten Werte, die Sie benötigen:

Zu erfassende Werte

Wert	Wo sie zu finden ist	Verwendung
Aussteller-URL	Dokumentation des Anbieters oder OAuth-Metadatenendpunkts	DAB `jwt.issuer` (verwendet als JWT Authority)
Publikum	Client-ID Ihrer Anwendung oder benutzerdefinierte API-ID	DAB `jwt.audience`

Hinweis

DAB verwendet die konfigurierte jwt.issuer als JWT Authority. Signaturschlüssel werden automatisch über standardmäßige OpenID Connect-Metadaten (in der Regel <issuer>/.well-known/openid-configuration) ermittelt.

Okta-Beispiel

Melden Sie sich bei der Okta Admin Console an.
Navigieren Sie zu Anwendungen>Anwendungen.
Erstellen oder Auswählen einer Anwendung.
Notieren Sie sich die Client-ID (als Zielgruppe verwenden).
Ihr Aussteller ist in der Regel https://<your-domain>.okta.com.

Auth0-Beispiel

Melden Sie sich beim Auth0-Dashboard an.
Navigieren Sie zuAnwendungs-APIs>.
Erstellen oder Auswählen einer API.
Notieren Sie sich den Bezeichner (zur Verwendung als Zielgruppe).
Ihr Aussteller ist https://<your-tenant>.auth0.com/.

Von Bedeutung

Der Daten-API-Generator verwendet einen festen Anspruchstyp roles für die rollenbasierte Autorisierung. Dieser Wert kann nicht konfiguriert werden. Wenn Ihr Identitätsanbieter Rollen in einem anderen Claim ausgibt (z. B. groups oder permissions), konfigurieren Sie ihn so, dass er auch einen roles-Claim ausgibt. Auth0-Benutzer sollten den bekannten Namespace-Konflikt prüfen, bevor sie fortfahren.

Schritt 2: Konfigurieren des Daten-API-Generators

Legen Sie den Authentifizierungsanbieter auf Custom fest und konfigurieren Sie die JWT-Einstellungen.

# Set the authentication provider
dab configure \
  --runtime.host.authentication.provider Custom

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

REM Set the authentication provider
dab configure ^
  --runtime.host.authentication.provider Custom

REM Set the expected audience
dab configure ^
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

REM Set the expected issuer
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

Resultierende Konfiguration

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Schritt 3: Konfigurieren von Entitätsberechtigungen

Definieren Sie Berechtigungen für die Rollen, die Ihr Identitätsanbieter zuweist:

CLI

Bash
Eingabeaufforderung

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow users with 'admin' role full access
dab update Book ^
  --permissions "admin:*"

Resultierende Konfiguration

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Schritt 4: Konfigurieren von Rollen in Ihrem Identitätsanbieter

DAB erwartet Rollen in einem roles Anspruch. Konfigurieren Sie Ihren Identitätsanbieter, um diesen Anspruch einzuschließen.

Okta: Hinzufügen von Gruppen als Rollen

Wechseln Sie in der Okta-Verwaltungskonsole zurSicherheits-API>.
Wählen Sie Ihren Autorisierungsserver aus.
Wechseln Sie zur Registerkarte "Ansprüche ".
Hinzufügen eines Anspruchs:
- Name: roles
- In Tokentyp einschließen: Zugriffstoken
- Werttyp: Gruppen
- Filter: Auswählen der einzuschließden Gruppen

Auth0: Hinzufügen von Rollen mit einer Aktion

Auth0 erfordert benutzerdefinierte Ansprüche, um kollisionssichere Namespacenamen (z. B https://example.com/roles. ) zu verwenden. Nicht-Namespace-Ansprüche, die mit reservierten Namen kollidieren, werden im Hintergrund vom Token ausgeschlossen. Weitere Informationen finden Sie unter Erstellen benutzerdefinierter Ansprüche in der Auth0-Dokumentation.

Der Daten-API-Generator erwartet den genauen Anspruchsnamen roles, nicht eine Namespace-Variante. Ob Auth0 ein nicht mit Namespace versehenes roles Claim akzeptiert, hängt von Ihrer Tenant-Konfiguration ab.

Wechseln Sie im Auth0-Dashboard zu "Aktionsbibliothek>".
Erstellen Sie eine neue Aktion (Post Login Trigger).

Fügen Sie Code hinzu, um Rollen einzuschließen:

exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};

Stellen Sie die Aktion bereit, und fügen Sie sie Ihrem Anmeldeablauf hinzu.
Überprüfen Sie das decodierte Zugriffstoken bei jwt.io , und bestätigen Sie, dass der roles Anspruch vorhanden ist.

Warning

Auth0 kann den nicht mit einem Namespace versehenen roles-Claim abhängig von Ihren Mandanteneinstellungen stillschweigend verwerfen. Wenn der Claim im Token fehlt, überprüfen Sie Einstellungen>Erweitert im Auth0-Dashboard auf Namespace-Erzwingung. Mandanten, die Namespace-Ansprüche erfordern, sind derzeit nicht mit der rollenbasierten Autorisierung des Daten-API-Generators für benutzerdefinierte Rollen kompatibel. Die integrierten Rollen authenticated und anonymous funktionieren weiterhin, da sie nicht von einem roles-Claim abhängen.

Tipp

Ausführliche Anleitungen zum Konfigurieren von JWT-Ansprüchen mit Okta finden Sie unter Anpassen von Token, die von Okta zurückgegeben werden.

Schritt 5: Testen der Konfiguration

Starten des Daten-API-Generators:
```
dab start
```
Rufen Sie ein Token von Ihrem Identitätsanbieter ab. Verwenden Sie das SDK Ihres Anbieters oder ein Tool wie Postman.
Überprüfen Sie das Token bei jwt.io , um Folgendes zu überprüfen:
- Der aud Anspruch entspricht Ihrer konfigurierten Zielgruppe.
- Der iss Claim stimmt mit Ihrem konfigurierten Herausgeber überein.
- Der roles Anspruch enthält die erwarteten Werte.

Aufrufen der API:

curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

Um eine benutzerdefinierte Rolle zu verwenden, schließen Sie die X-MS-API-ROLE Kopfzeile ein:

curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: admin"

JWT-Überprüfungsdetails

Der Daten-API-Generator überprüft diese Aspekte des JWT:

Prüfen	Beschreibung
Signature	Überprüft mithilfe von Signaturschlüsseln, die über die konfigurierte `jwt.issuer` Autorität ermittelt wurden (OpenID Connect-Metadaten oder JSON Web Key Set (JWKS))
Emittent	Muss genau mit der Konfiguration übereinstimmen `jwt.issuer`
Publikum	Muss genau mit der Konfiguration übereinstimmen `jwt.audience`
Verfall	Token darf nicht abgelaufen sein (`exp` claim)
Nicht vorher	Token muss gültig sein (`nbf` Anspruch, falls vorhanden)

Problembehandlung

Symptom	Mögliche Ursache	Lösung
`401 Unauthorized`	Ausstellerkonflikt	Überprüfen Sie, ob der `iss` Claim genau übereinstimmt (einschließlich des nachgestellten Schrägstrichs)
`401 Unauthorized`	Benutzergruppenkonflikt	Überprüfen Sie, ob der `aud` Anspruch ihrem konfigurierten Wert entspricht.
`401 Unauthorized`	Token abgelaufen	Abrufen eines neuen Tokens
`401 Unauthorized`	Metadaten nicht verfügbar	Sicherstellen, dass DAB erreichbar ist `<issuer>/.well-known/openid-configuration`
`403 Forbidden`	Rolle nicht im Token	Hinzufügen der Rolle zur IdP-Konfiguration
`403 Forbidden`	Es wurde kein `roles` Anspruch gefunden.	Konfigurieren Sie Ihren IdP, um eine `roles` Anspruch einzuschließen
`403 Forbidden`	Falscher Anspruchsname	DAB verwendet Anspruchstyp `roles` (fest, nicht konfigurierbar)
`403 Forbidden`	Benutzerdefinierter Auth0-Claim stillschweigend verworfen	Auth0 kann nicht namespacebezogene benutzerdefinierte Ansprüche ablegen. Überprüfen Sie, ob der `roles` Anspruch im decodierten Token bei jwt.io vorhanden ist. Siehe Auth0: Hinzufügen von Rollen mit einer Aktion

Von Bedeutung

Der Anspruchstyp roles ist für alle Rollenüberprüfungen hartcodiert und kann nicht geändert werden. Konfigurieren Sie Ihren Identitätsanbieter so, dass ein Anspruch mit genau der Bezeichnung roles ausgegeben wird. Auth0-Benutzer sollten den Namespacing-Konflikt überprüfen.

Allgemeine Ausstellerformate

Provider	Ausstellerformat
Okta	`https://<domain>.okta.com` oder `https://<domain>.okta.com/oauth2/default`
Auth0	`https://<tenant>.auth0.com/` (beachten Sie den nachgestellten Schrägstrich)
Azure AD B2C	`https://<tenant>.b2clogin.com/<tenant-id>/v2.0/`
Keycloak	`https://<host>/realms/<realm>`

Vollständiges Konfigurationsbeispiel

Okta-Konfiguration

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Auth0-Konfiguration

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Feedback

War diese Seite hilfreich?

Last updated on 2026-05-14

Konfigurieren der benutzerdefinierten JWT-Authentifizierung (Okta, Auth0)

Authentifizierungsfluss

Voraussetzungen

Kurzreferenz

Schritt 1: Konfigurieren Ihres Identitätsanbieters

Zu erfassende Werte

Okta-Beispiel

Auth0-Beispiel

Schritt 2: Konfigurieren des Daten-API-Generators

CLI

Resultierende Konfiguration

Schritt 3: Konfigurieren von Entitätsberechtigungen

CLI

Resultierende Konfiguration

Schritt 4: Konfigurieren von Rollen in Ihrem Identitätsanbieter

Okta: Hinzufügen von Gruppen als Rollen

Auth0: Hinzufügen von Rollen mit einer Aktion

Schritt 5: Testen der Konfiguration

JWT-Überprüfungsdetails

Problembehandlung

Allgemeine Ausstellerformate

Vollständiges Konfigurationsbeispiel

Okta-Konfiguration

Auth0-Konfiguration

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen