Udostępnij przez

Konfigurowanie uwierzytelniania usługi App Service (EasyAuth)

Usługa Azure App Service zapewnia wbudowane uwierzytelnianie (często nazywane "EasyAuth"), które obsługuje logowanie użytkownika przed dotarciem do aplikacji. Konstruktor interfejsu API danych może odczytywać informacje o tożsamości wprowadzone przez usługę App Service, włączając uwierzytelnianie bez bezpośredniego zarządzania tokenami.

Ważne

Dostawca AppService ufa nagłówkom tożsamości przekazywanym przez usługę EasyAuth. Upewnij się, że klienci nie mogą pominąć funkcji EasyAuth i bezpośrednio nawiązać połączenia z konstruktorem interfejsu API danych.

Przepływ uwierzytelniania

Gdy konstruktor interfejsu API danych działa za usługą Azure App Service z włączonym uwierzytelnianiem, usługa App Service obsługuje przepływ OAuth i przekazuje informacje o tożsamości za pośrednictwem nagłówków HTTP:

Ilustracja przepływu uwierzytelniania usługi App Service przedstawiająca sposób, w jaki usługa EasyAuth wprowadza nagłówki tożsamości.

Phase Co się stanie
Uwierzytelnianie użytkownika Usługa App Service przechwytuje nieuwierzytelnione żądania i przekierowuje je do dostawcy tożsamości.
Wstrzykiwanie tożsamości Po uwierzytelnieniu usługa App Service dodaje nagłówek X-MS-CLIENT-PRINCIPAL
Przetwarzanie DAB Konstruktor interfejsu API danych Base64 dekoduje kod JSON nagłówka i tworzy element ClaimsPrincipal z tablicy claims
Authorization DAB używa ClaimsPrincipal.IsInRole() do walidowania nagłówka X-MS-API-ROLE, a następnie ocenia uprawnienia i polityki

Wymagania wstępne

  • Subskrypcja platformy Azure
  • Azure App Service lub Azure Functions (w infrastrukturze usługi App Service)
  • Zainstalowany interfejs wiersza polecenia konstruktora interfejsu API danych (przewodnik instalacji)
  • Istniejąca dab-config.json z co najmniej jedną encją

Krótki przewodnik

Setting Wartość
Provider AppService
Nagłówek tożsamości X-MS-CLIENT-PRINCIPAL (Kodowanie JSON zakodowane w formacie Base64)
Nagłówek wyboru roli X-MS-API-ROLE
Obsługuje roszczenia niestandardowe Tak
Testowanie lokalne Tak (ręcznie ustaw nagłówki)

Krok 1. Włączanie uwierzytelniania w usłudze App Service

Konfigurowanie uwierzytelniania w usłudze Azure App Service:

  1. W witrynie Azure Portal przejdź do usługi App Service.

  2. Wybierz Ustawienia>Uwierzytelnianie.

  3. Wybierz Dodaj dostawcę tożsamości.

  4. Wybierz Microsoft (lub innego obsługiwanego dostawcę).

  5. Skonfiguruj ustawienia:

    • Typ rejestracji aplikacji: Utwórz nową lub wybierz istniejącą
    • Obsługiwane typy kont: wybierz na podstawie scenariusza
    • Ograniczanie dostępu: wymaganie uwierzytelniania

  6. Wybierz Dodaj.

Wskazówka

Uwierzytelnianie usługi App Service współpracuje z wieloma dostawcami tożsamości, takimi jak Microsoft, Google, Facebook, Twitter i OpenID Connect.

Krok 2. Konfigurowanie konstruktora interfejsu API danych

Ustaw dostawcę uwierzytelniania na :AppService

CLI

dab configure \
  --runtime.host.authentication.provider AppService

Konfiguracja wyniku

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

Uwaga / Notatka

W przeciwieństwie do EntraID/AzureAD lub dostawców Custom, AppService nie wymaga ustawień jwt.audience ani jwt.issuer. Usługa App Service weryfikuje token przed przekazaniem informacji o tożsamości do DAB.

Krok 3. Konfigurowanie uprawnień jednostki

Definiowanie uprawnień dla ról. Konstruktor interfejsu API danych ocenia role za pomocą metody ClaimsPrincipal.IsInRole(), która sprawdza oświadczenia analizowane z nagłówka X-MS-CLIENT-PRINCIPAL . Uwzględnij w tablicy claims żądania ról z odpowiednim typem żądania.

Przykładowa konfiguracja

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

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

Konfiguracja wyniku

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Krok 4. Testy lokalne przy użyciu X-MS-CLIENT-PRINCIPAL

Możesz przetestować uwierzytelnianie usługi App Service lokalnie, ręcznie podając nagłówek X-MS-CLIENT-PRINCIPAL. To podejście symuluje sposób, w jaki usługa EasyAuth przekazuje informacje do aplikacji i pozwala testować zachowanie oparte na rolach oraz roszczeniach bez konieczności wdrażania na Azure.

Utwórz klienta głównego

Nagłówek X-MS-CLIENT-PRINCIPAL zawiera obiekt JSON zakodowany w formacie Base64. Konstruktor interfejsu API danych analizuje następujące właściwości:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Koduj podmiot

Zakoduj kod JSON jako Base64. Możesz użyć dowolnego narzędzia:

PowerShell

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Bash:

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Wysyłanie żądania z nagłówkiem

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

Struktura X-MS-CLIENT-PRINCIPAL

Konstruktor interfejsu API danych analizuje następujące właściwości z jednostki klienta:

Majątek Typ Description
auth_typ ciąg Typ uwierzytelniania (na przykład aad). Wymagane do uwierzytelniania tożsamości.
name_typ ciąg (Opcjonalnie) Typ oświadczenia używany dla nazwy użytkownika
role_typ ciąg (Opcjonalnie) Typ deklaracji używany dla ról (domyślnie jest roles)
claims obiekt[] Zestaw roszczeń z właściwościami typ i val. Role muszą być tutaj uwzględnione jako oświadczenia.

Ważne

Role są oceniane za pomocą metody ClaimsPrincipal.IsInRole(), która sprawdza tablicę claims pod kątem pasujących do role_typ elementów. Dołącz każdą rolę jako oddzielny wpis oświadczenia (na przykład { "typ": "roles", "val": "editor" }).

Używanie oświadczeń w zasadach bazy danych

Za pomocą dostawcy usługi AppService można używać oświadczeń w zasadach bazy danych. Umożliwia to zabezpieczenia na poziomie wiersza na podstawie tożsamości użytkownika.

Przykład: filtrowanie według identyfikatora obiektu użytkownika

W tym przykładzie użyto oświadczenia oid (identyfikatora obiektu), które Microsoft Entra ID zawiera w tokenach:

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Wskazówka

Typowe typy oświadczeń z usługi Microsoft Entra ID obejmują oid (identyfikator obiektu), email, name i preferred_username. Użyj dokładnego ciągu typu oświadczenia od dostawcy tożsamości.

Dostępne odniesienia do roszczeń

Odwołania do roszczeń używają dokładnych ciągów typu roszczenia z tablicy claims.

Numer referencyjny roszczenia Description
@claims.<claim-type> Dowolne oświadczenie z claims tablicy dopasowane przez typ właściwość

Na przykład, jeśli twój główny podmiot zawiera { "typ": "email", "val": "alice@contoso.com" }, użyj @claims.email w swojej polityce. Typ oświadczenia musi być dokładnie zgodny.

Żądania anonimowe

Gdy usługa App Service zezwala na nieuwierzytelnione żądania lub w przypadku testowania lokalnego bez nagłówka X-MS-CLIENT-PRINCIPAL, oprogramowanie pośredniczące uwierzytelniania Data API builder automatycznie ustawia nagłówek X-MS-API-ROLE na anonymous. Żądania są następnie oceniane przy użyciu anonymous roli:

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Aby ta funkcja działała, jednostka musi mieć uprawnienia do anonymous roli:

{
  "permissions": [
    {
      "role": "anonymous",
      "actions": ["read"]
    }
  ]
}

Rozwiązywanie problemów

Objaw Możliwa przyczyna Rozwiązanie
401 Unauthorized (lub przekieruj do logowania) Usługa EasyAuth zablokowała żądanie, zanim dotarło do języka DAB Zaloguj się za pomocą usługi EasyAuth lub wyślij prawidłowe poświadczenia; weryfikowanie ustawień uwierzytelniania usługi App Service
403 Forbidden Rola nie znajduje się w uprawnieniach Dodawanie roli do uprawnień jednostki
403 Forbidden X-MS-API-ROLE nie znajduje się w rolach użytkownika Upewnij się, że wartość nagłówka pasuje do roszczenia roli w tablicy głównego claims.
Oświadczenia są niedostępne Brak claims tablicy w głównym elemencie Dodawanie oświadczeń do formatu X-MS-CLIENT-PRINCIPAL JSON
Rola nie została rozpoznana Role, które nie są w claims tablicy Dodaj atrybuty ról z poprawnym role_typ (na przykład { "typ": "roles", "val": "editor" })
Testowanie lokalne kończy się niepowodzeniem Nagłówek nie zakodowany w formacie Base64 Zakoduj poprawnie kod JSON przed wysłaniem

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": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Treści powiązane

  • Last updated on