Weryfikowanie tokenu firmy Microsoft Entra

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady validate-azure-ad-token wymuszają istnienie i ważność tokenu internetowego JSON (JWT), który został dostarczony przez usługę Microsoft Entra (dawniej o nazwie Azure Active Directory) dla określonego zestawu podmiotów zabezpieczeń w katalogu. Zestaw JWT można wyodrębnić z określonego nagłówka HTTP, parametru zapytania lub wartości udostępnionej przy użyciu wyrażenia zasad lub zmiennej kontekstowej.

Uwaga

Aby zweryfikować JWT, który został dostarczony przez innego dostawcę tożsamości, usługa API Management udostępnia validate-jwt również ogólne zasady.

Uwaga

Ustaw elementy zasad i elementy podrzędne w kolejności podanej w instrukcji zasad. Dowiedz się więcej na temat ustawiania lub edytowania zasad usługi API Management.

Instrukcja zasad

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Azure Active Directory</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Azure Active Directory</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
</validate-azure-ad-token>

Atrybuty

Atrybut opis Wymagani Wartość domyślna
tenant-id Identyfikator dzierżawy lub adres URL usługi Microsoft Entra. Wyrażenia zasad są dozwolone. Tak Nie dotyczy
nazwa nagłówka Nazwa nagłówka HTTP zawierającego token. Wyrażenia zasad są dozwolone. Należy określić jedną z header-namewartości lub query-parameter-nametoken-value . Authorization
query-parameter-name Nazwa parametru zapytania zawierającego token. Wyrażenia zasad są dozwolone. Należy określić jedną z header-namewartości lub query-parameter-nametoken-value . Nie dotyczy
token-value Wyrażenie zwracające ciąg zawierający token. Nie można zwracać Bearer jako części wartości tokenu. Wyrażenia zasad są dozwolone. Należy określić jedną z header-namewartości lub query-parameter-nametoken-value . Nie dotyczy
failed-validation-httpcode Kod stanu HTTP, który ma być zwracany, jeśli zestaw JWT nie przejdzie walidacji. Wyrażenia zasad są dozwolone. Nie. 401
komunikat o błędzie sprawdzania poprawności nie powiodło się Komunikat o błędzie zwracany w treści odpowiedzi HTTP, jeśli zestaw JWT nie przejdzie walidacji. Ten komunikat musi mieć poprawnie znaki specjalne. Wyrażenia zasad są dozwolone. Nie. Domyślny komunikat o błędzie zależy od problemu z walidacją, na przykład "JWT not present".
output-token-variable-name Ciąg. Nazwa zmiennej kontekstowej, która będzie otrzymywać wartość tokenu jako obiekt typu Jwt po pomyślnej weryfikacji tokenu. Wyrażenia zasad nie są dozwolone. Nie. Nie dotyczy

Elementy

Element opis Wymagania
Odbiorców Zawiera listę akceptowalnych oświadczeń odbiorców, które mogą być obecne w tokenie. Jeśli istnieje wiele audience wartości, każda wartość jest podejmowana do momentu wyczerpania wszystkich (w tym przypadku walidacja zakończy się niepowodzeniem) lub do momentu pomyślnego zakończenia. Wyrażenia zasad są dozwolone. Nie.
backend-application-ids Zawiera listę dopuszczalnych identyfikatorów aplikacji zaplecza. Jest to wymagane tylko w zaawansowanych przypadkach konfiguracji opcji i można je zazwyczaj usunąć. Wyrażenia zasad nie są dozwolone. Nie.
client-application-ids Zawiera listę dopuszczalnych identyfikatorów aplikacji klienckich. Jeśli istnieje wiele application-id elementów, każda wartość jest podejmowana do momentu wyczerpania wszystkich (w tym przypadku walidacja zakończy się niepowodzeniem) lub do momentu pomyślnego zakończenia. Jeśli nie podano identyfikatora aplikacji klienckiej, należy określić co najmniej jedno audience oświadczenie. Wyrażenia zasad nie są dozwolone. Nie.
required-claims Zawiera listę elementów dla claim wartości oświadczeń, które powinny być obecne w tokenie, który ma być uznawany za prawidłowy. match Gdy atrybut jest ustawiony na allwartość , każda wartość oświadczenia w zasadach musi być obecna w tokenie, aby walidacja zakończyła się pomyślnie. match Gdy atrybut jest ustawiony na any, co najmniej jedno oświadczenie musi znajdować się w tokenie, aby walidacja zakończyła się pomyślnie. Wyrażenia zasad są dozwolone. Nie.

atrybuty oświadczenia

Atrybut opis Wymagani Wartość domyślna
name Nazwa oświadczenia, jak oczekiwano, w tokenie. Wyrażenia zasad są dozwolone. Tak Nie dotyczy
match Atrybut match w elemecie claim określa, czy każda wartość oświadczenia w zasadach musi znajdować się w tokenie, aby walidacja zakończyła się pomyślnie. Dopuszczalne wartości:

- all — każda wartość oświadczenia w zasadach musi być obecna w tokenie, aby walidacja zakończyła się pomyślnie.

- any — co najmniej jedna wartość oświadczenia musi znajdować się w tokenie, aby walidacja zakończyła się pomyślnie.

Wyrażenia zasad są dozwolone.		 Nie. wszystkie
Separator Ciąg. Określa separator (na przykład ","), który ma być używany do wyodrębniania zestawu wartości z oświadczenia wielowartościowego. Wyrażenia zasad są dozwolone. Nie. Nie dotyczy

Użycie

Uwagi dotyczące użycia

  • Zasad ograniczeń dostępu można używać w różnych zakresach do różnych celów. Na przykład można zabezpieczyć cały interfejs API za pomocą uwierzytelniania firmy Microsoft Entra, stosując validate-azure-ad-token zasady na poziomie interfejsu API lub stosując je na poziomie operacji interfejsu API i użyć claims do bardziej szczegółowej kontroli.
  • Identyfikator Entra firmy Microsoft dla klientów (wersja zapoznawcza) nie jest obsługiwany.

Przykłady

Prosta walidacja tokenu

Poniższe zasady są minimalną formą validate-azure-ad-token zasad. Oczekuje się, że JWT zostanie podany w domyślnym Authorization nagłówku przy użyciu schematu Bearer . W tym przykładzie identyfikator dzierżawy firmy Microsoft i identyfikator aplikacji klienckiej są udostępniane przy użyciu nazwanych wartości.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Sprawdź, czy odbiorcy i oświadczenia są poprawne

Poniższe zasady sprawdzają, czy odbiorcą jest nazwa hosta wystąpienia usługi API Management i czy ctry oświadczenie to US. Nazwa hosta jest udostępniana przy użyciu wyrażenia zasad, a identyfikator dzierżawy Firmy Microsoft Entra i identyfikator aplikacji klienckiej są udostępniane przy użyciu nazwanych wartości. Zdekodowany zestaw JWT jest udostępniany w zmiennej jwt po weryfikacji.

Aby uzyskać więcej informacji na temat opcjonalnych oświadczeń, przeczytaj Artykuł Zapewnianie opcjonalnych oświadczeń do aplikacji.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Powiązana zawartość

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: