Udostępnij przez

Konfiguracja uwierzytelniania Microsoft Entra ID

Ten przewodnik przeprowadzi Cię przez proces konfigurowania uwierzytelniania Microsoft Entra ID (dawniej Azure Active Directory) dla Data API Builder. Pod koniec aplikacja kliencka uwierzytelnia użytkowników za pośrednictwem Entra, uzyskuje tokeny dla konstruktora Data API, a DAB może używać tożsamości zarządzanej do nawiązywania połączenia z Azure SQL.

Konstruktor interfejsu API danych uwierzytelnia żądania przychodzące przy użyciu walidacji elementu nośnego JWT (EntraID/AzureAD/Custom) lub nagłówków tożsamości udostępnianych przez platformę ().AppService W przypadku lokalnego programowania i testowania uprawnień użyj dostawcy Simulator .

Ilustracja przedstawiająca sposób uwierzytelniania klientów w konstruktorze interfejsu API danych przy użyciu tokenów JWT.

Przewodniki dotyczące dostawców uwierzytelniania

Wybierz przewodnik na podstawie swojego dostawcy tożsamości:

Provider Guide
Microsoft Entra ID Ten artykuł
Okta, Auth0 lub inne Konfigurowanie niestandardowego uwierzytelniania JWT
Azure App Service Konfigurowanie uwierzytelniania usługi App Service
Testowanie lokalne Konfigurowanie uwierzytelniania symulatora

Przepływ uwierzytelniania

Na poniższym diagramie przedstawiono pełny przepływ uwierzytelniania podczas korzystania z identyfikatora Entra firmy Microsoft z konstruktorem interfejsu API danych:

Ilustracja sekwencji uwierzytelniania identyfikatora entra firmy Microsoft przedstawiająca logowanie użytkownika, pozyskiwanie tokenów i dostęp do bazy danych.

Przepływ ma trzy odrębne fazy:

Phase Description
Uwierzytelnianie użytkownika Użytkownik loguje się za pośrednictwem aplikacji klienckiej za pośrednictwem identyfikatora Entra firmy Microsoft
Uwierzytelnianie klienta Aplikacja kliencka uzyskuje token o zakresie DAB i wywołuje konstruktora interfejsu API danych
Dostęp do bazy danych Konstruktor interfejsu API danych weryfikuje token, a następnie łączy się z bazą danych przy użyciu własnej tożsamości (tożsamości zarządzanej lub poświadczeń parametrów połączenia)

Ważne

Konstruktor interfejsu API danych weryfikuje przychodzący token użytkownika na potrzeby uwierzytelniania interfejsu API, ale nawiązuje połączenie z bazą danych przy użyciu własnych poświadczeń (tożsamości zarządzanej lub uwierzytelniania SQL). DAB nie wykonuje wymiany tokenów on-behalf-of (OBO) w celu uzyskania dostępu do bazy danych w imieniu użytkownika wywołującego.

Wymagania wstępne

  • Subskrypcja platformy Azure z dzierżawą microsoft Entra ID
  • Zainstalowany interfejs wiersza polecenia konstruktora interfejsu API danych (przewodnik instalacji)
  • Istniejąca dab-config.json z co najmniej jedną encją
  • (Opcjonalnie) Azure SQL Database dla scenariuszy z tożsamością zarządzaną

Krótki przewodnik

Setting Wartość
Provider EntraID (lub AzureAD w celu zachowania zgodności)
Wymagane do weryfikacji aud, , iss, expprawidłowy podpis
Wymagane do autoryzacji roles oświadczenie (tylko w przypadku korzystania z ról niestandardowych)
Format wystawcy https://login.microsoftonline.com/<tenant-id>/v2.0
Format odbiorców api://<app-id> lub niestandardowy identyfikator URI identyfikatora aplikacji
Rola domyślna Authenticated
Nagłówek roli niestandardowej X-MS-API-ROLE
Typ oświadczenia roli roles (naprawiono, nie można skonfigurować)

Uwaga / Notatka

Podczas korzystania z EntraID lub AzureAD jako dostawcy, DAB pozwala na specyficzną dla tokenów firmy Microsoft Entra dodatkową walidację wystawcy klucza podpisywania. Zapewnia to silniejsze zabezpieczenia w porównaniu z dostawcą ogólnym Custom .

Krok 1. Rejestrowanie aplikacji w identyfikatorze Entra firmy Microsoft

Utwórz rejestrację aplikacji, która reprezentuje Twój interfejs API w Data API builder. Aplikacje klienckie będą żądać tokenów z adresem odbiorcy pasującym do tej rejestracji.

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra.

  2. Przejdź do Tożsamość>Aplikacje>Rejestracje aplikacji.

  3. Wybierz opcję Nowa rejestracja.

  4. Wprowadź nazwę (na przykład Data API Builder API).

  5. Wybierz odpowiednie obsługiwane typy kont dla danego scenariusza:

    • Pojedynczy tenant: tylko użytkownicy w twojej organizacji
    • Multitenant: użytkownicy w dowolnym katalogu Microsoft Entra

  6. Pozostaw pusty identyfikator URI przekierowania (ta rejestracja dotyczy interfejsu API, a nie klienta).

  7. Wybierz pozycję Zarejestruj.

  8. Na stronie Przegląd aplikacji zapisz następujące wartości:

    Wartość Gdzie go znaleźć Służy do
    Identyfikator aplikacji (klienta) Strona przeglądu Tworzenie identyfikatora URI użytkowników
    Identyfikator katalogu (klienta) Strona przeglądu Budowanie adresu URL wystawcy

