Partager 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 nécessite la configuration d’étendues d’accès et de 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.

  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. Effectuez la procédure pour inscrire une application et 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.

Attribuer le propriétaire de l’applicationr

  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. Sélectionnez la case à cocher pour activer le rôle d’application, puis Appliquer.

Ajouter une étendue

Conseil

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

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.

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. Sélectionnez Exposer une API.

  2. En haut de la page, sélectionnez Ajouter à côté d’URI D’ID d’application. La valeur par défaut est api://<application-client-id>. 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. Cliquez sur Enregistrer.

  3. Sélectionnez Ajouter une étendue :

    Volet Exposer une API d’une inscription d’application dans le portail Azure

  4. 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. Vous devez utiliser Administrateurs uniquement pour les 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. Accès en lecture seule pour les enregistrements Employés
    Description du consentement de l'administrateur Description plus détaillée de l’autorisation accordée par l’étendue que seuls les administrateurs verront. Autoriser l’application pour avoir un accès en lecture seule à toutes les données Employé.
    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. Accès en lecture seule pour les enregistrements Employés
    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. Autoriser l’application pour avoir un accès en lecture seule à toutes les données Employé.
    État Indique si l’étendue est activée ou désactivée. Activé

  5. Sélectionnez Ajouter une étendue.

  6. (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 de la section Ajouter une étendue, puis spécifiez ces valeurs dans le volet Ajouter une étendue. Sélectionnez Ajouter une étendue quand vous avez terminé :

Champ Exemple de valeur
Nom de l'étendue Employees.Write.All
Qui peut donner son consentement Administrateurs uniquement
Nom d'affichage du consentement administrateur Accès en lecture seule pour les enregistrements Employés
Description du consentement de l'administrateur Autorisez l’application pour avoir un accès en lecture seule à toutes les données Employé.
Nom d'affichage du consentement de l'utilisateur Aucune (laisser vide)
Description du consentement de l'utilisateur Aucune (laisser vide)
État Activé

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 :

Capture d’écran du volet Exposer une API montrant deux étendues exposées.

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.

Étape suivante

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