Validation de jeton JWT

S’APPLIQUE À : tous les niveaux de Gestion des API

La validate-jwt stratégie applique l’existence et la validité d’un jeton web JSON pris en charge (JWT) fourni par un fournisseur d’identité. Le JWT peut être extrait à partir d’un en-tête HTTP spécifié, extrait à partir d’un paramètre de requête spécifié, ou correspondant à une valeur spécifique.

Instruction de la stratégie

<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" validate-connectivity="true | false"/>
  <issuer-signing-keys>
    <key id="kid-claim" certificate-id="mycertificate" n="modulus" e="exponent">Base64 encoded signing key</key>
    <!-- if there are multiple keys, then add additional key elements -->
  </issuer-signing-keys>
  <decryption-keys>
    <key certificate-id="mycertificate">Base64 encoded signing key</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>

Attributs

Éléments

attributs de clé

attributs de revendication

Utilisation

• Sections de la stratégie : inbound
• Étendues de la stratégie : global, espace de travail, produit, API, opération
• Passerelles : classiques, v2, consommation, auto-hébergées, espace de travail

Notes d’utilisation

• La validate-jwt stratégie exige que la exp revendication inscrite soit incluse dans le JWT, sauf si require-expiration-time l’attribut est spécifié et défini sur false.
• La stratégie prend en charge les algorithmes de signature symétriques et asymétriques :
  • Symétrique : les algorithmes de chiffrement suivants sont pris en charge : A128CBC-HS256, A192CBC-HS384, A256CBC-HS512.
    • Si elle est utilisée dans la stratégie, la clé doit être fournie en ligne au sein de la stratégie au format encodé en Base64.
  • Asymétrique : les algorithmes de chiffrement suivants sont pris en charge : PS256, RS256, RS512, ES256.
    • Si elle est utilisée dans la stratégie, la clé peut être fournie soit via un point de terminaison de configuration OpenID, soit en spécifiant l’ID d’un certificat chargé (au format PFX) qui contient la clé publique ou la paire modulo-exposant de la clé publique.
• Si l’instance Gestion des API est injectée ou intégrée dans un réseau virtuel et openid-config les URL de point de terminaison sont configurées dans la stratégie, définissez l’attribut pour false désactiver la validate-connectivity vérification de la disponibilité des points de terminaison.
• Vous pouvez utiliser des stratégies de restriction d’accès dans différentes étendues à des fins différentes. Par exemple, vous pouvez sécuriser toute l’API avec l’authentification Microsoft Entra en appliquant la stratégie validate-jwt au niveau de l’API, ou vous pouvez l’appliquer au niveau de l’opération d’API et utiliser claims pour un contrôle plus précis.
• Lors de l’utilisation d’un en-tête personnalisé (header-name), le schéma requis configuré (require-scheme) est ignoré. Pour utiliser un schéma requis, les JWT doivent être fournis dans l’en-tête Authorization .

Exemples

Validation simple du jeton

<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>

Validation de jeton avec certificat 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>

validation de jeton à locataire unique Microsoft Entra ID

<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>00001111-aaaa-2222-bbbb-3333cccc4444</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

validation des jetons de locataire client Microsoft Entra ID

<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>

validation de jeton Azure Active Directory B2C

<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>11112222-bbbb-3333-cccc-4444dddd5555</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Validation du jeton à l'aide de la clé de décryptage

Cet exemple montre comment utiliser la validate-jwt stratégie pour valider un jeton déchiffré à l’aide d’une clé de déchiffrement. La clé est spécifiée à l'aide de l'identifiant d'un certificat téléchargé (au format PFX) qui contient la clé publique.

<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>
    <decryption-keys>
        <key certificate-id="my-certificate-in-api-management" /> <!-- decryption key specified as certificate ID -->
    </decryption-keys>
</validate-jwt>

Autoriser l’accès aux opérations à partir de revendications de jetons

Cet exemple montre comment utiliser la stratégie pour autoriser l’accès aux opérations en fonction de la validate-jwt valeur des revendications de jeton.

<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>

Stratégies connexes

• Authentification et autorisation

Contenu connexe

Pour plus d’informations sur l’utilisation des stratégies, consultez :

• Tutoriel : Transformer et protéger votre API
• Référence de politique pour obtenir la liste complète des déclarations et des paramètres de politique
• Expressions de stratégie
• Définir ou modifier des stratégies
• Réutiliser les configurations de stratégie
• Po de extraits de codePolicy
• po de terrain de jeuPolicy
• Azure API Management kit de ressources de stratégie
• Get Copilot assistance pour créer, expliquer et dépanner des stratégies