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 dostawcę tożsamości innego niż Microsoft Entra, usługa API Management udostępnia również ogólne validate-jwt 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, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    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 Microsoft Entra</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 Microsoft Entra</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>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Atrybuty

Atrybut opis Wymagani Wartość domyślna
tenant-id Identyfikator dzierżawy lub adres URL dzierżawy microsoft Entra ID lub jeden z następujących dobrze znanych dzierżaw:

- organizations lub https://login.microsoftonline.com/organizations — aby zezwolić na tokeny z kont w dowolnym katalogu organizacyjnym (dowolny katalog firmy Microsoft Entra)
- common lub https://login.microsoftonline.com/common — aby zezwolić na tokeny z kont w dowolnym katalogu organizacyjnym (dowolnym katalogu Microsoft Entra) i z osobistych kont Microsoft (na przykład Skype, XBox)

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-name token-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-name token-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-name token-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 Struna. 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.
odszyfrowywanie kluczy Lista podelementów używana do odszyfrowywania tokenu key podpisanego przy użyciu klucza asymetrycznego. Jeśli istnieje wiele kluczy, każdy klucz jest sprawdzany do momentu wyczerpania wszystkich kluczy (w tym przypadku walidacja zakończy się niepowodzeniem) lub klucz zakończy się powodzeniem.

Określ klucz publiczny przy użyciu certificate-id atrybutu z wartością ustawioną na identyfikator certyfikatu przekazanego do usługi API Management.		 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 Struna. 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

atrybuty klucza

Atrybut opis Wymagani Wartość domyślna
identyfikator certyfikatu Identyfikator jednostki certyfikatu przekazanej do usługi API Management, używany do określania klucza publicznego w celu zweryfikowania tokenu podpisanego przy użyciu klucza asymetrycznego. Tak Nie dotyczy

Użycie

  • Sekcje zasad: ruch przychodzący
  • Zakresy zasad: globalny, obszar roboczy, produkt, interfejs API, operacja
  • Bramy: klasyczne, v2, zużycie, self-hosted, obszar roboczy

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. Identyfikator dzierżawy firmy Microsoft to dobrze znana organizations dzierżawa, która umożliwia tokeny z kont w dowolnym katalogu organizacyjnym. Nazwa hosta jest udostępniana przy użyciu wyrażenia zasad, a identyfikator aplikacji klienckiej jest dostarczany przy użyciu nazwanej 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="organizations" 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: