Obtenir l’accès sans utilisateur
Pour appeler Microsoft Graph, une application doit obtenir un jeton d’accès auprès du Plateforme d'identités Microsoft. Ce jeton d’accès inclut des informations indiquant si l’application est autorisée à accéder à Microsoft Graph pour le compte d’un utilisateur connecté ou avec sa propre identité. Cet article fournit des conseils sur la façon dont une application peut accéder à Microsoft Graph avec sa propre identité, également appelée accès d’application uniquement.
Cet article détaille les requêtes HTTP brutes impliquées pour qu’une application appelle Microsoft Graph avec sa propre identité à l’aide d’un flux populaire appelé flux d’octroi des informations d’identification du client OAuth 2.0. Vous pouvez également éviter d’écrire des requêtes HTTP brutes et utiliser une bibliothèque d’authentification intégrée ou prise en charge par Microsoft qui gère un grand nombre de ces détails pour vous et vous aide à obtenir des jetons d’accès et à appeler Microsoft Graph. Pour plus d’informations, consultez Utiliser la bibliothèque d’authentification Microsoft (MSAL).
Configuration requise
Avant de passer aux étapes décrites dans cet article :
- Comprendre les concepts d’authentification et d’autorisation dans le Plateforme d'identités Microsoft. Pour plus d’informations, consultez Principes de base de l’authentification et de l’autorisation.
- Inscrivez l’application avec Microsoft Entra ID. Pour plus d’informations, consultez Inscrire une application avec le Plateforme d'identités Microsoft.
Étapes relatives à l’autorisation et à l’authentification
Pour qu’une application obtienne l’autorisation et l’accès à Microsoft Graph à l’aide du flux d’informations d’identification du client, vous devez suivre les cinq étapes suivantes :
- Inscrivez l’application avec Microsoft Entra ID.
- Configurez les autorisations de l’application Microsoft Graph sur l’application.
- Demander le consentement de l’administrateur.
- Demandez un jeton d’accès.
- Appelez Microsoft Graph à l’aide du jeton d’accès.
1. Inscrire l’application
Avant que l’application puisse utiliser le point de terminaison Plateforme d'identités Microsoft ou appeler Microsoft Graph, elle doit être correctement inscrite. Suivez les étapes pour inscrire votre application sur le centre d'administration Microsoft Entra.
À partir de l’inscription de l’application, enregistrez les valeurs suivantes :
- ID d’application (appelé ID d’objet sur le centre d'administration Microsoft Entra) attribué par le portail d’inscription d’application.
- Une clé secrète client (mot de passe d’application), un certificat ou des informations d’identification d’identité fédérée.
- URI de redirection permettant à l’application de recevoir des réponses de jeton de Microsoft Entra ID.
- URI de redirection permettant au service de recevoir des réponses de consentement administrateur si l’application implémente des fonctionnalités pour demander le consentement de l’administrateur.
2. Configurer les autorisations pour Microsoft Graph
Microsoft Graph expose des autorisations d’application pour les applications qui appellent Microsoft Graph sous leur propre identité. Ces autorisations nécessitent toujours le consentement de l’administrateur.
Vous préconfigurez les autorisations d’application dont l’application a besoin lorsque vous inscrivez l’application. Un administrateur peut donner son consentement à ces autorisations à l’aide du centre d'administration Microsoft Entra lorsqu’il installe l’application dans son organization, ou vous pouvez fournir une expérience d’inscription dans l’application par le biais de laquelle les administrateurs peuvent donner leur consentement aux autorisations que vous avez configurées. Une fois que Microsoft Entra ID enregistre le consentement de l’administrateur, l’application peut demander des jetons sans avoir à demander à nouveau le consentement.
Pour configurer les autorisations d’application pour l’application dans le portail d’inscriptions d’applications Azure, procédez comme suit :
- Sous la page Autorisations de l’API de l’application, choisissez Ajouter une autorisation.
- Sélectionnez Microsoft Graph.
- Sélectionnez Autorisations d’application.
- Dans la boîte de dialogue Sélectionner les autorisations , choisissez les autorisations à configurer pour l’application.
La capture d’écran suivante illustre la boîte de dialogue Sélectionner les autorisations pour les autorisations de l’application Microsoft Graph.
Importante
Configurez toujours le jeu d’autorisations le moins privilégié requis par l’application. Pour plus d’informations, consultez Bonnes pratiques pour l’utilisation des autorisations Microsoft Graph.
3. Demander le consentement de l’administrateur
Les administrateurs peuvent accorder les autorisations dont votre application a besoin au centre d'administration Microsoft Entra. Toutefois, lorsque vous n’avez pas accès à la centre d'administration Microsoft Entra, vous pouvez fournir une expérience d’inscription aux administrateurs à l’aide du point de terminaison Plateforme d'identités Microsoft/adminconsent.
Importante
Lorsque vous modifiez les autorisations configurées, vous devez également répéter le processus de consentement de l’administrateur. Les modifications apportées dans le portail d’inscription d’application ne seront pas répercutées tant qu’un administrateur autorisé tel qu’un administrateur général n’aura pas réinséré à l’application.
Demande
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions HTTP/1.1
| Paramètre | Condition | Description |
|---|---|---|
| client | Obligatoire | Locataire d’annuaire à partir duquel vous souhaitez demander l’autorisation. La valeur peut être au format GUID ou nom convivial. Si vous ne savez pas à quel locataire appartient l’utilisateur et que vous souhaitez lui permettre de se connecter avec n’importe quel locataire, utilisez common. |
| client_id | Requis | ID d’application que le Portail d’inscription des applications Azure a affectée à votre application. |
| redirect_uri | Obligatoire | URI de redirection dans lequel vous souhaitez que la réponse soit envoyée pour que votre application gère. Il doit correspondre à l’un des URI de redirection que vous avez inscrits dans le portail. Il doit être encodé en URL et il peut avoir des segments de chemin d’accès supplémentaires. |
| state | Recommandé | Valeur incluse dans la requête qui est également retournée dans la réponse du jeton. Il peut s’agir d’une chaîne de n’importe quel contenu souhaité. L’état est utilisé pour encoder des informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, telles que la page ou la vue sur laquelle il se trouvait. |
Expérience de consentement administrateur
Avec les demandes adressées au /adminconsent point de terminaison, Microsoft Entra ID impose que seul un administrateur autorisé puisse se connecter pour terminer la demande. L’administrateur est invité à approuver toutes les autorisations d’application que vous avez demandées pour votre application dans le portail d’inscription d’application.
La capture d’écran suivante est un exemple de la boîte de dialogue de consentement que Microsoft Entra ID présente à l’administrateur :
Réponse
Si l’administrateur approuve les autorisations relatives à votre application, la réponse réussie ressemble à ceci :
// Line breaks are for legibility only.
https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
| Paramètre | Description |
|---|---|
| client | Client du répertoire ayant accordé à votre application les autorisations demandées au format GUID. |
| state | Valeur incluse dans la requête qui est également retournée dans la réponse du jeton. Il peut s’agir d’une chaîne de n’importe quel contenu souhaité. L’état est utilisé pour encoder des informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, telles que la page ou la vue sur laquelle il se trouvait. |
| admin_consent | Définissez sur True. |
4. Demander un jeton d’accès
Dans le flux d’octroi des identifiants du client OAuth 2.0, vous utilisez l’ID d’application et les valeurs de la clé secrète client que vous avez enregistrées lors de l’inscription de votre application pour demander un jeton d’accès directement à partir du point de terminaison /token de la plateforme d’identités Microsoft.
Vous spécifiez les autorisations préconfigurées en passant https://graph.microsoft.com/.default comme valeur pour le scope paramètre dans la demande de jeton.
Demande de jeton
Envoyez une requête POST au point de terminaison de la /token plateforme d’identité pour acquérir un jeton d’accès. Dans cette requête, le client utilise la clé secrète client.
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Paramètre | Condition | Description |
|---|---|---|
| client | Obligatoire | Locataire d’annuaire à partir duquel vous souhaitez demander l’autorisation. La valeur peut être au format GUID ou nom convivial. |
| client_id | Requis | ID d’application que le Portail d’inscription d’applications Azure a attribuée lorsque vous avez inscrit votre application. |
| étendue | Requis | La valeur transmise pour le paramètre étendue dans cette requête doit être l'identifiant (app ID URI) de la ressource que vous souhaitez, agrémenté du .defaultsuffixe. Par exemple, l’URI d’ID d’application de ressource Microsoft Graph est https://graph.microsoft.com/. Pour Microsoft Graph, la valeur de l’étendue est donc https://graph.microsoft.com/.default. Cette valeur indique au point de terminaison de la plateforme d’identités Microsoft d’inclure dans le jeton d’accès toutes les autorisations au niveau de l’application que l’administrateur a acceptées. |
| client_secret | Requis | Clé secrète client que vous avez générée pour votre application dans le portail d’inscription de l’application. Vérifiez qu’il est encodé dans l’URL. |
| grant_type | Requis | Doit être client_credentials. |
Réponse du jeton
Une réponse correcte se présente comme suit :
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in":3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Paramètre | Description |
|---|---|
| access_token | Le jeton d'accès demandé. Votre application peut utiliser ce jeton dans les appels à Microsoft Graph. |
| expires_in | Validité du jeton d’accès (en secondes). |
| ext_expires_in | Permet d’indiquer une durée de vie étendue pour le jeton d’accès et de prendre en charge la résilience lorsque le service d’émission de jeton ne répond pas. |
| token_type | Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra ID est Bearer. |
5. Utiliser le jeton d’accès pour appeler Microsoft Graph
Une fois que vous disposez d’un jeton d’accès, l’application l’utilise pour appeler Microsoft Graph en attachant le jeton d’accès en tant que jeton du porteur à l’en-tête Authorization dans une requête HTTP. La requête suivante obtient tous les utilisateurs du locataire. L’application doit disposer de l’autorisation User.Read.All pour appeler cette API.
GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Une réponse réussie ressemble à ceci (certains en-têtes de réponse ont été supprimés) :
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"value": [
{
"businessPhones": [],
"displayName": "Conf Room Adams",
"givenName": null,
"jobTitle": null,
"mail": "Adams@Contoso.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "Adams@Contoso.com",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@Contoso.com",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "AdeleV@Contoso.com",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
Scénarios d’application pris en charge et ressources
Les applications qui appellent Microsoft Graph sous leur propre identité sont classées en deux catégories :
- Les services d’arrière-plan (démons) qui s’exécutent sur un serveur sans qu’un utilisateur soit connecté.
- Applications qui ont un utilisateur connecté, mais qui appellent également Microsoft Graph avec leur propre identité. Par exemple, pour utiliser des fonctionnalités qui nécessitent plus de privilèges élevés que l’utilisateur.
Dans cet article, l’application a utilisé une clé secrète client comme informations d’identification. Vous pouvez éventuellement configurer un certificat ou des informations d’identification d’identité fédérée.
Pour plus d’informations sur les applications qui appellent Microsoft Graph sous leur propre identité et utilisent le flux d’informations d’identification du client, consultez Flux d’authentification et scénarios d’application : application démon qui appelle une API web dans le nom du démon.
Utiliser la bibliothèque d’authentification Microsoft (MSAL)
Dans cet article, vous avez parcouru les détails du protocole de bas niveau généralement requis uniquement lors de la création manuelle et de l’émission de requêtes HTTP brutes pour exécuter le flux d’informations d’identification du client. Dans les applications de production, utilisez une bibliothèque d’authentification intégrée ou prise en charge par Microsoft, telle que la bibliothèque d’authentification Microsoft (MSAL), pour obtenir des jetons de sécurité et appeler des API web protégées telles que Microsoft Graph.
MSAL et d’autres bibliothèques d’authentification prises en charge simplifient le processus en gérant des détails tels que la validation, la gestion des cookies, la mise en cache des jetons et les connexions sécurisées, ce qui vous permet de vous concentrer sur les fonctionnalités de votre application.
Microsoft a créé et gère un large éventail d’exemples de code qui illustrent l’utilisation des bibliothèques d’authentification prises en charge avec les Plateforme d'identités Microsoft. Pour accéder à ces exemples de code, consultez les exemples de code Plateforme d'identités Microsoft.
Contenu connexe
- Choisissez parmi des exemples de code générés et gérés par Microsoft pour exécuter des applications personnalisées qui utilisent des bibliothèques d’authentification prises en charge, connectez des utilisateurs et appelez Microsoft Graph. Consultez les didacticiels Microsoft Graph.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour