Authentification et connexion sur OneDrive
Utiliser Microsoft Graph
Cette rubrique contient des informations sur l’autorisation d’une application à l’aide de comptes Microsoft pour Onedrive personnel. Toutefois, cette méthode n’est plus recommandée. Les nouvelles applications doivent être développées à l’aide de Microsoft Graph et doivent suivre le processus d’autorisation inclus dans Autorisation et connexion pour OneDrive dans Microsoft Graph.
Prise en main
Pour utiliser l’API OneDrive, vous devez disposer d’un jeton d’accès qui authentifie votre application auprès d’un ensemble d’autorisations spécifique pour un utilisateur. Dans cette section, vous allez découvrir comment :
- Inscrire votre application pour obtenir un ID client et un code secret client.
- Connecter votre utilisateur à OneDrive avec les étendues spécifiées à l’aide du flux de jeton ou du flux de code.
- Déconnecter l’utilisateur (facultatif).
L’API OneDrive utilise le schéma d’authentification standard OAuth 2.0 pour authentifier les utilisateurs et générer des jetons d’accès. Vous devez fournir un jeton d’accès pour chaque appel de l’API via l’une des opérations suivantes.
- En-tête HTTP :
Authorization: bearer {token}
Inscrire votre application
Pour authentifier votre application, vous devez inscrire votre application auprès de Microsoft et fournir des informations détaillées sur l’application.
Pour inscrire votre application
Consultez la rubrique sur Enregistrement de votre application pour l’API OneDrive pour plus d’informations sur l’inscription de votre application.
Connecter des utilisateurs
Pour démarrer le processus de connexion de votre application, vous devez contacter le service web d’autorisation des comptes Microsoft avec une étendue spécifiée et recevoir un jeton d’accès. Le flux suit les flux d’authentification OAuth 2.0 standard et requiert des appels d’un navigateur web ou d’un contrôle de navigateur web.
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 | Obligatoire |
|---|---|---|
| offline_access | Permet à votre application de fonctionner hors connexion, même lorsque l’utilisateur n’est pas actif. Fournit à votre application un objet refresh_token qui peut être utilisé pour générer des jetons accès supplémentaires si nécessaire. Cette étendue n’est pas disponible pour le flux de jeton. | Non |
| onedrive.readonly | Donne une autorisation de lecture seule pour tous les fichiers OneDrive d’un utilisateur, y compris les fichiers partagés avec l’utilisateur. | Oui |
| onedrive.readwrite | 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. Cette étendue est obligatoire pour créer des liens de partage. | Oui |
| onedrive.appfolder | Donne une autorisation de lecture et d’écriture sur un dossier spécifique de votre application. | Oui |
Par exemple, une application classique peut demander les étendues suivantes :
onedrive.readwrite offline_access
Flux d’authentification pris en charge
Deux flux d’authentification sont pris en charge :
Flux de jeton
Le flux de jeton est le flux d’authentification le plus simple. Ce flux est utile pour obtenir rapidement un jeton d’accès pour utiliser l’API OneDrive de façon interactive. Ce flux n’offre pas de jeton d’actualisation et ne peut donc pas être utilisé pour l’accès à long terme à l’API OneDrive.
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.live.com/oauth20_authorize.srf?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. |
Utilisez cette URL de redirection pour les applications mobiles et de bureau https://login.live.com/oauth20_desktop.srf.
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://login.live.com/oauth20_authorize.srf#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 à l’API OneDrive.
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.live.com/oauth20_authorize.srf?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://login.live.com/oauth20_authorize.srf?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.live.com/oauth20_token.srf
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é dans le Centre de développement du compte 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 à l’API OneDrive.
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é un accès à wl.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.live.com/oauth20_token.srf
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é dans le site de gestion des applications Kit de développement logiciel (SDK) Live.
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, authentication_token et refresh_token si vous avez demandé l’étendue wl.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 à l’API OneDrive.
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.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}
Cet appel supprime tous les cookies qui permettent l’authentification unique et garantit que lorsque votre application lance l’environnement de connexion la fois suivante, l’utilisateur sera invité à entrer un nom d’utilisateur et un mot de passe pour continuer.
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. 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 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 votre 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.
Erreurs
En cas d’erreur d’authentification, le navigateur web est redirigé vers une page d’erreur. Alors que la page d’erreur affiche toujours un message convivial, l’URL de la page d’erreur inclut des informations supplémentaires qui peuvent vous aider à procéder au débogage. Ces informations ne s’affichent pas toujours dans le contenu de la page d’erreur du navigateur.
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}
L’URL inclut les paramètres de la requête que vous pouvez utiliser pour analyser l’erreur et y répondre en conséquence. Ces paramètres sont toujours inclus sous la forme d’un signet (après le caractère #). Le contenu de la page affiche toujours un message d’erreur générique pour l’utilisateur.
Si l’utilisateur choisit de ne pas fournir d’autorisation à votre application, le flux est redirigé vers votre URI de redirection et inclut les mêmes paramètres d’erreur.
Paramètres d’erreur
| Nom du paramètre | Valeur | Description |
|---|---|---|
| error | chaîne | Code d’erreur identifiant l’erreur qui s’est produite. |
| error_description | chaîne | Description de l’erreur. |
Rubriques connexes
Les rubriques suivantes contiennent des aperçus généraux d’autres concepts qui s’appliquent à l’API OneDrive.