Partage via

Démarrage rapide : Configurer une application pour exposer une API web

  • Article

Dans ce guide de démarrage rapide, vous allez inscrire une API web auprès de la plateforme d’identités Microsoft et l’exposer à des applications clientes en ajoutant une étendue. En enregistrant votre API web et en l'exposant par le biais de scopes, en attribuant un propriétaire et un rôle d'application, vous pouvez fournir un accès basé sur des permissions à ses ressources aux utilisateurs autorisés et aux applications clientes qui accèdent à votre API.

Prérequis

Inscrire l’API web

L’accès aux API suppose de configurer les étendues d’accès et les rôles. Si vous souhaitez exposer aux applications clientes les API web de vos applications de ressources, configurez les étendues d’accès et les rôles de l’API. Si vous voulez qu’une application cliente puisse accéder à une API web, configurez les autorisations d’accès à l’API lors de l’inscription de l’application.

Pour fournir un accès délimité aux ressources de votre API web, vous devez d’abord inscrire l’API auprès de la plateforme d’identités Microsoft.

Effectuez les étapes décrites dans la section Inscrire une application du guide de Démarrage rapide : Inscrire une application auprès de la plateforme d’identités Microsoft.

Ignorez la section URI de redirection (facultatif). Vous n’avez pas besoin de configurer un URI de redirection pour une API web, car aucun utilisateur n’est connecté de manière interactive.

Assigner le propriétaire de l’application

  1. Dans l’inscription de votre application, sous Gérer, sélectionnez Propriétaires, puis Ajouter des propriétaires.
  2. Dans la nouvelle fenêtre, recherchez et sélectionnez le ou les propriétaires que vous souhaitez affecter à l’application. Les propriétaires sélectionnés s’affichent dans le panneau droit. Une fois que vous avez terminé, confirmez avec Sélectionner. Le ou les propriétaires de l’application apparaissent désormais dans la liste du propriétaire.

Remarque

Assurez-vous que l’application API et l’application à laquelle vous souhaitez ajouter des autorisations ont un propriétaire. Sinon, l’API ne sera pas répertoriée lors de la demande d’autorisations d’API.

Assigner le rôle d’application

  1. Dans l’inscription de votre application, sous Gérer, sélectionnez Rôles d’application, puis Créer un rôle d’application.

  2. Ensuite, spécifiez les attributs du rôle d’application dans le volet Créer un rôle d’application . Pour cette procédure pas à pas, vous pouvez utiliser les exemples de valeurs ou spécifier les vôtres.

    Champ Description Exemple
    Nom complet Nom de votre rôle d’application Enregistrements d’employés
    Types de membres autorisés Spécifie si le rôle d’application peut être attribué à des utilisateurs/groupes et/ou à des applications Applications
    Valeur Valeur affichée dans la revendication « rôles » d’un jeton Employee.Records
    Description Une description plus détaillée de rôle d’application. Les applications ont accès aux enregistrements des employés

  3. Cochez la case pour activer le rôle d’application.

Une fois l'API Web enregistrée et dotée d'un rôle d'application et d'un propriétaire, vous pouvez ajouter des champs d'application au code de l'API afin qu'il puisse fournir des autorisations granulaires aux consommateurs.

Ajouter une étendue

Conseil

Les étapes décrites dans cet article peuvent varier légèrement en fonction du portail de départ.

Le code d’une application cliente demande l’autorisation d’effectuer des opérations définies par votre API web en transmettant un jeton d’accès avec ses demandes à la ressource protégée (l’API web). Votre API web effectue ensuite l’opération demandée uniquement si le jeton d’accès qu’elle reçoit contient les étendues nécessaires.

