Partage via

Valider le jeton Microsoft Entra

  • Article

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 certificate-id="mycertificate"/>
        <!-- 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 sous-éléments key utilisée pour déchiffrer un jeton signé avec une clé asymétrique. Si plusieurs clés sont présentes, chaque clé est essayée jusqu’à ce qu’il n’en reste plus (auquel cas la validation échoue) ou jusqu’à ce qu’une clé réussisse.

Spécifiez la clé publique à l’aide d’un attribut certificate-id dont la valeur est définie sur l’identificateur d’un certificat chargé dans 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. Oui N/A

Usage

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'utiliser claims 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>

Contenu connexe

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