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

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

• Un compte Azure avec un abonnement actif : créez gratuitement un compte
• Exécution du Démarrage rapide : Configurer un locataire

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.

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

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 :

   

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.

Ajouter une étendue nécessitant un consentement administrateur

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 :

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 :

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.