Partager via

Comment autoriser la console de test du portail des développeurs en configurant l’autorisation utilisateur OAuth 2.0

  • Article

S’applique à : Développeur | Essentiel | Essentiel v2 | Standard | Standard v2 | Premium | Premium v2

De nombreuses API prennent en charge OAuth 2.0 pour sécuriser les API et assurer que seuls les utilisateurs valides y ont accès et peuvent accéder uniquement aux ressources pour lesquelles ils y sont autorisés. Pour utiliser la console de développement interactive Gestion des API Azure avec ces API, le service vous permet de configurer un fournisseur externe pour l’autorisation utilisateur OAuth 2.0.

La configuration de l'autorisation de l'utilisateur OAuth 2.0 dans la console de test du portail de développement offre aux développeurs un moyen pratique d'acquérir un jeton d'accès OAuth 2.0. Depuis la console de test, le jeton est alors passé au back-end avec l’appel d’API. La validation du jeton doit être configurée séparément, soit à l’aide d’une stratégie de validation JWT, soit dans le service principal.

Prérequis

Cet article explique comment configurer votre instance de service Gestion des API pour utiliser l’autorisation OAuth 2.0 dans la console de test du portail des développeurs, mais ne vous montre pas comment configurer un fournisseur OAuth 2.0.

Si vous n’avez pas encore créé d’instance de service Gestion des API, consultez Créer une instance de service Gestion des API.

Présentation du scénario

La configuration de l’autorisation utilisateur OAuth 2.0 dans Gestion des API permet seulement à la console de test du portail des développeurs (et la console de test dans le Portail Azure) en tant que client d’acquérir un jeton auprès du serveur d’autorisation. La configuration pour chaque fournisseur OAuth 2.0 est différente, bien que les étapes soient similaires et que les informations requises pour configurer OAuth 2.0 dans votre instance de service API Management soient les mêmes. Cet article présente un exemple d’utilisation de Microsoft Entra ID comme fournisseur OAuth 2.0.

Les étapes de configuration de haut niveau sont les suivantes :

  1. Inscrivez une application (application back-end) dans Microsoft Entra ID pour représenter l’API.

  2. Inscrivez une autre application (application cliente) dans Microsoft Entra ID pour représenter une application cliente qui doit appeler l’API, dans le cas présent, la console de test du portail des développeurs.

    Dans Microsoft Entra ID, accordez des autorisations pour permettre à l’application cliente d’appeler l’application back-end.

  3. Configurez la console de test dans le portail des développeurs pour appeler une API en utilisant l’autorisation utilisateur OAuth 2.0.

  4. Configurer une API pour utiliser l’autorisation utilisateur OAuth 2.0

  5. Ajoutez une stratégie afin de pré-autoriser le jeton OAuth 2.0 pour chaque demande entrante. Vous pouvez utiliser la stratégie validate-jwt pour n’importe quel fournisseur OAuth 2.0.

Cette configuration prend en charge le flux OAuth suivant :

Graphique de vue d’ensemble pour conceptualiser visuellement le flux suivant.

  1. Le portail des développeurs demande un jeton à Microsoft Entra ID à l’aide des informations d’identification de l’application cliente.

  2. Une fois la validation réussie, Microsoft Entra ID émet le jeton d’accès/d’actualisation.

  3. Un développeur (utilisateur du portail des développeurs) effectue un appel d’API avec l’en-tête d’autorisation.

  4. Le jeton est validé à l’aide de la stratégie validate-jwt dans Gestion des API par Microsoft Entra ID.

  5. En fonction du résultat de la validation, le développeur reçoit la réponse dans le portail des développeurs.

Types d'octroi d'autorisation

La gestion des API Azure prend en charge les types d’octroi 2.0 OAuth suivants (flux). Un type d’octroi fait référence à une méthode pour une application cliente (dans ce contexte, la console de test dans le portail des développeurs) pour obtenir un jeton d’accès à votre API backend. Vous pouvez configurer un ou plusieurs types d’octroi, en fonction de votre fournisseur et de vos scénarios OAuth 2.0.

Voici un résumé de haut niveau. Pour plus d'informations sur les types de subventions, voir le cadre d'autorisation OAuth 2.0 et les types de subventions OAuth.

Type d’autorisation Description Scénarios
Code d’autorisation. Échange le code d’autorisation pour le jeton Applications côté serveur telles que Web Apps
Code d’autorisation + PKCE Amélioration du flux du code d’autorisation qui crée un défi de code envoyé avec une demande d’autorisation Clients mobiles et publics incapables de protéger un secret ou un jeton
Implicite (déconseillé) Retourne le jeton d’accès immédiatement sans une étape d’échange de code d’autorisation supplémentaire Clients qui ne peuvent pas protéger un secret ou un jeton comme les applications mobiles et les applications à page unique

