Validation de jeton JWT

  • Article

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

La stratégie validate-jwt applique l’existence et la validité d’un jeton JWT (JSON Web Token) pris en charge 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.

Remarque

Pour valider un JWT fourni par le service Microsoft Entra, Gestion des API fournit également la stratégie validate-azure-ad-token.

Remarque

Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. Pour vous aider à configurer cette stratégie, le portail fournit un éditeur guidé basé sur des formulaires. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.

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

Attributs

Attribut Description Obligatoire Default
header-name Nom de l’en-tête HTTP contenant le jeton. Les expressions de stratégie sont autorisées. header-name, query-parameter-name ou token-value doit être spécifié. N/A
query-parameter-name Nom du paramètre de la requête contenant le jeton. Les expressions de stratégie sont autorisées. header-name, query-parameter-name ou token-value doit être spécifié. N/A
token-value Expression retournant une chaîne contenant le jeton. Vous ne devez pas renvoyer Bearer comme partie de la valeur du jeton. Les expressions de stratégie sont autorisées. header-name, query-parameter-name ou token-value doit être spécifié. N/A
failed-validation-httpcode Code d’état HTTP à renvoyer si le JWT n’est pas validé. Les expressions de stratégie sont autorisées. Non 401
failed-validation-error-message Message d’erreur à renvoyer dans le corps de la réponse HTTP si le JWT n’est pas validé. Les éventuels caractères spéciaux de ce message doivent être correctement placés dans une séquence d’échappement. Les expressions de stratégie sont autorisées. Non Le message d’erreur par défaut dépend du problème de validation, par exemple « JWT absent ».
require-expiration-time Propriété booléenne. Spécifie si une revendication d’expiration est requise dans le jeton. Les expressions de stratégie sont autorisées. Non true
require-scheme Le nom du schéma de jeton, par ex. « Support ». Lorsque cet attribut est défini, la stratégie garantit que le schéma spécifié est présent dans la valeur d’en-tête d’autorisation. Les expressions de stratégie sont autorisées. Non N/A
require-signed-tokens Propriété booléenne. Spécifie si un jeton doit être signé. Les expressions de stratégie sont autorisées. Non true
clock-skew Intervalle de temps. Permet de spécifier l’écart maximal de durée estimée entre les horloges système de l’émetteur du jeton et l’instance de gestion des API. Les expressions de stratégie sont autorisées. Non 0 seconde
output-token-variable-name Chaîne. Nom de la variable de contexte qui recevra la valeur du jeton en tant qu’objet de type Jwt à la validation du jeton. Les expressions de stratégie ne sont pas autorisées. Non N/A

Éléments

Élément Description Obligatoire
openid-config Ajoutez un ou plusieurs de ces éléments pour spécifier une URL de point de terminaison de configuration OpenID conforme à partir de laquelle les clés de signature et l’émetteur peuvent être obtenus.

La configuration incluant le jeu de clés web JSON (JWKS) est extraite du point de terminaison toutes les heures et mise en cache. Si le jeton validé fait référence à une clé de validation (à l’aide de la revendication kid) manquante dans la configuration mise en cache ou en cas d’échec de la récupération, la Gestion des API extrait le point de terminaison au plus une fois toutes les 5 minutes. Ces intervalles sont susceptibles d’être modifiés sans préavis.

La réponse devrait correspondre aux spécifications définies dans l’URL :https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Pour Microsoft Entra ID, utilisez le point de terminaison de métadonnées OpenID Connect configuré dans votre inscription d’application, par exemple :
– v2 https://login.microsoftonline.com/{tenant-name}/v2.0/.well-known/openid-configuration
– v2 multi-locataire https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
– v1 https://login.microsoftonline.com/{tenant-name}/.well-known/openid-configuration
– Locataire client (préversion) https://{tenant-name}.ciamlogin.com/{tenant-id}/v2.0/.well-known/openid-configuration

En remplaçant le nom ou l’ID de votre locataire de répertoire, par exemple contoso.onmicrosoft.com, pour {tenant-name}.		 Non
issuer-signing-keys Liste de clés de sécurité encodées en base 64, en sous-éléments key, utilisée pour valider les jetons signés. Si plusieurs clés de sécurité sont présentes, chacune est tentée jusqu’à ce qu’il n’en reste plus (ce qui entraîne un échec de validation) ou jusqu’à ce que l’une d’elles soit la clé appropriée (utile pour la substitution de jeton).

