Protéger une API dans Gestion des API Azure en utilisant l’autorisation OAuth 2.0 avec Microsoft Entra ID

  • Article

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

Dans cet article, vous allez découvrir les grandes étapes de configuration de votre instance Gestion des API Azure pour protéger une API en utilisant le protocole OAuth 2.0 avec Microsoft Entra ID.

Pour obtenir une vue d’ensemble conceptuelle de l’autorisation des API, consultez Authentification et autorisation aux API dans le service Gestion des API.

Prérequis

Avant de suivre les étapes décrites dans cet article, vous devez avoir :

  • Une instance Gestion des API
  • Une API publiée avec l’instance Gestion des API
  • Un locataire Microsoft Entra

Vue d’ensemble

Suivez ces étapes pour protéger une API dans Gestion des API en utilisant l’autorisation OAuth 2.0 avec Microsoft Entra ID.

  1. Inscrivez une application (appelée backend-app dans cet article) dans Microsoft Entra ID pour protéger l’accès à l’API.

    Pour accéder à l’API, les utilisateurs ou les applications vont acquérir et présenter un jeton OAuth valide accordant l’accès à cette application avec chaque demande d’API.

  2. Configurez la stratégie validate-jwt dans Gestion des API pour valider le jeton OAuth présenté dans chaque demande d’API entrante. Les requêtes valides peuvent être passées à l’API.

Les détails sur les flux d’autorisation OAuth et la façon de générer les jetons OAuth nécessaires sont en dehors du cadre de cet article. En règle générale, une application cliente distincte est utilisée pour acquérir auprès de Microsoft Entra ID les jetons qui autorisent l’accès à l’API. Pour des liens vers plus d’informations, consultez les Étapes suivantes.

Inscrire une application dans Microsoft Entra ID pour représenter l’API

En utilisant le portail Azure, protégez une API avec Microsoft Entra ID en inscrivant d’abord une application qui représente l’API.

Pour plus d'informations sur l'inscription d'une application, consultez Démarrage rapide : Configurer une application pour exposer une API web.

  1. Dans le portail Azure, recherchez et sélectionnez Inscriptions d’applications.

  2. Sélectionnez Nouvelle inscription.

  3. Lorsque la page Inscrire une application s’affiche, saisissez les informations d’inscription de votre application :

    • Dans la section Nom, saisissez un nom d’application cohérent qui s’affichera pour les utilisateurs de l’application, par exemple backend-app.
    • Dans la section Types de comptes pris en charge, sélectionnez une option adaptée à votre scénario.

  4. Laissez la section URI de redirection vide pour l’instant.

  5. Sélectionnez Inscrire pour créer l’application.

  6. Dans la page Vue d’ensemble de l’application, recherchez la valeur ID d’application (client) et notez-la.

  7. Sous la section Gérer du menu latéral, sélectionnez Exposer une API et définissez l’URI de l’ID d’application avec la valeur par défaut. Si vous développez une application cliente distincte pour obtenir des jetons OAuth 2.0 pour l’accès à l’application back-end, enregistrez notez cette valeur pour l’utiliser plus tard.

  8. Sélectionnez le bouton Ajouter une étendue pour afficher la page Ajouter une étendue :

    1. Entrez un nouveau Nom d’étendue, le Nom d’affichage du consentement administrateur et la Description du consentement administrateur.
    2. Assurez-vous que l’état d’étendue Activée est sélectionné.

  9. Sélectionnez le bouton Ajouter une étendue pour créer l’étendue.

  10. Répétez les deux étapes précédentes pour ajouter toutes les étendues prises en charge par votre API.

  11. Une fois les étendues créées, prenez-en note pour les utiliser plus tard.

Configuration d’une stratégie de validation JWT pour autoriser des demandes

L’exemple de stratégie suivant, quand il est ajouté à la section de stratégie <inbound>, vérifie la valeur de la revendication d’audience dans un jeton d’accès obtenu auprès de Microsoft Entra ID qui est présenté dans l’en-tête Authorization. Elle retourne une erreur si le jeton n’est pas valide. Configurez cette stratégie avec une étendue de stratégie appropriée pour votre scénario.

  • Dans l’URL openid-config, aad-tenant est l’ID de locataire dans Microsoft Entra ID. Recherchez cette valeur dans le portail Azure, par exemple dans la page Vue d’ensemble de votre ressource Microsoft Entra. L’exemple présenté suppose une application Microsoft Entra à locataire unique et un point de terminaison de configuration v2.
  • La valeur de claim est l’ID client de l’application back-end que vous avez inscrite dans 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/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Remarque

L’URL openid-config précédente correspond au point de terminaison v2. Pour le point de terminaison openid-config v1, utilisez https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Pour plus d’informations sur la façon de configurer des stratégies, consultez Définir ou modifier des stratégies. Reportez-vous à la référence validate-jwt pour plus de personnalisation sur les validations JWT. Pour valider un JWT fourni par le service Microsoft Entra, Gestion des API fournit également la stratégie validate-azure-ad-token.

Workflow d’autorisation

  1. Un utilisateur ou une application acquiert un jeton auprès de Microsoft Entra ID avec des autorisations qui accordent l’accès à l’application back-end.

  2. Le jeton est ajouté dans l’en-tête d’autorisation des demandes d’API adressées à Gestion des API.

  3. Gestion des API valide le jeton en utilisant la stratégie validate-jwt.

    • Si une demande n’a pas de jeton valide, Gestion des API la bloque.

    • Si une demande est accompagnée d’un jeton valide, la passerelle peut transférer la demande à l’API.

Étapes suivantes