Généralement non recommandé en raison des risques inhérents au fait de retourner un jeton d’accès dans la redirection HTTP sans confirmation de sa réception par le client
Mot de passe de propriétaire de la ressource. Demande les informations d’identification de l’utilisateur (nom d’utilisateur et mot de passe), généralement à l’aide d’un formulaire interactif Pour une utilisation avec des applications hautement fiables

Utilisez ce flux uniquement lorsqu’aucun autre flux plus sécurisé ne peut être utilisé.
Informations d'identification du client Authentifie et autorise une application plutôt qu’un utilisateur Applications machine à machine qui ne nécessitent pas d’autorisations spécifiques pour accéder aux données, comme les interfaces CLI, les démons ou les services qui s’exécutent sur votre back-end

Considérations relatives à la sécurité

Réfléchissez à la façon dont le type d’octroi génère un jeton, à la portéedu jeton et à la façon dont le jeton peut être exposé. Un jeton compromis peut être utilisé par un acteur malveillant pour accéder à des ressources supplémentaires dans l’étendue du jeton.

Lors de la configuration de l’autorisation utilisateur OAuth 2.0 dans la console de test du portail des développeurs :

  • Limitez la portée du jeton au minimum nécessaire pour que les développeurs testent les API. Limitez l’étendue à la console de test ou aux API affectées. La procédure de configuration de l’étendue des jetons dépend de votre fournisseur OAuth 2.0.

    Selon vos scénarios, vous pouvez configurer des étendues de jeton plus ou moins restrictives pour d’autres applications clientes que vous créez pour accéder aux API principales.

  • Soyez extrêmement vigilant si vous activez le workflow des informations d’identification du client. La console de test dans le portail des développeurs, lors de l’utilisation du workflow des informations d’identification du client, ne demande pas d’informations d’identification. Un jeton d’accès peut être exposé par inadvertance à des développeurs ou à des utilisateurs anonymes de la console de développeur.

Suivi des informations clés

Tout au long de ce tutoriel, vous êtes invité à enregistrer les informations clés à référencer ultérieurement :

  • ID d’application principale (client): GUID de l’application qui représente l’API back-end
  • Étendues d’application back-end: une ou plusieurs étendues que vous pouvez créer pour accéder à l’API. Le format d’étendue est api://<Backend Application (client) ID>/<Scope Name> (par exemple, api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
  • ID d’application principale (client): GUID de l’application qui représente le portail du développeur
  • Valeur du secret de l’application cliente : GUID qui sert de secret pour l’interaction avec l’application cliente dans Microsoft Entra ID

Inscrire des applications auprès du serveur OAuth

Vous devez inscrire deux applications auprès de votre fournisseur OAuth 2.0 : une représente l’API du back-end à protéger, et une deuxième représente l’application cliente qui appelle l’API, dans le cas présent, la console de test du portail des développeurs.

Voici des exemples d’étapes utilisant Microsoft Entra ID comme fournisseur OAuth 2.0. Pour plus d'informations sur l'inscription d'une application, consultez Démarrage rapide : Configurer une application pour exposer une API web.

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

  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. Plus tard, vous allez ajouter un URI de redirection généré dans la configuration OAuth 2.0 dans Gestion des API.

  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. Enregistrez cette valeur pour une utilisation ultérieure.

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

    1. Entrez un Nom d’étendue pour une étendue prise en charge par l’API (par exemple Files.Read).
    2. Dans Qui peut donner son consentement ?, effectuez une sélection pour votre scénario, par exemple Administrateurs et utilisateurs. Sélectionnez administrateurs uniquement pour des scénarios à privilèges élevés.
    3. Entrez un Nom d’affichage du consentement administrateur et une Description du consentement administrateur.
    4. 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. Lorsque les étendues sont créées, prenez-en note afin de les utiliser à une étape ultérieure.

Inscrire une autre application dans Microsoft Entra ID pour représenter une application cliente

Inscrivez chaque application cliente qui appelle l’API en tant qu’application dans Microsoft Entra ID.

  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 client-app.
    • Dans la section Types de comptes pris en charge, sélectionnez une option adaptée à votre scénario.

  4. Dans la section URI de redirection, sélectionnez Web et laissez le champ URL vide pour le moment.

  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. Créez un secret client pour cette application afin de l’utiliser à une étape ultérieure.

    1. Sous la section Gérer du menu latéral, sélectionnez Certificats et secrets.
    2. Sous Secrets client , sélectionnez + Nouveau secret client.
    3. Sous Ajouter une clé secrète client, fournissez une Description et choisissez le moment où la clé doit expirer.
    4. Sélectionnez Ajouter.

Lorsque le secret est créé, notez la valeur de clé afin de l’utiliser à une étape ultérieure. Vous ne pouvez plus accéder à nouveau au secret dans le portail.