Konfiguracja identyfikatora URI aplikacji

  1. W rejestracji aplikacji przejdź do sekcji Uwidacznianie interfejsu API.

  2. Wybierz Dodaj obok Identyfikator URI aplikacji.

  3. Zaakceptuj wartość domyślną (api://<app-id>) lub wprowadź niestandardowy identyfikator URI.

  4. Wybierz Zapisz.

Wskazówka

URI Identyfikatora Aplikacji staje się wartością audience w konfiguracji DAB. Używaj spójnego formatu w różnych środowiskach.

Dodawanie ról aplikacji (opcjonalnie)

Jeśli chcesz używać ról niestandardowych poza Anonymous i Authenticated:

  1. Przejdź do Ról aplikacji.

  2. Wybierz pozycję Utwórz rolę aplikacji.

  3. Wejść:

    • Wyświetlana nazwa: Reader
    • Dozwolone typy elementów członkowskich: Użytkownicy/grupy lub Oba
    • Wartość: reader (ta wartość jest wyświetlana w oświadczeniu tokenu roles )
    • Opis: Read-only access to data

  4. Wybierz i zastosuj.

  5. Powtórz dla dodatkowych ról (na przykład writer, admin).

Krok 2. Konfigurowanie konstruktora interfejsu API danych

Skonfiguruj DAB, aby zweryfikować tokeny wydane przez dzierżawę Entra dla odbiorców interfejsu API.

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"

Konfiguracja wyniku

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

Krok 3. Konfigurowanie uprawnień jednostki

Zdefiniuj, które role mogą uzyskiwać dostęp do każdej jednostki. Żądania są oceniane względem roli określonej na podstawie tokenu.

Udzielanie dostępu do uwierzytelnionych użytkowników

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

Udzielanie dostępu do roli niestandardowej

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

Konfiguracja wyniku

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

Krok 4. Konfigurowanie połączenia z bazą danych

Konstruktor interfejsu API danych łączy się z bazą danych przy użyciu własnej tożsamości, niezależnie od uwierzytelnionego użytkownika. W przypadku scenariuszy produkcyjnych z usługą Azure SQL użyj tożsamości zarządzanej.

Uwaga / Notatka

Połączenie z bazą danych używa tożsamości usługi (tożsamości zarządzanej lub poświadczeń SQL) języka DAB, a nie tożsamości użytkownika wywołującego. DAB nie przekazuje tokenów użytkownika do bazy danych.

Zarządzana tożsamość przypisana przez system

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

Tożsamość zarządzana przypisana użytkownikowi

{
  "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;"
  }
}

Opcja B: uwierzytelnianie SQL (programowanie)

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

Ważne

Nigdy nie zatwierdzaj parametrów połączenia przy użyciu haseł do kontroli źródła. Użyj zmiennych środowiskowych lub usługi Azure Key Vault.

Opcja C: Programowanie lokalne za pomocą polecenia az login

W przypadku lokalnego programowania w usłudze Azure SQL użyj poświadczeń interfejsu wiersza polecenia platformy Azure:

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

Przed rozpoczęciem DAB zaloguj się.

az login

Krok 5. Testowanie konfiguracji

  1. Uruchom konstruktora interfejsu API danych:

    dab start

  2. Uzyskaj token dla interfejsu API. Użyj biblioteki Microsoft Authentication Library (MSAL) lub narzędzia, takiego jak jwt.ms do testowania.

  3. Wywołaj interfejs API przy użyciu tokenu:

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

  4. Aby użyć roli niestandardowej, dołącz nagłówek X-MS-API-ROLE.

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

Uwaga / Notatka

Rola określona w X-MS-API-ROLE musi istnieć w oświadczeniu roles tokenu. Jeśli rola nie znajduje się w tokenie, żądanie zostanie odrzucone.

Zachowanie wyboru roli

Konstruktor interfejsu API danych określa rolę żądania przy użyciu tej logiki:

Token obecny? X-MS-API-ROLE nagłówek? Rola w tokenie? Wynik
Nie. Nie. — Anonymous
Tak (prawidłowe) Nie. — Authenticated
Tak (prawidłowe) Tak Nie. Odrzucono (403 Zabronione)
Tak (prawidłowe) Tak Tak Wartość nagłówka
Tak (nieprawidłowe) — — Odrzucono (401 Brak autoryzacji)

Rozwiązywanie problemów

Objaw Możliwa przyczyna Rozwiązanie
401 Unauthorized Token wygasł lub jest błędnie sformatowany Uzyskiwanie nowego tokenu; sprawdzanie tokenu w jwt.ms
401 Unauthorized Niezgodność odbiorców Sprawdź, czy jwt.audience jest zgodne z oświadczeniem tokenu aud
401 Unauthorized Niezgodność wystawcy Sprawdź, czy jwt.issuer dokładnie pasuje do roszczenia iss tokenu
403 Forbidden Rola nie jest zawarta w tokenie Upewnij się, że użytkownik ma przypisaną rolę aplikacji w aplikacji Entra
403 Forbidden Brak uprawnień dla roli Dodawanie roli do tablicy permissions jednostki

Kompletny przykład konfiguracji

{
  "$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"]
        }
      ]
    }
  }
}

Treści powiązane

  • Last updated on