Accéder en toute sécurité aux produits et API avec les applications Microsoft Entra

S’APPLIQUE À : Développeur | De base | Standard | Premium

Gestion des API prend désormais en charge l’accès intégré OAuth 2.0 en fonction d’une application pour générer des API en utilisant le flux d’informations d’identification du client. Cette fonctionnalité permet aux gestionnaires d’API d’inscrire des applications d’ID Microsoft Entra, en rationalisant l’accès à l’API sécurisée pour les développeurs via l’autorisation OAuth 2.0.

Remarque

Les applications sont actuellement en préversion limitée. Pour vous inscrire, remplissez ce formulaire.

Avec cette fonctionnalité :

• Les gestionnaires d’API définissent une propriété de produit pour activer l’accès basé sur l’application.
• Les gestionnaires d’API inscrivent des applications clientes dans Microsoft Entra ID pour limiter l’accès à des produits spécifiques.
• Les développeurs peuvent accéder aux informations d’identification de l’application cliente à l’aide du portail des développeurs Gestion des API.
• À l’aide du flux d’informations d’identification du client OAuth 2.0, les développeurs ou les applications obtiennent des jetons qu’ils peuvent inclure dans les demandes d’API
• Les jetons présentés dans les demandes d’API sont validés par la passerelle Gestion des API pour autoriser l’accès aux API du produit.

Conditions préalables

• Instance Gestion des API déployée dans le niveau Premium, Standard, De base ou Développeur . Si vous devez déployer une instance, consultez Créer une instance de service Gestion des API.

• Au moins un produit dans votre instance Gestion des API, avec au moins une API qui lui est affectée.

  • Le produit doit être dans l’état Publié afin qu’il soit accessible par les développeurs via le portail des développeurs.
  • Pour les tests, vous pouvez utiliser le produit Starter par défaut et l’API Echo qui lui est ajoutée.
  • Si vous souhaitez créer un produit, consultez Créer et publier un produit.

• Des autorisations suffisantes dans votre locataire Microsoft Entra pour attribuer le rôle Administrateur d’application qui nécessite au moins le rôle Administrateur de rôle privilégié.

• Si vous le souhaitez, ajoutez un ou plusieurs utilisateurs dans votre instance Gestion des API.

• Si vous choisissez d’utiliser Azure PowerShell localement :
  • Installez la dernière version du module Az PowerShell.
  • Connectez-vous à votre compte Azure à l’aide de la cmdlet Connect-AzAccount.
• Si vous choisissez d’utiliser Azure Cloud Shell :
  • Pour plus d’informations, consultez Vue d’ensemble d’Azure Cloud Shell.

Configurer une identité managée

1. Activez une identité managée affectée par le système pour Gestion des API dans votre instance Gestion des API.

2. Attribuez à l’identité le rôle RBAC Administrateur d’application dans Microsoft Entra ID. Pour attribuer le rôle :

   1. Connectez-vous au portail et accédez à Microsoft Entra ID.
   2. Dans le menu de gauche, sélectionnez Gérer les>rôles et les administrateurs.
   3. Sélectionnez Administrateur d’application.
   4. Dans le menu de gauche, sélectionnez Gérer>les affectations>+ Ajouter des affectations.
   5. Dans la page Ajouter des affectations , recherchez l’identité managée de l’instance Gestion des API par nom (nom de l’instance Gestion des API). Sélectionnez l’identité managée, puis sélectionnez Ajouter.

Activer l’accès basé sur l’application pour le produit

Suivez ces étapes pour activer l’accès basé sur l’application pour un produit. Un produit doit avoir ce paramètre activé pour être associé à une application cliente dans les étapes ultérieures.

L’exemple suivant utilise le produit Starter , mais choisissez n’importe quel produit publié dont au moins une API lui est affectée.

