Authentification et connexion de OneDrive Entreprise

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.

Utilisation d’Azure Active Directory pour l’authentification

Pour utiliser l’API OneDrive avec OneDrive Entreprise, 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.

L’obtention d’une application configurée pour accéder à OneDrive Entreprise est un véritable défi. Nous travaillons actuellement sur la facilitation de ce processus. Nous vous remercions de votre patience.

Dans cette section, vous allez découvrir comment :

1. Enregistrer votre application avec Azure Active Directory.
2. Se connecter à OneDrive Entreprise

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. Fournissez un jeton d’accès pour chaque appel d’API via un en-tête HTTP :

Authorization: bearer {token}

Accédez à l’API en envoyant des requêtes HTTP à une URL de point de terminaison spécifique. L’URL racine est basée sur le nom d’hôte du serveur qui sert de point de terminaison REST. Vous pouvez utiliser l’API de découverte pour rechercher les points de terminaison des services Office 365. Pour plus d’informations, consultez la rubrique Tâches courantes de découverte du point de terminaison à l’aide de l’API du service de découverte. Votre URL racine apparaît dans l’exemple suivant, où {tenant} est issu de l’URL de votre point de terminaison découvert :

https://{tenant}-my.sharepoint.com/_api/v2.0/

Enregistrer votre application avec Azure Active Directory

Avant de vous connecter, vous devez enregistrer votre application auprès d’Azure Active Directory et définir les autorisations requises par votre application. Pour plus d’informations, consultez la rubrique Enregistrer votre application pour SharePoint Server 2016 ou OneDrive Entreprise.

Connexion à OneDrive Entreprise

Lors de votre première connexion à OneDrive Entreprise, votre application a besoin des valeurs suivantes :

• L’ID client et la clé (clé secrète client) enregistrés avec Azure Active Directory (AAD)
• Le code d’autorisation envoyé par le flux du code d’autorisation OAuth 2
• L’URL du point de terminaison de l’API OneDrive Entreprise
• Le jeton d’accès pour la ressource OneDrive Entreprise
• Actualisez le jeton pour générer des jetons d’accès supplémentaires lors de l’expiration du jeton en cours.

Les étapes suivantes vous mèneront aux demandes nécessaires pour obtenir toutes ces valeurs.

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. Consultez la rubrique Présentation des concepts d’authentification de l’application Office 365 pour des informations générales sur l’authentification d’Office 365. Toutefois, vous devrez exécuter quelques étapes supplémentaires pour obtenir toutes les valeurs requises pour utiliser l’API OneDrive Entreprise.

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. Ce processus crée et envoie un jeton d’actualisation à votre application. Avec le jeton d’actualisation, une utilisation à long terme de l’API est possible lorsque l’utilisateur n’utilise pas activement votre application.

Chaque jeton d’accès généré par Azure Active Directory est propre à une seule ressource. Pour découvrir le point de terminaison de l’API OneDrive Entreprise et pour appeler ce point de terminaison, vous avez besoin de deux jetons d’accès, un pour chaque point de terminaison de l’API (ressource).

Un jeton unique d’actualisation peut être utilisé pour générer des jetons d’accès pour n’importe quel point de terminaison auquel votre application est autorisée à accéder.

Étape 1. Connexion et obtention d’un code d’autorisation

Pour commencer, votre application charge le point de terminaison courant Azure Active Directory OAuth 2 dans un navigateur web qui invite l’utilisateur à se connecter avec ses informations d’identification. Cette URL utilise le point de terminaison courant du client. Elle est valide pour toutes les applications.

GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}

Paramètres de chaîne de requête requis

Remarque L’URI de redirection doit correspondre à l’un des URI de redirection que vous avez spécifié dans le portail de gestion Azure.

Réponse

Lorsque l’utilisateur s’est authentifié avec succès et que votre application a reçu son autorisation, comme illustré dans l’exemple suivant, le navigateur web est redirigé vers votre URL de redirection avec des paramètres supplémentaires ajoutés à l’URL.

https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...

La valeur de chaîne de requête du code est le code d’autorisation dont vous aurez besoin à l’étape suivante.

Étape 2. Échange du code d’autorisation pour les jetons

Une fois que vous avez reçu la valeur du code, vous pouvez échanger ce code contre un ensemble de jetons qui vous permettent de vous authentifier auprès de différentes API Office 365. Pour échanger le code, soumettez une demande au point de terminaison du jeton pour Azure Active Directory, comme dans l’exemple :

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

Le corps pour cette demande est une chaîne codée au format URL, avec les paramètres obligatoires suivants :

Dans la plupart des cas, l’URL du point de terminaison de l’API OneDrive Entreprise n’est pas connue. Pour découvrir l’URL du point de terminaison, vous devez appeler l’API de découverte Office 365. Pour vous authentifier aupès de l’API de découverte, vous devez demander un jeton d’accès pour la ressource https://api.office.com/discovery/. Veillez à inclure le caractère de fin /. Dans le cas contraire, votre application ne pourra pas accéder à l’API de découverte.

Réponse

Si l’appel est réussi, le corps de la réponse est une chaîne JSON qui inclut les propriétés access_token, expires_in et refresh_token.

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

