Autorisation et connexion pour OneDrive dans Microsoft Graph
Pour utiliser l’API OneDrive via Microsoft Graph, vous devez disposer d’un jeton d’accès qui procure à l’application un ensemble d’autorisations spécifique pour un utilisateur. Dans cette section, vous allez découvrir comment :
- Enregistrer votre application pour obtenir un ID d’application.
- Connectez votre utilisateur avec les étendues spécifiées à l’aide du flux de jeton ou du flux de code.
- Déconnectez l’utilisateur (facultatif).
L’API OneDrive utilise le schéma d’autorisation standard OAuth 2.0 pour autoriser les applications et générer des jetons d’accès. Vous devez fournir un jeton d’accès pour chaque appel d’API authentifié à l’aide d’un en-tête HTTP :
Authorization: bearer {token}
Remarque : Le schéma d’autorisation recommandé consiste à utiliser le point de terminaison Azure AD v2.0. Toutefois, dans certains cas, il est nécessaire d’utiliser le point de terminaison Azure AD d’origine. Pour plus d’informations, consultez la rubrique Authentification d’application avec Microsoft Graph.
Inscrire votre application
La première étape consiste à enregistrer une application auprès de Microsoft et de fournir des informations détaillées sur l’application. Vous pouvez inscrire votre application et recevoir un nouvel ID d’application à partir de la page d’inscriptions Azure App.
Pour plus d’informations sur la façon d’enregistrer votre application, consultez la rubrique Enregistrement de votre application pour l’API OneDrive.
Connecter des utilisateurs
Votre application doit démarrer le processus de connexion en contactant le point de terminaison de l’autorisation Azure Active Directory avec une étendue spécifiée. Le flux suit les flux d’autorisation OAuth 2.0 standard et requiert des appels d’un navigateur web ou d’un contrôle de navigateur web. Le résultat du flux d’autorisation renvoie un jeton d’accès et éventuellement d’autres jetons que votre application peut utiliser pour accéder à l’API.
Domaines d’authentification
Les étendues déterminent le type d’accès accordé à l’application lorsque l’utilisateur est connecté. Toutes les étendues prennent en charge l’authentification unique sur le web, ce qui signifie que si un utilisateur est déjà connecté à OneDrive, il peut alors ignorer le flux d’authentification et accéder directement au flux d’autorisation.
| Nom de l’étendue | Description |
|---|---|
| offline_access | Permet à votre application de travailler hors connexion, même lorsque l’utilisateur n’est pas actif. Nécessite l’utilisation du flux de code. |
| files.read | Donne une autorisation de lecture pour tous les fichiers OneDrive d’un utilisateur. |
| files.read.all | Donne une autorisation de lecture seule pour tous les fichiers OneDrive d’un utilisateur, y compris les fichiers partagés avec l’utilisateur. |
| files.readwrite | Donne une autorisation de lecture et d’écriture pour tous les fichiers OneDrive d’un utilisateur. |
| files.readwrite.all | Donne une autorisation de lecture et d’écriture pour tous les fichiers OneDrive d’un utilisateur, y compris les fichiers partagés avec l’utilisateur. |
Par exemple, une application classique peut demander les étendues suivantes :
files.readwrite offline_access
Flux d’authentification pris en charge
Azure Active Directory prend en charge plusieurs flux d’autorisation, dont les deux plus courants sont les suivants :
Flux de jeton
Le flux d’autorisation le plus simple est le flux de jeton. Ce flux est utile pour obtenir rapidement un jeton d’accès pour utiliser l’API OneDrive de façon interactive. Ce flux ne fournit pas de jeton d’actualisation et, par conséquent, ne convient pas pour un accès aux ressources sur le long terme.
Pour démarrer le processus de connexion avec le flux de jeton, utilisez un contrôle de navigateur web ou un navigateur web afin de charger une demande d’URL.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
&response_type=token&redirect_uri={redirect_uri}
Paramètres de chaîne de requête requis
| Nom du paramètre | Valeur | Description |
|---|---|---|
| client_id | chaîne | Valeur de l’ID client créé pour votre application. |
| redirect_uri | chaîne | URL de redirection vers laquelle est renvoyé le navigateur à la fin de l’authentification. |
| response_type | chaîne | Type de réponse prévu dans le flux d’autorisation. Pour ce flux, la valeur doit être token. |
| scope | chaîne | Liste des étendues requises par votre application, séparées par des espaces. |
Réponse
Suite à l’authentification et à l’autorisation de votre application, le navigateur web est redirigé vers l’URL de redirection fournie avec les paramètres supplémentaires ajoutés à l’URL.
https://myapp.com/auth-redirect#access_token=EwC...EB
&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
&scope=onedrive.readwrite&user_id=3626...1d
Les valeurs access_token, authentication_token et user_id sont tronquées dans l’exemple précédent. Les valeurs access_token et authentication_token sont très longues.
Vous pouvez utiliser la valeur access_token pour soumettre des demandes à Microsoft Graph.
Flux de code
Le flux de code pour l’authentification est un processus en trois étapes avec des appels distincts pour authentifier et autoriser l’application, ainsi que pour générer un jeton d’accès pour utiliser l’API OneDrive. Cela permet également à votre application de recevoir un jeton d’actualisation qui permet une utilisation sur le long terme de l’API dans certains scénarios, et ainsi d’autoriser l’accès lorsque l’utilisateur n’utilise pas votre application de manière active.
Étape 1. Obtention d’un code d’autorisation
Pour démarrer le processus de connexion avec le flux de code, utilisez un contrôle de navigateur web ou un navigateur web pour charger cette demande d’URL.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
&response_type=code&redirect_uri={redirect_uri}
Paramètres de chaîne de requête requis
| Nom du paramètre | Valeur | Description |
|---|---|---|
| client_id | chaîne | ID client créé pour votre application. |
| scope | chaîne | Liste d’étendues à séparateur espace requis par votre application. |
| redirect_uri | chaîne | URL de redirection vers laquelle est renvoyé le navigateur à la fin de l’authentification. |
| response_type | chaîne | Type de réponse prévu dans le flux d’autorisation. Pour ce flux, la valeur doit être code. |
Réponse
Suite à l’authentification et à l’autorisation de votre application, le navigateur web est redirigé vers votre URL de redirection avec les paramètres supplémentaires ajoutés à l’URL.
https://myapp.com/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c
Étape 2. Échange du code contre les jetons d’accès
Une fois que vous avez reçu la valeur code, vous pouvez échanger ce code contre un ensemble de jetons qui vous permettent de vous authentifier auprès de l’API OneDrive.
Pour échanger le code, soumettez la demande suivante :
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code
Paramètres du corps de la demande requis
Le corps de la demande est une chaîne d’URL correctement codée, avec certains paramètres nécessaires.
| Nom du paramètre | Valeur | Description |
|---|---|---|
| client_id | chaîne | Valeur de l’ID client créé pour votre application. |
| redirect_uri | chaîne | URL de redirection vers laquelle est renvoyé le navigateur à la fin de l’authentification. Celle-ci doit correspondre à la valeur redirect_uri utilisée dans la première demande. |
| client_secret | chaîne | Clé secrète client créée pour votre application. |
| code | chaîne | Code d’autorisation que vous avez reçu dans la première demande d’authentification. |
Note Pour les applications web, la partie domaine de l’URI de redirection doit correspondre à la partie domaine de l’URI de redirection que vous avez spécifiée dans le Centre de développement Microsoft.
Réponse
Si l’appel est réussi, la réponse à la requête POST contient une chaîne JSON qui inclut plusieurs propriétés, notamment access_token, token_type et refresh_token (si vous avez demandé l’étendue wl.offline_access).
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Vous pouvez désormais enregistrer et utiliser le access_token fourni pour soumettre des demandes authentifiées à Microsoft Graph.
Important : utilisez les valeurs access_token et refresh_token dans cette réponse comme vous le feriez avec un mot de passe.
Le jeton d’accès est valide uniquement pour le délai en secondes spécifié dans la propriété expires_in. Vous pouvez demander un nouveau jeton d’accès à l’aide du jeton d’actualisation (le cas échéant) ou en répétant la demande d’authentification depuis le début.
Étape 3. Obtenez un nouveau jeton d’accès ou un jeton d’actualisation.
Si votre application a demandé l’étendue offline_access, cette étape renvoie un jeton refresh_token qui peut être utilisé pour générer des jetons d’accès supplémentaires une fois que le jeton initial a expiré.
Pour échanger le jeton d’actualisation contre un nouveau jeton d’accès, soumettez la demande suivante :
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token
Paramètres du corps de la demande requis
Le corps de la demande est une chaîne d’URL correctement codée, avec certains paramètres nécessaires.
| Nom du paramètre | Valeur | Description |
|---|---|---|
| client_id | chaîne | ID client créé pour votre application. |
| redirect_uri | chaîne | URL de redirection vers laquelle est renvoyé le navigateur à la fin de l’authentification. Celle-ci doit correspondre à la valeur redirect_uri utilisée dans la première demande. |
| client_secret | chaîne | Clé secrète client créée pour votre application. |
| refresh_token | chaîne | Jeton d’actualisation que vous avez reçu précédemment. |
Note Pour les applications web, la partie domaine de l’URI de redirection doit correspondre à la partie domaine de l’URI de redirection que vous avez spécifiée dans le Centre de développement Microsoft.
Réponse
Si l’appel est réussi, la réponse à la requête POST contient une chaîne JSON qui comprend plusieurs propriétés, notamment access_token, authentication_token et refresh_token si vous avez demandé l’étendue offline_access.
{
"token_type":"bearer",
"expires_in": 3600,
"scope": "wl.basic onedrive.readwrite wl.offline_access",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Vous pouvez désormais enregistrer et utiliser le access_token pour soumettre des demandes authentifiées à Microsoft Graph.
Important : utilisez les valeurs access_token et refresh_token dans cette réponse comme vous le feriez avec un mot de passe.
Le jeton d’accès est valide uniquement pour le délai en secondes spécifié dans la propriété expires_in. Vous pouvez demander un nouveau jeton d’accès à l’aide du jeton d’actualisation (le cas échéant) ou en répétant la demande d’authentification depuis le début.
Déconnexion de l’utilisateur
Pour déconnecter un utilisateur, procédez comme suit :
- Supprimez les valeurs
access_tokenourefresh_tokenmises en cache que vous avez reçues précédemment du flux OAuth. - Effectuez toutes les actions de déconnexion nécessaires dans votre application (par exemple, nettoyage de l’état local, suppression des éléments mis en cache, etc..).
- Appelez le service web d’autorisation à l’aide de cette URL :
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}
Cet appel supprime tous les cookies qui permettent l’authentification unique et garantit que lorsque votre application lance le flux d’autorisation la fois suivante, l’utilisateur doit se connecter à nouveau. Grâce à cette déconnexion, le flux ne révoque aucun contenu précédemment accordé à une application.
Paramètres de chaîne de requête requis
| Nom du paramètre | Valeur | Description |
|---|---|---|
| redirect_uri | chaîne | URL de redirection vers laquelle est renvoyé le navigateur à la fin de l’authentification. Doit correspondre exactement à la valeur redirect_uri utilisée dans la demande d’obtention de jeton. |
Après avoir supprimé le cookie, le navigateur est redirigé vers l’URL de redirection que vous avez fournie. Lorsque le navigateur charge votre page de redirection, aucun paramètre de chaîne de requête d’authentification n’est défini et vous pouvez en déduire que l’utilisateur a été déconnecté.
Refus d’accès
Les utilisateurs du compte Microsoft peuvent refuser l’accès d’une application à leur compte en accédant à la page d’autorisation de gestion du compte Microsoft.
Lorsque l’autorisation est refusée pour une application, tout jeton d’actualisation fourni précédemment à votre application n’est plus valide. Vous devez répéter le flux d’authentification pour demander un nouvel accès, puis actualiser le jeton de A à Z.
Voir aussi
Les rubriques suivantes contiennent des aperçus généraux d’autres concepts qui s’appliquent à l’API OneDrive.