1. Connectez-vous au portail à l’URL personnalisée suivante pour la fonctionnalité des applications : ;https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications
2. Accédez à votre instance API Management.
3. Dans le menu de gauche, sous API, sélectionnez Produits.
4. Choisissez le produit que vous souhaitez configurer, tel que le produit Starter .
5. Dans le menu de gauche, sous Produit, sélectionnez Propriétés.
6. Dans la section Accès basé sur l’application, activez le paramètre de jeton OAuth 2.0 (le plus sécurisé).
7. Si vous le souhaitez, activez le paramètre de clé d’abonnement . Si vous activez l’accès en fonction de l’application et une exigence d’abonnement, la passerelle Gestion des API peut accepter un jeton OAuth 2.0 ou une clé d’abonnement pour l’accès aux API du produit.
8. Cliquez sur Enregistrer.

Conseil / Astuce

Vous pouvez également activer le paramètre de jeton OAuth 2.0 lors de la création d’un produit.

L’activation de l’accès basé sur l’application crée une application d’entreprise principale dans Microsoft Entra ID pour représenter le produit. L’ID d’application back-end s’affiche dans la page Propriétés du produit.

Remarque

Cet ID d’application est défini comme valeur Audience lors de la création d’une application cliente pour accéder au produit. Utilisez également cette valeur lors de la génération d’un jeton pour appeler l’API de produit.

(Facultatif) Passer en revue les paramètres d’application de produit dans l’ID Microsoft Entra

Si vous le souhaitez, passez en revue les paramètres de l’application d’entreprise principale créée dans l’ID Microsoft Entra pour représenter le produit.

L’application est nommée au format suivant : APIMProductApplication<product-name>. Par exemple, si le nom du produit est Starter, le nom de l’application est APIMProductApplicationStarter. L’application a un rôle d’application défini.

Pour passer en revue les paramètres d'application dans Inscriptions d'applications :

1. Connectez-vous au portail et accédez à Microsoft Entra ID>Manage>App Registrations.
2. Sélectionnez Toutes les applications.
3. Recherchez et sélectionnez l’application créée par Gestion des API.
4. Dans le menu de gauche, sous Gérer, sélectionnez Rôles d’application.
5. Vérifiez le rôle d’application défini par Gestion des API Azure, comme illustré dans la capture d’écran suivante :

Inscrire l’application cliente pour accéder au produit

Inscrivez maintenant une application cliente qui limite l’accès à un ou plusieurs produits.

• Un produit doit avoir l’accès basé sur l’application activé pour être associé à une application cliente.
• Chaque application cliente dispose d’un seul utilisateur (propriétaire) dans l’instance Gestion des API. Seul le propriétaire peut accéder aux API de produit via l’application.
• Un produit peut être associé à plusieurs applications clientes.

Pour inscrire une application cliente :

1. Connectez-vous au portail à l’URL personnalisée suivante pour la fonctionnalité des applications : ;https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications

2. Accédez à votre instance API Management.

3. Dans le menu de gauche, sous API, sélectionnez Applications>+ Inscrire une application.

4. Dans la page Inscrire une application , entrez les paramètres d’application suivants :

   • Nom : entrez un nom pour l’application.
   • Propriétaire : sélectionnez le propriétaire de l’application dans la liste déroulante des utilisateurs de l’instance Gestion des API.
   • Accorder l’accès aux produits sélectionnés : sélectionnez un ou plusieurs produits dans l’instance Gestion des API qui ont été précédemment activés pour l’accès basé sur l’application.
   • Description : Si vous le souhaitez, entrez une description.

   

5. Sélectionnez Inscrire.

L’application est ajoutée à la liste des applications dans la page Applications . Sélectionnez l’application pour afficher les détails tels que l’ID client. Vous avez besoin de cet ID pour générer un jeton pour appeler l’API de produit.

Conseil / Astuce

• Après avoir créé une application, associez-la éventuellement à d’autres produits. Sélectionnez l’application dans la page Applications , puis sélectionnez Détails>produits>+ Ajouter un produit.
• Vous pouvez également créer ou associer une application en modifiant un produit à partir de la page Produits .

Générer une clé secrète client

Une clé secrète client doit être générée pour que l’application cliente utilise le flux d’informations d’identification du client OAuth 2.0. Le secret est valide pendant un an, mais peut être régénéré à tout moment.