Remarque : La réponse peut contenir des propriétés supplémentaires. Ces propriétés ne sont pas requises pour utiliser les API.

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, ou en répétant la demande d’authentification du début.

Étape 3. Découvrir l’URI de la ressource OneDrive Entreprise

Étant donné que différents clients et utilisateurs utilisent une URL différente pour fournir un accès à l’API, votre application aura besoin de découvrir l’URL du OneDrive Entreprise de l’utilisateur connecté. Pour ce faire, votre application peut utiliser l’API de découverte Office 365 afin de demander une liste des services et des points de terminaison de l’API disponibles pour votre application et l’utilisateur connecté.

À l’aide d’un jeton d’accès reçu pour la ressource https://api.office.com/discovery/, vous pouvez soumettre une demande à l’API de découverte pour connaître les services disponibles :

GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}

Réponse

Si l’appel est réussi, le corps de la réponse contient des données JSON avec des informations sur les services disponibles pour l’utilisateur et votre application. Vous pouvez analyser cette réponse pour rechercher l’URL du point de terminaison de l’API OneDrive Entreprise.

{
  "@odata.context": "https:\/\/api.office.com\/discovery\/v1.0\/me\/$metadata#allServices",
  "value": [
    {
      "@odata.type": "#Microsoft.DiscoveryServices.ServiceInfo",
      "capability": "MyFiles",
      "serviceApiVersion": "v2.0",
      "serviceEndpointUri": "https:\/\/contoso-my.sharepoint.com\/_api\/v2.0",
      "serviceResourceId": "https:\/\/contoso-my.sharepoint.com\/"
    }
  ]
}

Remarque : Les autres propriétés seront renvoyées sur l’objet ServiceInfo. Cet exemple est tronqué aux propriétés clés.

Pour rechercher l’URL du point de terminaison pour OneDrive Entreprise, recherchez également l’objet ServiceInfo dans la collection value qui correspond au prédicat suivant :

capability = "MyFiles" AND serviceApiVersion = "v2.0"

Lorsque votre application trouve un objet ServiceInfo correspondant pour OneDrive Entreprise, vous devez enregistrer la valeur des deux propriétés de cet objet : serviceResourceId et serviceEndpointUri. Ces valeurs seront utilisées à l’étape suivante pour fournir un nouveau jeton d’accès et effectuer des appels d’API OneDrive.

Étape 4. Échange d’un jeton d’actualisation contre un jeton d’accès pour appeler l’API OneDrive

Maintenant que votre application connaît la ressource et l’URL du point de terminaison pour OneDrive Entreprise, elle peut échanger le jeton d’actualisation reçu à l’étape 2 contre un jeton d’accès qui peut être utilisé avec l’API OneDrive.

Pour échanger le jeton d’actualisation contre un nouveau jeton d’accès, soumettez la demande suivante :

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

Le corps de la demande est une chaîne codée au format URL, avec les paramètres suivants :

Note L’URI de redirection doit correspondre à l’URI de redirection que vous avez spécifié dans le portail de gestion Azure.

Réponse

Si l’appel est réussi, le corps de la réponse est une chaîne JSON qui inclut access_token, expires_in et refresh_token.

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

Remarque : Remplacez les valeurs du jeton d’actualisation que vous avez précédemment enregistrées par celles renvoyées par les appels ultérieurs au service d’émission de jeton pour vous assurer que votre application dispose d’un jeton avec la dernière date d’expiration.

La valeur de la propriété access_token peut désormais être utilisée pour soumettre des demandes authentifiées à l’API OneDrive. Pour plus d’informations sur les jetons d’actualisation, consultez la rubrique Actualiser des jetons pour plusieurs ressources.

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 (généralement 1 heure). 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.

Si le jeton d’accès arrive à expiration, les demandes soumises à l’API renvoient une réponse 401 Unauthorized. Si vous recevez cette réponse à une demande authentifiée, vous devez générer un nouveau jeton d’accès à l’aide de votre jeton d’actualisation enregistré.

Étape 5. Demande à l’API OneDrive

Maintenant que votre application dispose d’un jeton d’accès valide pour le point de terminaison de l’API OneDrive Entreprise de l’utilisateur, elle peut effectuer une demande authentifiée à l’API OneDrive.
Pour ce faire, vous devez utiliser la valeur serviceEndpointUri extraite de l’API de découverte et le jeton d’accès envoyé par le service d’émission de jeton.

Par exemple, pour obtenir les informations relatives au OneDrive Entreprise de l’utilisateur, vous pouvez soumettre une demande de chemin d’accès à l’API /drive :

GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}

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.

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.

Pour plus d’informations sur la gestion des erreurs, consultez la rubrique Gestion des erreurs dans OAuth 2.0.

Voir aussi

Les rubriques suivantes contiennent des aperçus généraux d’autres concepts qui s’appliquent à l’API OneDrive.

• Développer avec l’API OneDrive
• Utilisation d’Azure Active Directory pour l’authentification
• Authentification de OneDrive et connexion à l’aide de comptes Microsoft
• Concepts de l’authentification Office 365
• OAuth 2.0 dans Azure AD
• Flux d’octroi de code d’autorisation