Valider le jeton Microsoft Entra
S’APPLIQUE À : Tous les niveaux de Gestion des API
La stratégie validate-azure-ad-token
applique l’existence et la validité d’un jeton web JSON (JWT) fourni par le service Microsoft Entra (anciennement appelé Azure Active Directory) pour un ensemble spécifié de principaux dans le répertoire. Le JWT peut être extrait d’un en-tête HTTP, d’un paramètre de requête ou d’une valeur spécifié à l’aide d’une expression de stratégie ou d’une variable de contexte.
Remarque
Pour valider un JWT fourni par un fournisseur d’identité autre que Microsoft Entra, Gestion des API fournit également la stratégie générique validate-jwt
.
Remarque
Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.
Instruction de la stratégie
<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>Base64 encoded signing key | certificate-id="mycertificate"</key>
<!-- if there are multiple keys, then add additional key elements -->
</decryption-keys>
</validate-azure-ad-token>
Attributs
Attribut | Description | Obligatoire | Default |
---|---|---|---|
tenant-id | ID de locataire ou URL du locataire Microsoft Entra ID, ou l’un des locataires connus suivants : - organizations ou https://login.microsoftonline.com/organizations - pour autoriser les jetons à partir de comptes dans un annuaire organisationnel (tout annuaire Microsoft Entra)- common ou https://login.microsoftonline.com/common - pour autoriser les jetons à partir de comptes dans un annuaire organisationnel (tout annuaire Microsoft Entra) et comptes Microsoft personnels (par exemple Skype, XBox)Les expressions de stratégie sont autorisées. |
Oui | N/A |
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é. |
Authorization |
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 ». |
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 |
---|---|---|
audiences | Contient la liste des revendications d’audience acceptables qui peuvent être présentes sur le jeton. Si plusieurs valeurs 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. Les expressions de stratégie sont autorisées. |
Non |
backend-application-ids | Contient une liste d’ID d’application back-end acceptables. Cela n’est nécessaire que dans les cas avancés pour la configuration des options et peut généralement être supprimé. Les expressions de stratégie ne sont pas autorisées. | Non |
client-application-ids | Contient une liste d’ID d’application back-end acceptables. Si plusieurs éléments application-id sont présents, chacun est tenté jusqu’à ce que tous soient épuisés (auquel cas la validation échoue) ou que l’un d’eux réussisse. Si aucun ID d’application cliente n’est fourni, une ou plusieurs revendications audience doivent être spécifiées. Les expressions de stratégie ne sont pas autorisées. |
Non |
required-claims | Contient une liste d’éléments claim pour les valeurs de revendication censées être présentes sur le jeton pour qu’il soit considéré comme valide. Si l’attribut match a la valeur all , toutes les valeurs de revendication de la stratégie doivent être présentes dans le jeton pour que la validation réussisse. Si l’attribut match a la valeur any , au moins une revendication doit être présente dans le jeton pour que la validation réussisse. Les expressions de stratégie sont autorisées. |
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.Pour déchiffrer un jeton chiffré avec une clé asymétrique, spécifiez éventuellement la clé publique à l’aide d’un attribut certificate-id dont la valeur est définie sur l’identificateur d’un certificat chargé sur Gestion des API. |
Non |
attributs de revendication
Attribut | Description | Obligatoire | Default |
---|---|---|---|
name | Nom de la revendication telle qu’elle doit apparaître dans le jeton. Les expressions de stratégie sont autorisées. | Oui | N/A |
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.Les expressions de stratégie sont autorisées. |
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. Les expressions de stratégie sont autorisées. | Non | N/A |
attributs de clé
Attribut | Description | Obligatoire | Par défaut |
---|---|---|---|
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 |
Usage
- 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
- 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-azure-ad-token
au niveau de l'API, ou vous pouvez l'appliquer au niveau des opérations de l'API et l'utiliserclaims
pour un contrôle plus granulaire. - Microsoft Entra ID pour les clients (préversion) n’est pas pris en charge.
Exemples
Validation simple du jeton
La stratégie suivante est la forme minimale de la stratégie validate-azure-ad-token
. Le JWT doit être fourni dans l’en-tête Authorization
par défaut à l’aide du schéma Bearer
. Dans cet exemple, l'ID de locataire Microsoft Entra et l'ID d'application client sont fournis à l'aide de valeurs nommées.
<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>
Vérifiez que l’audience et la revendication sont correctes.
La stratégie suivante permet de vérifier que l’audience est le nom d’hôte de l’instance Gestion des API et que la revendication ctry
est US
. L’ID de locataire Microsoft est le locataire organizations
connu, qui autorise les jetons de comptes dans n’importe quel annuaire organisationnel. Le nom d’hôte est fourni à l’aide d’une expression de stratégie et l’ID d’application cliente est fourni à l’aide d’une valeur nommée. Le JWT décodé est fourni dans la variable jwt
après validation.
Pour plus d’informations sur les revendications facultatives, consultez la ressource intitulée Fournir des revendications facultatives à votre application.
<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>
Stratégies connexes
Contenu connexe
Pour plus d’informations sur l’utilisation des stratégies, consultez :
- Tutoriel : Transformer et protéger votre API
- Référence de stratégie pour obtenir la liste complète des instructions et des paramètres de stratégie
- Expressions de stratégie
- Définir ou modifier des stratégies
- Réutilisation de configurations de stratégie
- Référentiel d’extrait de stratégie
- Créer des stratégies à l’aide de Microsoft Copilot dans Azure