1. Dans la page Applications , sélectionnez l’application que vous avez créée.

2. Dans la page Vue d’ensemble de l’application, en regard de la clé secrète client, sélectionnez Ajouter un secret.

3. Dans la page Nouvelle clé secrète client , sélectionnez Générer.

   Une clé secrète client est générée et affichée dans le champ Secret client . Veillez à copier la valeur secrète et à la stocker en toute sécurité. Vous ne pourrez plus le récupérer une fois que vous fermez la page.

4. Sélectionnez Fermer.

(Facultatif) Passer en revue les paramètres de l’application cliente dans l’ID Microsoft Entra

Si vous le souhaitez, passez en revue les paramètres de l’application cliente dans l’ID Microsoft Entra.

L’application est nommée au format suivant : APIMApplication<product-name>. Par exemple, si le nom du produit est Starter, le nom de l’application est similaire à APIMApplicationStarter.

Pour passer en revue les paramètres d'application dans Inscriptions d'applications :

1. Connectez-vous au portail et accédez à Microsoft Entra ID>Manage>App Registrations.

2. Sélectionnez Toutes les applications.

3. Recherchez et sélectionnez l’application cliente créée par Gestion des API.

4. Dans le menu de gauche, sous Gérer, sélectionnez autorisations d’API.

5. Vérifiez que l’application dispose des autorisations nécessaires pour accéder à l’application ou aux applications du produit principal.

   Par exemple, si l’application cliente accorde l’accès au produit Starter , l’application dispose des autorisations Product.Starter.All pour accéder à l’application APIMProductApplicationStarter .

   

Obtenir les paramètres d’application dans le portail des développeurs

Les utilisateurs peuvent se connecter au portail des développeurs pour afficher les applications clientes qu’ils possèdent.

1. Connectez-vous au portail des développeurs (https://<your-apim-instance-name>.developer.azure-api.net) à l’aide d’un compte d’utilisateur qui a été défini comme propriétaire d’une application cliente.

2. Dans le menu de navigation supérieur, sélectionnez Applications.

3. Les applications que l’utilisateur possède apparaissent dans la liste.

4. Sélectionnez une application pour afficher ses détails, tels que l’ID client, la clé secrète client et l’étendue. Ces valeurs sont nécessaires pour générer un jeton pour appeler les API de produit.

   

Créer un jeton et l’utiliser avec l’appel d’API

Après avoir activé l’accès basé sur l’application pour un produit et inscrit une application cliente, un développeur ou une application peut générer un jeton pour appeler les API du produit. Le jeton doit être inclus dans l’en-tête Authorization d’une requête.

Par exemple, un développeur ou une application peut exécuter les scripts Azure PowerShell suivants pour appeler l’application cliente pour générer un jeton, puis utiliser le jeton pour appeler une API de produit dans Gestion des API.

Avertissement

Les scripts suivants sont des exemples à des fins de test uniquement. En production, utilisez une méthode sécurisée pour stocker et récupérer le secret client.

Appeler l’application cliente pour générer un jeton

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Appeler l’API de produit à l’aide d’un jeton

Le jeton généré à l’étape précédente est utilisé pour appeler une API de produit. Le jeton est transmis dans l’en-tête d’autorisation de la requête. L’instance Gestion des API valide le jeton et autorise l’accès à l’API.

Le script suivant montre un exemple d’appel à l’API echo.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Résolution des problèmes

Erreur de serveur interne lors de l’inscription d’applications dans le portail

Si vous ne parvenez pas à répertorier les applications ou si vous recevez une erreur de serveur interne lors de l’inscription d’applications dans le portail, vérifiez ce qui suit :

• Le rôle Administrateur d’application est affecté à l’identité managée de l’instance Gestion des API dans l’ID Microsoft Entra.
• Vous êtes connecté au portail à l’URL personnalisée suivante pour la fonctionnalité des applications : ;https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=applications. Cette URL est requise pour accéder à la fonctionnalité d’applications dans Gestion des API.

Contenu connexe

• Créer et publier un produit
• Authentification et autorisation des API dans Gestion des API