Konfigurieren der Microsoft Entra ID-Authentifizierung

Dieses Handbuch führt Sie durch das Konfigurieren der Microsoft Entra ID-Authentifizierung (vormals Azure Active Directory) für den Daten-API-Generator. Am Ende authentifiziert Ihre Client-App Benutzer über Entra, erwirbt Token für den Daten-API-Generator, und DAB kann verwaltete Identität verwenden, um eine Verbindung mit Azure SQL herzustellen.

Der Daten-API-Generator authentifiziert eingehende Anforderungen entweder mithilfe der JSON Web Token (JWT) Bearer-Überprüfung (EntraID/AzureAD/Custom) oder plattformbezogener Identitätsheader (AppService). Verwenden Sie für lokale Entwicklungs- und Berechtigungstests den Simulator Anbieter.

Authentifizierungsanbieterhandbücher

Wählen Sie einen Leitfaden basierend auf Ihrem Identitätsanbieter aus:

Authentifizierungsfluss

Der Fluss weist drei verschiedene Phasen auf:

Voraussetzungen

• Ein Azure-Abonnement mit einem Microsoft Entra ID Mandant
• Installierte CLI des Daten-API-Generators (Installationshandbuch)
• Eine vorhandene dab-config.json mit mindestens einer Entität
• (Optional) Azure SQL-Datenbank für Szenarien mit verwalteter Identität

Kurzreferenz

Schritt 1: Registrieren einer Anwendung in Microsoft Entra ID

Erstellen Sie eine App-Registrierung, die Ihre Daten-API-Generator-API darstellt. Client-Apps fordern Token mit einer Zielgruppe an, die dieser Registrierung entspricht.

1. Melden Sie sich beim Microsoft Entra Admin Center an.

2. Navigieren Sie zu Identität>Anwendungen>App-Registrierungen.

3. Wählen Sie Neue Registrierung aus.

4. Geben Sie einen Namen ein (z. B Data API Builder API. ).

5. Wählen Sie die entsprechenden unterstützten Kontotypen für Ihr Szenario aus:

   • Einzelner Mandant: Nur Benutzer in Ihrer Organisation
   • Multitenant: Benutzer in einem beliebigen Microsoft Entra-Verzeichnis

6. Lassen Sie den Umleitungs-URI leer (diese Registrierung gilt für die API, nicht für den Client).

7. Wählen Sie Registrieren aus.

8. Notieren Sie sich auf der Seite "Übersicht" der App die folgenden Werte:

   Wert	Wo sie zu finden ist	Verwendung
   Anwendungs-ID (Client)	Seite „Übersicht“	Erstellung der Nutzergruppe-URI
   Verzeichnis-ID (Mandant)	Seite „Übersicht“	Erstellen der Aussteller-URL

Konfigurieren der Anwendungs-ID-URI

1. Wechseln Sie in der App-Registrierung zu "Verfügbarmachen einer API".

2. Wählen Sie neben Anwendungs-ID-URI die Option Hinzufügen aus.

3. Übernehmen Sie den Standardwert (api://<app-id>) oder geben Sie einen benutzerdefinierten URI ein.

4. Wählen Sie "Speichern" aus.

Hinzufügen eines Geltungsbereichs

Ein Berechtigungsbereich ist erforderlich, damit Clientanwendungen (einschließlich Azure CLI) delegierte Zugriffstoken für Ihre API anfordern können.

1. Wechseln Sie in der App-Registrierung zu "Verfügbarmachen einer API".

2. Wählen Sie unter Durch diese API definierte Bereiche die Option Bereich hinzufügen aus.

3. Geben Sie Folgendes ein:

   • Bereichsname: Endpoint.Access
   • Zum Einwilligen berechtigte Personen: Administratoren und Benutzer
   • Anzeigename der Administratoreinwilligung: Execute requests against Data API builder
   • Beschreibung der Administratoreinwilligung: Allows client app to send requests to Data API builder endpoint.
   • Anzeigename der Benutzereinwilligung: Execute requests against Data API builder
   • Beschreibung der Benutzereinwilligung: Allows client app to send requests to Data API builder endpoint.
   • Status:Aktiviert

4. Wählen Sie "Bereich hinzufügen" aus.

Hinzufügen von App-Rollen (optional)

Wenn Sie benutzerdefinierte Rollen über folgendes hinaus Anonymous verwenden möchten:Authenticated

1. Wechseln Sie zu App-Rollen.

2. Wählen Sie " App-Rolle erstellen" aus.

3. Geben Sie Folgendes ein:

   • Anzeigename: Reader
   • Zulässige Mitgliedertypen: Benutzer/Gruppen oder beides
   • Wert: reader (dieser Wert wird im Anspruch des roles Tokens angezeigt)
   • Beschreibung: Read-only access to data

4. Wählen Sie Anwenden.

5. Wiederholen Sie diesen Vorgang für weitere Rollen (z. B. writer, admin).

Festlegen der Manifesttokenversion

Standardmäßig legt das App-Registrierungsmanifest accessTokenAcceptedVersion auf null fest, wodurch v1.0-Token erzeugt werden. V1-Token verwenden ein anderes Ausstellerformat (https://sts.windows.net/<tenant-id>/) als der in DAB konfigurierte v2.0-Aussteller, wodurch die Tokenüberprüfung fehlschlägt.

1. Wechseln Sie in der App-Registrierung zu "Manifest".

2. Suchen Sie accessTokenAcceptedVersion und ändern Sie den Wert in 2.

3. Wählen Sie "Speichern" aus.

Benutzer zu App-Rollen zuweisen

Durch das Erstellen von App-Rollen werden diese nicht automatisch den Benutzern zugewiesen. Sie müssen Benutzer oder Gruppen über die Enterprise-Anwendung zuweisen.

1. Navigieren Sie im Microsoft Entra Admin Center zu Identity>Applications>Enterprise-Anwendungen.

2. Suchen und wählen Sie Ihre App (z. B. Data API Builder API). Eine Unternehmensanwendung wurde automatisch erstellt, wenn Sie die App registriert haben.

3. Wechseln Sie zu "Benutzer und Gruppen".

4. Wählen Sie "Benutzer/Gruppe hinzufügen" aus.

5. Wählen Sie unter "Benutzer" das Benutzerkonto aus, das Zugewiesen werden soll, und wählen Sie "Auswählen" aus.

6. Wählen Sie unter "Rolle auswählen" die Rolle aus, die zugewiesen werden soll (z. B. Reader). Wenn Ihre Rolle nicht angezeigt wird, haben Sie bitte etwas Geduld und warten einige Minuten, bis die Replikation von Microsoft Entra abgeschlossen ist.

7. Wählen Sie „Zuweisen“ aus.

8. Wiederholen Sie diesen Vorgang für jede Rolle, die Sie zuweisen möchten.

Schritt 2: Konfigurieren des Daten-API-Generators

Konfigurieren Sie DAB, um token zu überprüfen, die von Ihrem Entra-Mandanten für Ihre API-Zielgruppe ausgestellt wurden.

CLI

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

# Set the expected audience (Application ID URI)
dab configure \
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

# Set the expected issuer (your tenant)
dab configure \
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

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

REM Set the expected audience (Application ID URI)
dab configure ^
  --runtime.host.authentication.jwt.audience "api://<your-app-id>"

REM Set the expected issuer (your tenant)
dab configure ^
  --runtime.host.authentication.jwt.issuer "https://login.microsoftonline.com/<your-tenant-id>/v2.0"

Resultierende Konfiguration

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<your-tenant-id>/v2.0"
        }
      }
    }
  }
}

