Partager via

API web protégée : Inscription d'application

  • Article

Cet article explique comment inscrire une application pour une API web protégée.

Pour connaître les étapes courantes visant à inscrire une application, consultez Démarrage rapide : Inscrire une application avec la plateforme des identités Microsoft.

Version de jeton acceptée

La plateforme d’identités Microsoft peut émettre des jetons v1.0 et des jetons v2.0. Pour plus d’informations sur ces jetons, consultez Jetons d’accès.

La version de jeton que votre API peut accepter dépend de la sélection de Types de compte pris en charge lorsque vous créez l’inscription de votre application API Web dans le Portail Azure.

  • Si la valeur de Types de comptes pris en charge est Comptes dans un annuaire organisationnel et comptes personnels Microsoft (par exemple, Skype, Xbox, Outlook.com), la version de jeton acceptée est v2.0.
  • Sinon, la version de jeton acceptée est v1.0.

Après avoir créé l’application, vous pouvez déterminer ou changer la version de jeton acceptée en procédant comme suit :

  1. Dans le Centre d’administration Microsoft Entra, sélectionnez votre application, puis sélectionnez Manifeste.
  2. Recherchez la propriété accessTokenAcceptedVersion dans le manifeste.
  3. La valeur spécifie à Microsoft Entra la version de jeton acceptée par l’API web.
    • Si la valeur est 2, l’API web accepte les jetons v2.0.
    • Si la valeur est Null, l’API web accepte les jetons v1.0.
  4. Si vous avez modifié la version de jeton, sélectionnez Enregistrer.

L’API web spécifie la version de jeton qu’elle accepte. Quand un client demande un jeton pour votre API web auprès de la plateforme d’identités Microsoft, le client obtient un jeton qui indique quelle version de jeton est acceptée par l’API web.

Aucun URI de redirection

Les API web n’ont pas besoin d’inscrire d’URI de redirection, car aucun utilisateur n’est connecté de manière interactive.

API exposée

D’autres paramètres spécifiques aux API web sont l’API exposée et les étendues exposées ou rôles d’application.

Étendues et URI d’ID d’application

Les étendues se présentent généralement sous la forme resourceURI/scopeName. Pour Microsoft Graph, les étendues ont des raccourcis. Par exemple, User.Read est un raccourci pour https://graph.microsoft.com/user.read.

Lors de l’inscription de l’application, définissez les paramètres suivants :

  • L’URI de ressource
  • Une ou plusieurs étendues
  • Un ou plusieurs rôles d’application

Par défaut, le portail d’inscription des applications vous recommande d’utiliser l’URI de ressource api://{clientId}. Cet URI est unique, mais n’est pas lisible. Si vous modifiez l’URI, assurez-vous que la nouvelle valeur est unique. Le portail d’inscription des applications s’assure que vous utilisez un domaine de serveur de publication configuré.

Pour les applications clientes, les étendues s’affichent en tant que permissions déléguées et les rôles d’application en tant que permissions d’application pour votre API web.

Les étendues s’affichent également dans la fenêtre de consentement présentée aux utilisateurs de votre application. Par conséquent, fournissez les chaînes correspondantes qui décrivent l’étendue :

  • Comme vue par un utilisateur.
  • Comme vue par l’administrateur client, qui peut accorder un consentement administrateur.

Les rôles d’application ne peuvent pas être consentis par un utilisateur (car ils sont utilisés par une application qui appelle l’API Web pour son propre compte). Un administrateur client devra donner son consentement aux applications clientes de votre API Web qui exposent des rôles d’application. Pour plus d’informations, consultez Consentement administrateur.

Exposer des autorisations déléguées (étendues)

Pour exposer des autorisations déléguées ou des étendues, suivez les étapes de la section Configurer une application pour exposer une API web.

Si vous suivez le scénario d’API web décrit dans ces articles, utilisez ces paramètres :

  • URI d’ID d’application : acceptez l’URI d’ID d’application proposé (api://<clientId>) (si vous y êtes invité)
  • Nom de l’étendue : access_as_user
  • Qui peut donner son consentement ? : Administrateurs et utilisateurs
  • Nom d’affichage du consentement de l’administrateur : Accéder à TodoListService en tant qu’utilisateur
  • Description du consentement de l’administrateur : Accède à l’API web TodoListService en tant qu’utilisateur
  • Nom d’affichage du consentement de l’utilisateur : Accéder à TodoListService en tant qu’utilisateur
  • Description du consentement de l’utilisateur : Accède à l’API web TodoListService en tant qu’utilisateur
  • État : Activé

Conseil

Pour l’URI d’ID d’application, vous avez la possibilité de le définir sur l’autorité physique de l’API, par exemple https://graph.microsoft.com. Cela peut être utile si l’URL de l’API à appeler est connue.

Si votre API web est appelée par un service ou une application démon

Exposez les autorisations d’application au lieu des autorisations déléguées si votre API doit être accessible par des démons, des services ou d’autres applications non interactives (par un humain). Comme les applications de type démon et service s’exécutent sans assistance et s’authentifient avec leur propre identité, il n’existe aucun utilisateur pour « déléguer » leur autorisation.

Exposer des autorisations d’application (rôles d’application)

Pour exposer des autorisations d’application, suivez les étapes décrites dans Ajouter des rôles d’application à votre application.

Dans le volet Créer un rôle d’application sous Types de membres autorisés, sélectionnez Applications. Vous pouvez également ajouter le rôle à l’aide de l’éditeur de manifeste d’application, comme décrit dans l’article.

Restreindre les jetons d’accès à des applications clientes spécifiques

Les rôles d’application représentent le mécanisme utilisé par les développeurs d’applications pour exposer les autorisations de leur application. Le code de votre API web doit rechercher les rôles d’application dans les jetons d’accès qu’il reçoit des appelants.

Pour ajouter une autre couche de sécurité, un administrateur de locataire Microsoft Entra peut configurer son locataire afin que la plateforme d’identité Microsoft émette des jetons de sécurité uniquement pour les applications clientes dont il a approuvé l’accès à l’API.

Pour renforcer la sécurité en limitant l’émission de jeton uniquement aux applications clientes qui ont reçu des rôles d’application :

  1. Dans le centre d’administration Microsoft Entra, sélectionnez votre application sous Identité>Applications>Inscriptions d’applications.
  2. Sur la page de présentation de l'application, dans Essentials, recherchez et sélectionnez le lien Managed application in local directory pour accéder à la page de présentation de l'application d'entreprise.
  3. Sous Gérer, sélectionnez Propriétés.
  4. Définissez Affectation requise ? sur Oui.
  5. Cliquez sur Enregistrer.

Microsoft Entra ID recherche maintenant les attributions de rôle des applications clientes qui demandent des jetons d’accès pour votre API web. Si aucune application cliente n’a été affectée à un rôle d’application, Microsoft Entra ID retourne un message d’erreur au client similaire à _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Avertissement

N’utilisez PAS les codes d’erreur AADSTS ou leurs chaînes de message comme littéraux dans le code de votre application. Les codes d’erreur « AADSTS » et les chaînes de message d’erreur renvoyées par Microsoft Entra ID ne sont pas immuables et peuvent être changés par Microsoft à tout moment et sans préavis. Si vous prenez des décisions de création de branches dans votre code en fonction des valeurs des codes AADSTS ou de leurs chaînes de message, vous mettez en péril les fonctionnalités et la stabilité de votre application.

Étape suivante

L’article suivant de cette série présente la configuration du code d’application.