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.

Notes

Pour valider un JWT fourni par un autre fournisseur d’identité, Gestion des API fournit également la stratégie générique validate-jwt.

Notes

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, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

Attributs

Attribut Description Obligatoire Default
tenant-id ID de locataire ou URL du service Microsoft Entra. 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. Oui
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

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

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. Le nom d'hôte est fourni à l'aide d'une expression de stratégie, et l'ID de locataire Microsoft Entra et l'ID d'application client sont fournis à l'aide de valeurs nommées. 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="{{aad-tenant-id}}" 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 :