Tout d’abord, effectuez les étapes suivantes pour créer un exemple d’étendue nommé Employees.Read.All :

  1. Connectez-vous au Centre d’administration de Microsoft Entra au minimum en tant qu’Administrateur d’application cloud.

  2. Si vous avez accès à plusieurs tenants, utilisez l’icône Paramètres dans le menu supérieur pour basculer vers le tenant contenant l’enregistrement de l’application à partir du menu Répertoires + abonnements.

  3. Accédez àIdentité>Applications>Inscriptions d'applications, puis sélectionnez l’inscription d’application de votre API.

  4. Sélectionner Exposer une API

  5. Sélectionnez Ajouter en regard de URI d’ID d’application si vous n’en avez pas encore configuré un.

    Vous pouvez utiliser la valeur par défaut de api://<application-client-id> ou un autre modèle d’URI d’ID d’application pris en charge. L’URI d’ID d’application, qui doit être globalement unique, fait office de préfixe pour les étendues que vous référencerez dans le code de votre API.

  6. Sélectionnez Ajouter une étendue :

    An app registration's Expose an API pane in the Azure portal

  7. Spécifiez ensuite les attributs de l’étendue dans le volet Ajouter une étendue. Pour cette procédure pas à pas, vous pouvez utiliser les exemples de valeurs ou spécifier les vôtres.

    Champ Description Exemple
    Nom de l'étendue Nom de votre étendue. Une convention de nommage d’étendue courante est resource.operation.constraint. Employees.Read.All
    Qui peut donner son consentement Indique si cette étendue peut être consentie par des utilisateurs ou si le consentement d’un administrateur est nécessaire. Sélectionnez administrateurs uniquement pour des autorisations à privilèges élevés. Administrateurs et utilisateurs
    Nom d'affichage du consentement administrateur Courte description de l’objectif de l’étendue que seuls les administrateurs verront. Read-only access to Employee records
    Description du consentement de l'administrateur Description plus détaillée de l’autorisation accordée par l’étendue que seuls les administrateurs verront. Allow the application to have read-only access to all Employee data.
    Nom d'affichage du consentement de l'utilisateur Courte description de l’objectif de l’étendue. Affichée aux utilisateurs uniquement si vous définissez Qui peut donner son consentement sur Administrateurs et utilisateurs. Read-only access to your Employee records
    Description du consentement de l'utilisateur Description plus détaillée de l’autorisation accordée par l’étendue. Affichée aux utilisateurs uniquement si vous définissez Qui peut donner son consentement sur Administrateurs et utilisateurs. Allow the application to have read-only access to your Employee data.

  8. Définissez l’État sur Activé, puis sélectionnez Ajouter une étendue.

  9. (Facultatif) Pour supprimer les demandes de consentement des utilisateurs de votre application pour les étendues que vous avez définies, vous pouvez préautoriser l’application cliente à accéder à votre API web. Préautorisez uniquement les applications clientes que vous approuvez, car vos utilisateurs n’auront pas la possibilité de refuser le consentement.

    1. Sous Applications clientes autorisées, sélectionnez Ajouter une application cliente.
    2. Entrez l’ID d’application (client) de l’application cliente que vous souhaitez préautoriser, par exemple celui d’une application web que vous avez inscrite précédemment.
    3. Sous Étendues autorisées, sélectionnez les étendues pour lesquelles vous souhaitez supprimer les invites de consentement, puis sélectionnez Ajouter une application.

    Si vous avez effectué cette étape facultative, l’application cliente est désormais une application cliente préautorisée, et les utilisateurs ne sont pas invités à donner leur consentement quand ils s’y connectent.

Ajoutez ensuite un autre exemple d’étendue nommé Employees.Write.All auquel seuls les administrateurs peuvent donner leur consentement. Les étendues qui nécessitent le consentement de l’administrateur sont généralement utilisées pour fournir l’accès à des opérations avec des privilèges plus élevés, et souvent par des applications clientes qui s’exécutent en tant que services back-end ou en tant que démons qui ne connectent pas un utilisateur de manière interactive.

Pour ajouter l’exemple d’étendue Employees.Write.All, effectuez les étapes décrites dans la section Ajouter une étendue, puis spécifiez ces valeurs dans le volet Ajouter une étendue :

Champ Exemple de valeur
Nom de l'étendue Employees.Write.All
Qui peut donner son consentement Administrateurs uniquement
Nom d'affichage du consentement administrateur Write access to Employee records
Description du consentement de l'administrateur Allow the application to have write access to all Employee data.
Nom d'affichage du consentement de l'utilisateur Aucune (laisser vide)
Description du consentement de l'utilisateur Aucune (laisser vide)

Définissez l’État sur Activé, puis sélectionnez Ajouter une étendue.

Vérifier les étendues exposées

Si vous avez correctement ajouté les deux exemples d’étendues décrits dans les sections précédentes, ils apparaissent dans le volet Exposer une API de l’inscription d’application de votre API web, semblable à l’image suivante :

Screenshot of the Expose an API pane showing two exposed scopes.

Comme indiqué dans l’image, la chaîne complète d’une étendue est la concaténation de l’URI d’ID d’application de votre API web et du Nom de l’étendue.

Par exemple, si l’URI d’ID d’application de votre API web est https://contoso.com/api, et que le nom de l’étendue est Employees.Read.All, l’étendue complète est :

https://contoso.com/api/Employees.Read.All

Utilisation des étendues exposées

Dans l’article suivant de cette série, vous allez configurer l’inscription d’une application cliente avec un accès à votre API web et les étendues que vous avez définies en suivant les étapes de cet article.

Une fois qu’une inscription d’application cliente est autorisée à accéder à votre API web, la plateforme d’identités peut émettre un jeton d’accès OAuth 2.0 pour le client. Quand le client appelle l’API web, il présente un jeton d’accès dont la revendication d’étendue (scp) est définie sur les autorisations que vous avez spécifiées dans l’inscription d’application du client.

Vous pouvez exposer des étendues supplémentaires ultérieurement si nécessaire. Considérez que votre API web peut exposer plusieurs étendues associées à plusieurs opérations. Votre ressource peut contrôler l’accès à l’API web lors de l’exécution, en évaluant les revendications de l’étendue (scp) dans le jeton d’accès OAuth 2.0 qu’elle reçoit.

Étapes suivantes

Maintenant que vous avez exposé votre API web en configurant ses étendues, configurez l’inscription de votre application cliente avec l’autorisation d’accès aux étendues.

Configurer une inscription d’application pour l’accès à une API web