Octroyer des autorisations dans Microsoft Entra ID

Maintenant que vous avez inscrit deux applications pour représenter l’API et la console de test, accordez des autorisations pour permettre à l’application cliente d’appeler l’application du back-end.

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

  2. Choisissez votre application cliente. Ensuite, dans le menu latéral, sélectionnez Autorisations de l’API.

  3. Sélectionnez Ajouter une autorisation.

  4. Sous Sélectionnez une API, sélectionnez Mes API, puis recherchez et sélectionnez votre backend-app.

  5. Sélectionnez Autorisations déléguées, puis les autorisations appropriées à votre backend-app.

  6. Sélectionnez Ajouter des autorisations.

Éventuellement :

  1. Accédez à la page Autorisations de l’API de votre application cliente.

  2. Sélectionnez Accorder un consentement administrateur pour <nom-du-locataire> afin de donner le consentement au nom de tous les utilisateurs de ce répertoire.

Configurer un serveur d’autorisation OAuth 2.0 dans Gestion des API

  1. Dans le portail Azure, accédez à votre instance APIM.

  2. Sous Portail des développeurs dans le menu latéral, sélectionnez OAuth 2.0 + OpenID Connect.

  3. Sous l’onglet OAuth 2.0, sélectionnez + Ajouter.

    Menu OAuth 2.0

  4. Entrez un nom et une description facultative dans les champs Nom et Description.

    Notes

    Ces champs sont utilisés pour identifier le serveur d’autorisation OAuth 2.0 dans l’instance de service Gestion des API. Leurs valeurs ne proviennent pas du serveur OAuth 2.0.

  5. Entrez l' URL de la page d'enregistrement client - par exemple, https://contoso.com/login. Cette page permet aux utilisateurs de créer et de gérer leurs comptes, si votre fournisseur OAuth 2.0 prend en charge la gestion des comptes utilisateur. La page varie selon le fournisseur OAuth 2,0 utilisé.

    Si la gestion des utilisateurs de comptes de votre fournisseur OAuth 2.0 n’a pas été configurée, entrez ici un espace réservé d’URL, par exemple l’URL de votre entreprise ou une URL comme http://localhost.

    Nouveau serveur OAuth 2.0

  6. La section suivante du formulaire inclut les paramètres Types d’accès accordé aux autorisations, URL de point de terminaison d’autorisation et Méthode de demande d’autorisation.

    • Sélectionnez un ou plusieurs Types d’octroi d’autorisation souhaités. Pour cet exemple, sélectionnez Code d’autorisation (la valeur par défaut). En savoir plus

    • Entrez l' URL de point de terminaison d'autorisation. Vous pouvez obtenir l’URL du point de terminaison dans la page Points de terminaison de l’une de vos inscriptions d’application. Pour une application à locataire unique dans Microsoft Entra ID, cette URL sera similaire à l’une des URL suivantes, où {aad-tenant} est remplacé par l’ID de votre locataire Microsoft Entra.

      L’utilisation du point de terminaison v2 est recommandée ; cependant, Gestion des API prend en charge les points de terminaison v1 et v2.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

    • La Méthode de demande d’autorisation spécifie comment la demande d'autorisation est envoyée au serveur OAuth 2.0. Sélectionnez POST.

    Spécifier les paramètres d'autorisation

  7. Spécifier les paramètres URL de point de terminaison de jeton, Méthodes d’authentification du client, Méthode d’envoi des jetons d’accès et Étendue par défaut.

    • Entrez l’URL du point de terminaison de jeton. Pour une application à locataire unique dans Microsoft Entra ID, cette URL sera similaire à l’une des URL suivantes, où {aad-tenant} est remplacé par l’ID de votre locataire Microsoft Entra. Utilisez la même version de point de terminaison (v2 ou v1) que celle que vous avez choisie précédemment.

      https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

      https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

    • Si vous utilisez les points de terminaison v1, ajoutez un paramètre de corps.
      * Nom : ressource.
      * Valeur : ID d’application (cliente) de l’application back-end

    • Si vous utilisez les points de terminaison v2 :
      * Saisissez l’étendue d’application back-end que vous avez créée dans le champ Étendue par défaut.
      * Définissez la valeur de la propriété accessTokenAcceptedVersion sur 2 dans le manifeste de l’application pour les inscriptions de l’application back-end et de l’application cliente.

    • Acceptez les paramètres par défaut pour Méthodes d’authentification client et pour Méthode d’envoi des jetons d’accès.

  8. Dans Informations d’identification client, entrez l’ID client et la Clé secrète client, qui sont obtenus lors du processus de création et de configuration de votre application cliente.

  9. Une fois ID client et Clé secrète client spécifiés, l’URI de redirection pour le code d’autorisation est généré. Cet URI est utilisé pour configurer l’URI de redirection dans la configuration de votre serveur OAuth 2.0.

    Dans le nouveau portail des développeurs, le suffixe URI se présente sous la forme suivante :

    • /signin-oauth/code/callback/{authServerName} pour le flux d’octroi du code d’autorisation
    • /signin-oauth/implicit/callback pour le flux d’octroi implicite

    Ajouter les informations d'identification du client pour le service OAuth 2.0

    Copiez l’URI de redirection approprié dans la page Authentification de l’inscription de votre application cliente. Dans l’inscription de l’application, sélectionnez Authentification>+ Ajouter une plateforme>Web, puis entrez l’URI de redirection.

  10. Si le paramètre Types d’accès accordés aux autorisations est défini sur Mot de passe du propriétaire des ressources, la section Informations d’identification du mot de passe du propriétaire des ressources permet de spécifier ces informations d’identification ; sinon, vous pouvez la laisser vide.

  11. Cliquez sur Créer pour enregistrer la configuration du serveur d’autorisation OAuth 2.0 de Gestion des API.

  12. Republiez le portail des développeurs.

    Important

    Lorsque vous apportez des modifications liées à OAuth 2.0, veillez à republier le portail des développeurs après chaque modification en tant que modifications pertinentes (par exemple, modification d’étendue) sinon la propagation ne peut pas se réaliser dans le portail et être utilisée ultérieurement pour essayer les API.