Schritt 3: Konfigurieren von Entitätsberechtigungen

Definieren Sie, welche Rollen auf jede Entität zugreifen können. Anforderungen werden anhand der vom Token ermittelten Rolle ausgewertet.

Gewährung von Zugriff für authentifizierte Benutzer

dab update Book \
  --permissions "Authenticated:read"

dab update Book ^
  --permissions "Authenticated:read"

Zugriff auf eine benutzerdefinierte Rolle gewähren

dab update Book \
  --permissions "reader:read" \
  --permissions "writer:create,read,update"

dab update Book ^
  --permissions "reader:read" ^
  --permissions "writer:create,read,update"

Resultierende Konfiguration

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "reader",
          "actions": ["read"]
        },
        {
          "role": "writer",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Schritt 4: Konfigurieren der Datenbankverbindung

Der Daten-API-Generator stellt eine Verbindung mit der Datenbank mithilfe einer eigenen Identität her, getrennt vom authentifizierten Benutzer. Verwenden Sie für Produktionsszenarien mit Azure SQL verwaltete Identität.

Option A: Verwaltete Identität (empfohlen für Azure)

Vom System zugewiesene verwaltete Identität

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;Encrypt=True;"
  }
}

Vom Benutzer zugewiesene verwaltete Identität

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Managed Identity;User Id=<uami-client-id>;Encrypt=True;"
  }
}

Option B: SQL-Authentifizierung (Entwicklung)

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  }
}

Option C: Lokale Entwicklung mit az login

Verwenden Sie für die lokale Entwicklung mit Azure SQL Ihre Azure CLI-Anmeldeinformationen:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Authentication=Active Directory Default;Encrypt=True;"
  }
}

Melden Sie sich vor dem Starten von DAB an:

az login

Schritt 5: Testen der Konfiguration

Autorisieren von Azure CLI als Clientanwendung

Bevor Azure CLI Token für Ihre API abrufen können, müssen Sie sie als autorisierte Clientanwendung hinzufügen.

1. Wechseln Sie in der App-Registrierung zu "Verfügbarmachen einer API".

2. Wählen Sie unter Autorisierte Clientanwendungen die Option Eine Clientanwendung hinzufügen aus.

3. Geben Sie die Azure CLI Client-ID ein: 00001111-aaaa-2222-bbbb-3333cccc4444.

4. Wählen Sie den Bereich api://<app-id>/Endpoint.Access aus.

5. Wählen Sie "Anwendung hinzufügen" aus.

Token mit Azure CLI abrufen

Melden Sie sich bei Azure CLI an, und legen Sie den Mandanten fest, in dem Ihre App-Registrierung vorhanden ist:

az login
az account set --tenant <your-tenant-id>

Fordern Sie ein Token an, das auf Ihre API abgestimmt ist.

az account get-access-token --scope api://<your-app-id>/Endpoint.Access --query "accessToken" -o tsv

Sie können das Token bei jwt.ms inspizieren, um die Ansprüche aud, iss und roles zu überprüfen.

Starten von DAB und Senden einer Anforderung

1. Starten des Daten-API-Generators:

   dab start
   

2. Rufen Sie die API mit dem Token auf:

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

3. 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: reader"
   

Rollenauswahlverhalten

Der Daten-API-Generator bestimmt die Rolle der Anforderung mithilfe dieser Logik:

Problembehandlung

Vollständiges Konfigurationsbeispiel

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=mydb;Authentication=Active Directory Managed Identity;Encrypt=True;"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://dab-api-12345678",
          "issuer": "https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "librarian",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

Verwandte Inhalte

• Autorisierung und Rollen
• Konfigurieren der Simulatorauthentifizierung für Tests
• Konfigurieren der App Service-Authentifizierung
• Referenz zur Laufzeitkonfiguration