Weryfikowanie JWT

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady validate-jwt wymuszają istnienie i ważność obsługiwanego tokenu internetowego JSON (JWT) wyodrębnionego z określonego nagłówka HTTP, wyodrębnionego z określonego parametru zapytania lub pasującego do określonej wartości.

Uwaga

Aby zweryfikować JWT, który został dostarczony przez usługę Microsoft Entra, usługa API Management udostępnia validate-azure-ad-token również zasady.

Uwaga

Ustaw elementy zasad i elementy podrzędne w kolejności podanej w instrukcji zasad. Aby ułatwić konfigurowanie tych zasad, portal udostępnia edytor oparty na formularzach z przewodnikiem. Dowiedz się więcej na temat ustawiania lub edytowania zasad usługi API Management.

Instrukcja zasad

<validate-jwt
    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"
    require-expiration-time="true | false"
    require-scheme="scheme"
    require-signed-tokens="true | false"
    clock-skew="allowed clock skew in seconds"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
  <openid-config url="full URL of the configuration endpoint, for example, https://login.constoso.com/openid-configuration" />
  <issuer-signing-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent"</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key>Base64 encoded signing key | certificate-id="mycertificate" | n="modulus" e="exponent" </key>
    <!-- if there are multiple keys, then add additional key elements -->
  </decryption-keys>
  <audiences>
    <audience>audience string</audience>
    <!-- if there are multiple possible audiences, then add additional audience elements -->
  </audiences>
  <issuers>
    <issuer>issuer string</issuer>
    <!-- if there are multiple possible issuers, then add additional issuer elements -->
  </issuers>
  <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 claim, then add additional claim elements -->
  </required-claims>
</validate-jwt>

Atrybuty

Atrybut opis Wymagani Wartość domyślna
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 . Nie dotyczy
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".
require-expiration-time Wartość logiczna. Określa, czy oświadczenie wygasania jest wymagane w tokenie. Wyrażenia zasad są dozwolone. Nie. prawda
require-scheme Nazwa schematu tokenu, na przykład "Bearer". Po ustawieniu tego atrybutu zasady zapewnią, że określony schemat znajduje się w wartości nagłówka Autoryzacja. Wyrażenia zasad są dozwolone. Nie. Nie dotyczy
require-signed-tokens (wymagaj tokenów z podpisem) Wartość logiczna. Określa, czy token jest wymagany do podpisania. Wyrażenia zasad są dozwolone. Nie. prawda
zegar-niesymetryczność Timespan. Służy do określania maksymalnej oczekiwanej różnicy czasu między zegarami systemowymi wystawcy tokenu a wystąpieniem usługi API Management. Wyrażenia zasad są dozwolone. Nie. 0 sekund
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
openid-config Dodaj co najmniej jeden z tych elementów, aby określić zgodny adres URL punktu końcowego konfiguracji openID, z którego można uzyskać klucze podpisywania i wystawcę.

Konfiguracja obejmująca zestaw kluczy sieci Web JSON (JWKS) jest pobierana z punktu końcowego co 1 godzinę i buforowana. Jeśli zweryfikowany token odwołuje się do klucza weryfikacji (przy użyciu kid oświadczenia), którego brakuje w konfiguracji buforowanej lub jeśli pobieranie zakończy się niepowodzeniem, usługa API Management ściąga z punktu końcowego co najwyżej raz na 5 minut. Te interwały mogą ulec zmianie bez powiadomienia.

Odpowiedź powinna być zgodna ze specyfikacjami zdefiniowanymi pod adresem URL: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

W przypadku identyfikatora Entra firmy Microsoft użyj punktu końcowego metadanych openID Połączenie skonfigurowanego w rejestracji aplikacji, takiego jak:
- wersja 2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
- Wersja 2 z wieloma dzierżawami https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
- wersja 1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
— Dzierżawa klienta (wersja zapoznawcza) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

Podstawianie nazwy lub identyfikatora dzierżawy katalogu, na przykład contoso.onmicrosoft.com, dla {tenant-name}.		 Nie.
klucze podpisywania wystawcy Lista kluczy zabezpieczeń zakodowanych w formacie Base64 w key podelementach używanych do weryfikowania podpisanych tokenów. Jeśli istnieje wiele kluczy zabezpieczeń, każdy klucz jest sprawdzany do momentu wyczerpania wszystkich (w tym przypadku walidacja nie powiedzie się) lub jednego z nich zakończy się powodzeniem (przydatne w przypadku przerzucania tokenu).

Opcjonalnie określ klucz przy użyciu atrybutu id , aby dopasować kid oświadczenie. Aby zweryfikować token podpisany przy użyciu klucza asymetrycznego, opcjonalnie określ klucz publiczny przy użyciu atrybutu z wartością certificate-id identyfikatora certyfikatu przekazanego do usługi API Management lub modulu n RSA i pary wykładniczej e klucza podpisywania w formacie zakodowanym w formacie Base64url.		 Nie.
odszyfrowywanie kluczy Lista kluczy zakodowanych w formacie Base64 w key podelementach używanych do odszyfrowywania tokenów. Jeśli istnieje wiele kluczy zabezpieczeń, każdy klucz jest sprawdzany do momentu wyczerpania wszystkich kluczy (w tym przypadku walidacja zakończy się niepowodzeniem) lub klucz zakończy się powodzeniem.

Opcjonalnie określ klucz przy użyciu atrybutu id , aby dopasować kid oświadczenie. Aby odszyfrować token zaszyfrowany przy użyciu klucza asymetrycznego, opcjonalnie określ klucz publiczny przy użyciu atrybutu z wartością certificate-id identyfikatora certyfikatu przekazanego do usługi API Management lub modulo n RSA i parę wykładniczą e klucza w formacie zakodowanym w formacie Base64url.		 Nie.
Odbiorców Lista akceptowalnych oświadczeń odbiorców w audience podelementach, które mogą być obecne w tokenie. Jeśli istnieje wiele wartości odbiorcó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. Należy określić co najmniej jedną grupę odbiorców. Nie.
Emitentów Lista dopuszczalnych podmiotów zabezpieczeń w issuer podelementach, które wystawiły token. Jeśli istnieje wiele wartości wystawcy, każda wartość jest podejmowana do momentu wyczerpania wszystkich (w tym przypadku walidacja zakończy się niepowodzeniem) lub do momentu pomyślnego zakończenia. Nie.
required-claims Lista oświadczeń w claim podelementach powinna być obecna na tokenie, aby była uznawana za prawidłową. Gdy istnieje wiele oświadczeń, token musi odpowiadać wartościom oświadczenia zgodnie z wartością atrybutu match . Nie.

atrybuty klucza

Atrybut opis Wymagani Wartość domyślna
identyfikator Ciąg. Identyfikator używany do dopasowania kid oświadczenia przedstawionego w JWT. Nie. Nie dotyczy
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. Nie. Nie dotyczy
n Modulo klucza publicznego używanego do weryfikowania wystawcy tokenu podpisanego przy użyciu klucza asymetrycznego. Musi być określony z wartością wykładnika e. Wyrażenia zasad nie są dozwolone. Nie. Nie dotyczy
e Wykładnik klucza publicznego używany do weryfikowania wystawcy tokenu podpisanego przy użyciu klucza asymetrycznego. Musi być określony z wartością modulusa n. Wyrażenia zasad nie są dozwolone. Nie. Nie dotyczy

atrybuty oświadczenia

Atrybut opis Wymagani Wartość domyślna
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.		 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. Nie. Nie dotyczy

Użycie

Uwagi dotyczące użycia

  • Zasady validate-jwt wymagają, aby zarejestrowane oświadczenie zostało uwzględnione w tokenie JWT, chyba że exprequire-expiration-time określono atrybut i ustawiono wartość false.
  • Zasady obsługują zarówno algorytmy symetryczne, jak i asymetryczne podpisywania:
    • Symetryczne — obsługiwane są następujące algorytmy szyfrowania: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
      • W przypadku użycia w zasadach klucz musi być podany w tekście w ramach zasad w postaci zakodowanej w formacie Base64.
    • Asymetryczne — obsługiwane są następujące algortithmy szyfrowania: PS256, RS256, RS512.
      • Jeśli są używane w zasadach, klucz może być dostarczony za pośrednictwem punktu końcowego konfiguracji OpenID lub podając identyfikator przekazanego certyfikatu (w formacie PFX), który zawiera klucz publiczny lub modulus-wykładnik pary klucza publicznego.
  • Aby skonfigurować zasady z jednym lub kilkoma punktami końcowymi konfiguracji OpenID do użytku z bramą hostowaną samodzielnie, adresy URL punktów końcowych konfiguracji OpenID muszą być również osiągalne przez bramę w chmurze.
  • 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-jwt zasady na poziomie interfejsu API lub stosując je na poziomie operacji interfejsu API i użyć claims do bardziej szczegółowej kontroli.
  • W przypadku używania nagłówka niestandardowego (header-name) skonfigurowany wymagany schemat (require-scheme) zostanie zignorowany. Aby użyć wymaganego schematu, tokeny JWT muszą być podane w nagłówku Authorization .

Przykłady

Prosta walidacja tokenu

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key>  <!-- signing key specified as a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Weryfikacja tokenu przy użyciu certyfikatu RSA

<validate-jwt header-name="Authorization" require-scheme="Bearer">
    <issuer-signing-keys>
        <key certificate-id="my-rsa-cert" />  <!-- signing key specified as certificate ID, enclosed in double-quotes -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>  <!-- audience is set to API Management host name -->
    </audiences>
    <issuers>
        <issuer>http://contoso.com/</issuer>
    </issuers>
</validate-jwt>

Weryfikacja pojedynczego tokenu dzierżawy identyfikatora entra firmy Microsoft

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/contoso.onmicrosoft.com/.well-known/openid-configuration" />
    <audiences>
        <audience>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Weryfikacja tokenu dzierżawy klienta identyfikatora entra firmy Microsoft

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
	<openid-config url="https://<tenant-name>.ciamlogin.com/<tenant-id>/v2.0/.well-known/openid-configuration" />
	<required-claims>
		<claim name="azp" match="all">
			<value>insert claim here</value>
		</claim>
	</required-claims>
</validate-jwt>

Weryfikacja tokenu B2C w usłudze Azure Active Directory

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/tfp/contoso.onmicrosoft.com/b2c_1_signin/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Autoryzowanie dostępu do operacji na podstawie oświadczeń tokenów

W tym przykładzie pokazano, jak za pomocą validate-jwt zasad autoryzować dostęp do operacji na podstawie wartości oświadczeń tokenu.

<validate-jwt header-name="Authorization" require-scheme="Bearer" output-token-variable-name="jwt">
    <issuer-signing-keys>
        <key>{{jwt-signing-key}}</key> <!-- signing key is stored in a named value -->
    </issuer-signing-keys>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <issuers>
        <issuer>contoso.com</issuer>
    </issuers>
    <required-claims>
        <claim name="group" match="any">
            <value>finance</value>
            <value>logistics</value>
        </claim>
    </required-claims>
</validate-jwt>
<choose>
    <when condition="@(context.Request.Method == "POST" && !((Jwt)context.Variables["jwt"]).Claims["group"].Contains("finance"))">
        <return-response>
            <set-status code="403" reason="Forbidden" />
        </return-response>
    </when>
</choose>

Powiązana zawartość

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