Configurer une API pour utiliser l’autorisation utilisateur OAuth 2.0

Après avoir sauvegardé la configuration du serveur OAuth 2.0, configurez la ou les API pour utiliser cette configuration.

Important

  • La configuration des paramètres d’autorisation utilisateur OAuth 2.0 pour une API permet à Gestion des API d’acquérir un jeton auprès du serveur d’autorisation lorsque vous utilisez la console de test dans le Portail Azure ou le portail des développeurs. Les paramètres du serveur d’autorisation sont également ajoutés à la définition et à la documentation de l’API.
  • Pour l’autorisation OAuth 2.0 au moment de l’exécution, l’application cliente doit acquérir et présenter le jeton et vous devez configurer la validation du jeton dans Gestion des API ou l’API back-end. Pour en voir un exemple, consultez Protéger une API dans Gestion des API Azure en utilisant l’autorisation OAuth 2.0 avec Microsoft Entra ID.

  1. Cliquez sur API dans le menu Gestion des API à gauche.

  2. Sélectionnez le nom de l’API souhaitée, puis sélectionnez l’onglet Paramètres. Faites défiler jusqu’à la section Sécurité, puis sélectionnez OAuth 2,0.

  3. Sélectionnez le Serveur d’autorisation souhaité dans la liste déroulante, puis cliquez sur Enregistrer.

    Configurer le serveur d'autorisation OAuth 2.0

Portail de développement - test de l’autorisation utilisateur OAuth 2.0

Une fois que vous avez configuré votre serveur d'autorisation OAuth 2.0 et votre API pour utiliser ce serveur, vous pouvez le tester en accédant au portail de développement et en appelant une API.

  1. Cliquez sur Portail des développeurs dans le menu supérieur de la page Vue d’ensemble de votre instance Gestion des API Azure.

  2. Accédez à l’opération de votre choix sous l’API dans le portail des développeurs.

  3. Sélectionnez Essayer pour vous connecter à la console des développeurs.

  4. Observez le nouvel élément dans la section Autorisation correspondant au serveur d’autorisation que vous venez d’ajouter.

  5. Sélectionnez Code d’autorisation dans la liste déroulante Autorisation.

    Sélectionner Autorisation code d’autorisation

  6. Une fois que vous y êtes invité, connectez-vous au locataire Microsoft Entra.

    • Si vous êtes déjà connecté avec ce compte, il est possible qu’aucune invite ne s’affiche.

  7. Une fois la connexion réussie, un en-tête Authorization est ajouté à la requête, avec un jeton d'accès de Microsoft Entra ID. Voici un exemple de jeton abrégé (encodé en base64) :

    Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA

  8. Configurez les valeurs souhaitées pour les paramètres restants, puis sélectionnez Envoyer pour appeler l’API.

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

Dans la configuration à ce stade, Gestion des API ne valide pas le jeton d’accès. Il passe seulement le jeton dans l’en-tête d’autorisation à l’API du back-end.

Pour pré-autoriser les demandes, configurez une stratégie validate-jwt pour valider le jeton d’accès de chaque demande entrante. Si une demande n’a pas de jeton valide, Gestion des API la bloque.

L'exemple de stratégie suivant, lorsqu'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 à partir de Microsoft Entra ID présenté dans l'en-tête Autorisation. 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.

Contenu connexe