Démarrage rapide : Configurer une application pour exposer une API webQuickstart: Configure an application to expose a web API

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 un exemple d’étendue.In this quickstart, you register a web API with the Microsoft identity platform and expose it to client apps by adding an example scope. En inscrivant votre API web et en l’exposant par le biais d’étendues, vous pouvez fournir un accès basé sur les autorisations à ses ressources pour les utilisateurs autorisés et les applications clientes qui accèdent à votre API.By registering your web API and exposing it through scopes, you can provide permissions-based access to its resources to authorized users and client apps that access your API.

PrérequisPrerequisites

Inscrire l’API webRegister the web API

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.To provide scoped access to the resources in your web API, you first need to register the API with the Microsoft identity platform.

  1. 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.Perform the steps in the Register an application section of Quickstart: Register an app with the Microsoft identity platform.
  2. Ignorez les sections Ajouter un URI de redirection et Configurer les paramètres de plateforme.Skip the Add a redirect URI and Configure platform settings sections. 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.You don't need to configure a redirect URI for a web API since no user is logged in interactively.
  3. Ignorez la section Ajouter des informations d’identification pour le moment.Skip the Add credentials section for now. Votre API a besoin de ses propres informations d’identification uniquement si elle accède à une API en aval. Ce scénario n’est pas abordé dans cet article.Only if your API accesses a downstream API would it need its own credentials, a scenario not covered in this article.

Une fois votre API web inscrite, vous êtes prêt à ajouter les étendues que le code de votre API peut utiliser pour fournir une autorisation précise aux consommateurs de cette dernière.With your web API registered, you're ready to add the scopes that your API's code can use to provide granular permission to consumers of your API.

Ajouter une étendueAdd a scope

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).The code in a client application requests permission to perform operations defined by your web API by passing an access token along with its requests to the protected resource (the web API). 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.Your web API then performs the requested operation only if the access token it receives contains the scopes required for the operation.

Tout d’abord, effectuez les étapes suivantes pour créer un exemple d’étendue nommé Employees.Read.All :First, follow these steps to create an example scope named Employees.Read.All:

  1. Connectez-vous au portail Azure.Sign in to the Azure portal.

  2. Si vous avez accès à plusieurs locataires, utilisez le filtre Répertoire + abonnement dans le menu du haut pour sélectionner le locataire contenant l’inscription de votre application cliente.

  3. Sélectionnez Azure Active Directory > Inscriptions d’applications, puis l’inscription d’application de votre API.Select Azure Active Directory > App registrations, and then select your API's app registration.

  4. Sélectionnez Exposer une API > Ajouter une étendue.Select Expose an API > Add a scope.

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

  5. Vous êtes invité à définir un URI d’ID d’application si vous n’en avez pas encore configuré un.You're prompted to set an Application ID URI if you haven't yet configured one.

    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.The App ID URI acts as the prefix for the scopes you'll reference in your API's code, and it must be globally unique. Vous pouvez utiliser la valeur par défaut fournie, qui se présente sous la forme api://<application-client-id>, ou spécifier un URI plus lisible comme https://contoso.com/api.You can use the default value provided, which is in the form api://<application-client-id>, or specify a more readable URI like https://contoso.com/api.

  6. Spécifiez ensuite les attributs de l’étendue dans le volet Ajouter une étendue.Next, specify the scope's attributes in the Add a scope pane. Pour cette procédure pas à pas, vous pouvez utiliser les exemples de valeurs ou spécifier les vôtres.For this walk-through, you can use the example values or specify your own.

    ChampField DescriptionDescription ExempleExample
    Nom de l'étendueScope name Nom de votre étendue.The name of your scope. Une convention de nommage d’étendue courante est resource.operation.constraint.A common scope naming convention is resource.operation.constraint. Employees.Read.All
    Qui peut donner son consentementWho can consent Indique si cette étendue peut être consentie par des utilisateurs ou si le consentement d’un administrateur est nécessaire.Whether this scope can be consented to by users or if admin consent is required. Sélectionnez administrateurs uniquement pour des autorisations à privilèges élevés.Select Admins only for higher-privileged permissions. Administrateurs et utilisateursAdmins and users
    Nom d'affichage du consentement administrateurAdmin consent display name Courte description de l’objectif de l’étendue que seuls les administrateurs verront.A short description of the scope's purpose that only admins will see. Read-only access to Employee records
    Description du consentement de l'administrateurAdmin consent description Description plus détaillée de l’autorisation accordée par l’étendue que seuls les administrateurs verront.A more detailed description of the permission granted by the scope that only admins will see. Allow the application to have read-only access to all Employee data.
    Nom d'affichage du consentement de l'utilisateurUser consent display name Courte description de l’objectif de l’étendue.A short description of the scope's purpose. Affichée aux utilisateurs uniquement si vous définissez Qui peut donner son consentement sur Administrateurs et utilisateurs.Shown to users only if you set Who can consent to Admins and users. Read-only access to your Employee records
    Description du consentement de l'utilisateurUser consent description Description plus détaillée de l’autorisation accordée par l’étendue.A more detailed description of the permission granted by the scope. Affichée aux utilisateurs uniquement si vous définissez Qui peut donner son consentement sur Administrateurs et utilisateurs.Shown to users only if you set Who can consent to Admins and users. Allow the application to have read-only access to your Employee data.
  7. Définissez l’État sur Activé, puis sélectionnez Ajouter une étendue.Set the State to Enabled, and then select Add scope.

  8. (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.(Optional) To suppress prompting for consent by users of your app to the scopes you've defined, you can pre-authorize the client application to access your web API. Préautorisez uniquement les applications clientes que vous approuvez, car vos utilisateurs n’auront pas la possibilité de refuser le consentement.Pre-authorize only those client applications you trust since your users won't have the opportunity to decline consent.

    1. Sous Applications clientes autorisées, sélectionnez Ajouter une application cliente.Under Authorized client applications, select Add a client application
    2. Entrez l’ID d’application (client) de l’application cliente que vous souhaitez préautoriser,Enter the Application (client) ID of the client application you want to pre-authorize. par exemple celui d’une application web que vous avez inscrite précédemment.For example, that of a web application you've previously registered.
    3. Sous Étendues autorisées, sélectionnez les étendues pour lesquelles vous souhaitez supprimer les invites de consentement, puis sélectionnez Ajouter une application.Under Authorized scopes, select the scopes for which you want to suppress consent prompting, then select Add 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.If you followed this optional step, the client app is now a pre-authorized client app (PCA), and users won't be prompted for their consent when signing in to it.

Ajoutez ensuite un autre exemple d’étendue nommé Employees.Write.All auquel seuls les administrateurs peuvent donner leur consentement.Next, add another example scope named Employees.Write.All that only admins can consent to. 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.Scopes that require admin consent are typically used for providing access to higher-privileged operations, and often by client applications that run as backend services or daemons that don't sign in a user interactively.

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 :To add the Employees.Write.All example scope, follow the steps in the Add a scope section and specify these values in the Add a scope pane:

ChampField Valeur d'exempleExample value
Nom de l'étendueScope name Employees.Write.All
Qui peut donner son consentementWho can consent Administrateurs uniquementAdmins only
Nom d'affichage du consentement administrateurAdmin consent display name Write access to Employee records
Description du consentement de l'administrateurAdmin consent description Allow the application to have write access to all Employee data.
Nom d'affichage du consentement de l'utilisateurUser consent display name Aucune (laisser vide)None (leave empty)
Description du consentement de l'utilisateurUser consent description Aucune (laisser vide)None (leave empty)

Vérifier les étendues exposéesVerify the exposed scopes

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 à cette image :If you successfully added both example scopes described in the previous sections, they'll appear in the Expose an API pane of your web API's app registration, similar to this image:

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

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.As shown in the image, a scope's full string is the concatenation of your web API's Application ID URI and the scope's Scope name.

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 :For example, if your web API's application ID URI is https://contoso.com/api and the scope name is Employees.Read.All, the full scope is:

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

Utilisation des étendues exposéesUsing the exposed scopes

Dans l’article suivant de la 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.In the next article in the series, you configure a client app's registration with access to your web API and the scopes you defined by following the steps this article.

Une fois qu’une inscription d’application cliente est autorisée à accéder à votre API web, la plateforme d’identités Microsoft peut émettre un jeton d’accès OAuth 2.0 pour le client.Once a client app registration is granted permission to access your web API, the client can be issued an OAuth 2.0 access token by the Microsoft identity platform. 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.When the client calls the web API, it presents an access token whose scope (scp) claim is set to the permissions you've specified in the client's app registration.

Vous pouvez exposer des étendues supplémentaires ultérieurement si nécessaire.You can expose additional scopes later as necessary. Considérez que votre API web peut exposer plusieurs étendues associées à plusieurs opérations.Consider that your web API can expose multiple scopes associated with several operations. Votre ressource peut contrôler l’accès à l’API web lors de l’exécution, en évaluant la ou les revendications de l’étendue (scp) dans le jeton d’accès OAuth 2.0 qu’elle reçoit.Your resource can control access to the web API at runtime by evaluating the scope (scp) claim(s) in the OAuth 2.0 access token it receives.

Étapes suivantesNext steps

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.Now that you've exposed your web API by configuring its scopes, configure your client app's registration with permission to access the scopes.