Spécifiez éventuellement une clé à l’aide de l’attribut id pour correspondre à une revendication kid. Pour valider un jeton signé avec une clé asymétrique, spécifiez éventuellement la clé publique à l’aide d’un attribut certificate-id avec la valeur de l’identificateur d’un certificat chargé sur Gestion des API, ou d’une paire RSA de modulo n et d’exposant e de la clé de signature au format encodé en Base64url.		 Non
decryption-keys Liste de clés encodées en base 64, en sous-éléments key, utilisée pour déchiffrer les jetons. Si plusieurs clés de sécurité sont présentes, chacune est tentée jusqu’à ce qu’il n’en reste plus (ce qui entraîne un échec de validation) ou jusqu’à ce que l’une d’elles soit la clé appropriée.

Spécifiez éventuellement une clé à l’aide de l’attribut id pour correspondre à une revendication kid. Pour déchiffrer un jeton chiffré avec une clé asymétrique, spécifiez éventuellement la clé publique à l’aide d’un attribut certificate-id avec la valeur de l’identificateur d’un certificat chargé sur Gestion des API, ou d’une paire RSA de modulo n et d’exposant e de la clé au format encodé en Base64url.		 Non
audiences Une liste des revendications d’audience acceptables, en sous-éléments audience, qui peuvent être présentes sur le jeton. Si plusieurs valeurs d’audience sont présentes, chacune est tentée jusqu’à ce que toutes soient épuisées (auquel cas la validation échoue) ou que l’une d’elles réussisse. Au moins une audience doit être spécifiée. Non
issuers Liste des services principaux acceptables, en sous-éléments issuer, qui ont émis le jeton. Si plusieurs valeurs d’émetteur sont présentes, chacune est tentée jusqu’à ce que toutes soient épuisées (auquel cas la validation échoue) ou que l’une d’elles réussisse. Non
required-claims Une liste de revendications, en sous-éléments claim, censées être présentes sur le jeton pour qu’il soit considéré comme valide. Lorsque plusieurs revendications sont présentes, le jeton doit correspondre aux valeurs de revendication en fonction de la valeur de l’attribut match. Non

attributs de clé

Attribut Description Obligatoire Default
id Chaîne. Identificateur utilisé pour faire correspondre la revendication kid présentée dans JWT. Non N/A
certificate-id Identificateur d’une entité de certificat chargée sur Gestion des API, utilisé pour spécifier la clé publique permettant de vérifier un jeton signé avec une clé asymétrique. Non N/A
n Module de la clé publique utilisée pour vérifier l’émetteur d’un jeton signé avec une clé asymétrique. Doit être spécifié avec la valeur de l’exposant e. Les expressions de stratégie ne sont pas autorisées. Non N/A
e Exposant de la clé publique utilisée pour vérifier l’émetteur d’un jeton signé avec une clé asymétrique. Doit être spécifié avec la valeur du modulo n. Les expressions de stratégie ne sont pas autorisées. Non N/A

attributs de revendication

Attribut Description Obligatoire Default
match L’attribut match sur l’élément claim spécifie si toutes les valeurs de revendication de la stratégie doivent être présentes dans le jeton pour que la validation réussisse. Les valeurs possibles sont les suivantes :

- all : toutes les valeurs de revendication de la stratégie doivent être présentes dans le jeton pour que la validation réussisse.

- any : au moins une valeur de revendication doit être présente dans le jeton pour que la validation réussisse.		 Non all
separator Chaîne. Spécifie un séparateur (par exemple, « , ») à utiliser pour extraire un ensemble de valeurs à partir d’une revendication à valeurs multiples. Non N/A

Usage

Notes d’utilisation

  • La stratégie validate-jwt exige que la revendication inscrite exp soit incluse dans le jeton JWT, sauf si l’attribut require-expiration-time est spécifié et a la valeur 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.
      • 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.
  • Pour configurer la stratégie avec un ou plusieurs points de terminaison de configuration OpenID à utiliser avec une passerelle auto-hébergée, les URL des points de terminaison de configuration OpenID doivent également être accessibles par la passerelle cloud.
  • 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 l'intégralité de 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 des opérations de l'API et l'utiliser claims pour un contrôle plus granulaire.
  • 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 jetons 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 du jeton monolocataire 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>25eef6e4-c905-4a07-8eb4-0d08d5df8b3f</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

Validation du jeton 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 d’un 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>d313c4e4-de5f-4197-9470-e509a2f0b806</audience>
    </audiences>
    <required-claims>
        <claim name="id" match="all">
            <value>insert claim here</value>
        </claim>
    </required-claims>
</validate-jwt>

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

Cet exemple montre comment utiliser la stratégie validate-jwt pour autoriser l’accès aux opérations à partir de revendications de jetons.

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

Contenu connexe

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