Authentification OneNote et autorisations de l’application Azure AD
S’applique aux : Blocs-notes d’entreprise sur Office 365
Authentification avec Azure AD (applications pour entreprise) :
- Enregistrer votre application et obtenir un identifiant client et un code secret
- Choisir les étendues d’autorisation d’application OneNote
- Obtenir le consentement de l’administrateur
- Obtenir un jeton d’accès
- Obtenir un nouveau jeton d’accès après l’expiration du précédent
Enregistrer votre application et obtenir un identifiant client et un secret (applications d’entreprise)
Voir la section Enregistrer votre application et obtenir un identifiant client et un secret.
Choisissez les étendues d'autorisation d'application OneNote (applications d'entreprise)
Les étendues d'autorisation représentent les niveaux d'accès au contenu OneNote. Une autorisation d'application est accordée à une application par l'administrateur d'une organisation et ne peut être utilisée que pour accéder aux données appartenant à cette organisation et à ses employés. Par exemple, l'API OneNote expose plusieurs autorisations d'application pour effectuer les opérations suivantes:
- Afficher les notes pour tous les utilisateurs
- Afficher et modifier les notes pour tous les utilisateurs
Suivez ces étapes pour attribuer des autorisations d’application OneNote à votre application :
Dans le Portail de gestion Azure, à la section Autorisations pour d’autres applications de la page de configuration de l’application, choisissez Ajouter une application.
Choisissez l’application OneNote, puis cochez sur la case au coin inférieur droit. Si OneNote n’est pas répertorié, assurez-vous d'avoir OneDrive for Business pour votre locataire.
Choisissez le plus bas niveau d’autorisations d'application dont votre application a besoin pour effectuer son travail et enregistrez vos modifications. Vous pouvez demander plusieurs étendues.
Étendues pour les autorisations d’application
Si vous accédez à des ordinateurs portables à l’aide des autorisations d’application, choisissez l’une des étendues suivantes.
| Étendue (entreprise) | Autorisation dans le portail Azure | Description |
|---|---|---|
| Notes.Read.All | Afficher les notes pour tous les utilisateurs | Permet à l’application d’afficher les notes OneNote de tous les utilisateurs de votre organisation, sans utilisateur connecté. L'application ne peut pas créer de nouvelles notes, modifier des notes existantes ou afficher des notes dans des sections protégées par mot de passe. |
| Notes.ReadWrite.All | Afficher et modifier les notes pour tous les utilisateurs | Permet à l’application d’afficher les notes OneNote de tous les utilisateurs de votre organisation, sans utilisateur connecté. L'application ne peut pas accéder aux notes sous des sections protégées par mot de passe. |
Obtenir le consentement de l’administrateur
Recommandé : Connectez l’utilisateur à votre application
Généralement, lorsque vous créez une application qui utilise des autorisations d'application, l'application nécessite une page ou une vue sur laquelle l'administrateur approuve les autorisations de l'application. Cette page peut faire partie du flux de connexion de l'application, des paramètres de l'application, ou peut être un flux de "connexion" dédié. Dans de nombreux cas, il est logique que l'application affiche cette vue "connect" uniquement après qu'un utilisateur s'est connecté à un compte Microsoft professionnel ou scolaire.
Si vous connectez l'utilisateur à votre application, vous pouvez identifier l'organisation à laquelle l'utilisateur appartient avant de demander à l'utilisateur d'approuver les autorisations d'application. Bien que cela ne soit pas strictement nécessaire, il peut vous aider à créer une expérience plus intuitive pour vos utilisateurs. Pour connecter l’utilisateur, suivez notre Didacticiels sur le protocole v2.0.
Demander les autorisations d’un administrateur d’annuaire
Lorsque vous êtes prêt à demander des autorisations à l’administrateur de l’organisation, vous pouvez rediriger l’utilisateur vers le point de terminaison de consentement de l’administrateur. Vous pouvez effectuer l’appel de l’API tel que ci-dessous :
// Line breaks are for legibility only.
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://localhost/myapp/permissions
Vous pouvez également essayer la requête ci-dessus dans un navigateur, tapez l’URL suivante dans la barre d’adresse de votre navigateur (construisez une URL valide en suivant ces instructions).
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions
Ce tableau décrit les paramètres utilisés dans la requête précédente :
| Paramètre | Condition | Description |
|---|---|---|
| client | Obligatoire | Le client de l’annuaire dont vous souhaitez demander l’autorisation. Cela peut être dans GUID ou un format de nom convivial. Si vous ne connaissez pas le client auquel l’utilisateur appartient et que vous souhaitez le laisser se connecter avec un client, utilisez common (commun). |
| client_id | Obligatoire | ID d’application que le portail d’enregistrement de l’application a affecté à votre application. |
| redirect_uri | Obligatoire | URI de redirection où vous souhaitez que la réponse soit envoyée. Doit correspondre exactement à l’un des URI de redirection que vous avez enregistrés dans le portail, sauf qu’il doit être au format URL et qu’il peut avoir des segments de chemin supplémentaires. |
| état | Recommandé | Valeur incluse dans la demande qui est également renvoyée dans la réponse du jeton. Il peut s’agir d’une chaîne de tout contenu de votre choix. L’état est utilisé pour coder les informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, comme la page ou la vue. |
Une fenêtre de consentement d’administration s’affichera, continuez et approuvez.
Réponse en cas de réussite
Si l’administrateur approuve les autorisations relatives à votre application, la réponse en cas de réussite ressemble à ceci :
GET https://login.microsoftonline.com/{tenant}/Consent/Grant
Ce tableau décrit les valeurs renvoyées dans la réponse précédente :
| Paramètre | Description |
|---|---|
| client | Client du répertoire ayant accordé à votre application les autorisations demandées au format GUID. |
Réponse en cas d’erreur
Si l’administrateur n’approuve pas les autorisations pour votre application, la réponse en cas d’erreur ressemble à ceci :
GET https://login.microsoftonline.com/{tenant}/login
Additional technical information:
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988
Timestamp: 2017-01-18 05:36:57Z
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators.
Ce tableau décrit les valeurs renvoyées dans la réponse précédente :
| Paramètre | Description |
|---|---|
| client | Client du répertoire ayant accordé à votre application les autorisations demandées au format GUID. |
Client du répertoire ayant accordé à votre application les autorisations demandées au format GUID. Vous pouvez maintenant demander un jeton pour la ressource que vous souhaitez.
Notes
- Le consentement de l’administrateur est une étape unique pour un client spécifique.
- Si vous souhaitez que votre application s'exécute dans d’autres clients, vous devez la configurer en tant qu’application multi-client dans Azure AD.
- Que l’application soit en cours d’exécution chez son propre client ou chez un autre client, le consentement de l’administrateur est une étape obligatoire
- Votre application est autorisée à choisir des autorisations déléguées en plus des autorisations d’application (mais le consentement de l’administrateur est toujours requis).
Obtenir un jeton d’accès (applications d’entreprise)
Après avoir acquis l’autorisation nécessaire pour votre application, procédez à l’acquisition des jetons d’accès pour les API.
Pour obtenir un jeton en se servant l’autorisation d’informations d’identification du client, envoyez une demande POST comme ci-dessous :
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
// Replace {app_secret} with an Azure AD generated key for your application
POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F
Ce tableau décrit les paramètres utilisés dans la requête précédente :
| Paramètre | Condition | Description |
|---|---|---|
| grant_type | Obligatoire | Doit être client_credentials. |
| client_id | Obligatoire | ID d’application que le portail d’enregistrement de l’application a affecté à votre application. |
| client_secret | Obligatoire | Clé secrète de l’application que vous avez générée pour votre application dans le portail d’enregistrement de l’application. Il est très important que ceci soit encodé en URL |
| resource | Obligatoire | La valeur transmise pour le resource paramètre dans cette requête doit être l'identificateur de ressource (Application ID URI) de la ressource que vous voulez. Pour l'API OneNote, la valeur est https://onenote.com/. Cette valeur indique au point de terminaison de jeton que de toutes les autorisations d’application directes que vous avez configurées pour votre application, il doit émettre un jeton pour celles associées a la ressource que vous souhaitez utiliser. |
Réponse en cas de réussite
Une réponse correcte se présente comme suit :
{
"token_type": "Bearer",
"expires_in": "3600",
"resource": "https:\/\/onenote.com\/",
"access_token": "eyJ0eXAiOiJKV1Qi..."
}
Ce tableau décrit les valeurs utilisées dans la requête précédente :
| Paramètre | Description |
|---|---|
| type-de code | Indique la valeur du type de jeton. Le seul type pris en charge par Azure AD est bearer. |
| expires_in | Validité du jeton d’accès (en secondes). |
| resource | L'identificateur de ressource (ID d'application URI) de la ressource sur laquelle ce code peut être utilisé. |
| access_token | Le jeton d'accès demandé. L’application peut utiliser ce jeton pour s’authentifier auprès de la ressource sécurisée, telle qu’une API Web. |
Réponse en cas d’erreur
Une réponse d’erreur ressemble à ceci (dans cet exemple, une valeur non valide pour client_secret est fournie dans la requête) :
{
"error": "invalid_client",
"error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
"error_codes": [
70002,
50012
],
"timestamp": "2017-01-19 20:34:11Z",
"trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
"correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}
Ce tableau décrit les valeurs utilisées dans la requête précédente :
| Paramètre | Description |
|---|---|
| erreur | Chaîne de code d'erreur que vous pouvez utiliser pour classer les types d'erreurs qui se produisent et pour réagir aux erreurs. |
| error_description | Un message d'erreur spécifique qui pourrait vous aider à identifier la cause première d'une erreur d'authentification. |
| erreur_codes | Une liste de codes d'erreur spécifiques à STS pouvant aider au diagnostic. |
| timestamp | L'heure à laquelle l'erreur s'est produite. |
| tracer_id | Un identifiant unique pour la demande qui pourrait aider avec les diagnostics. |
| correlation_id | Un identifiant unique pour la demande qui pourrait aider avec les diagnostics entre les composants. |
Inclure le code d’accès dans la demande que vous adressez à l’API OneNote
Toutes vos demandes adressées à l’API OneNote doivent envoyer le jeton d’accès sous forme de jeton de support dans l’en-tête d’autorisation. Par exemple, la demande suivante récupère cinq de vos blocs-notes, triés alphabétiquement par nom :
GET https://www.onenote.com/api/v1.0/users/foo@example.com/notes/notebooks?top=5
Authorization: Bearer {access-token}
Les codes d’accès ne sont valides que pour une heure, vous aurez donc besoin de nouveaux codes lorsqu’ils expireront. Vous devriez vérifier l'expiration du jeton avant de l'utiliser et obtenir un nouveau jeton d'accès si nécessaire. Les administrateurs n'ont pas à consentir aux autorisations à nouveau, sauf s'ils révoquent des autorisations.
Obtenir un nouveau code d'accès après son expiration
Si le code d’accès arrive à expiration, les demandes soumises à l’API renvoient une réponse 401 Unauthorized. Votre application doit gérer cette réponse et vérifier l'expiration du code avant d'envoyer des demandes.
Vous pouvez demander un nouveau code d'accès en répétant le processus décrit dans la section Obtenir un code d'accès plus tôt dans ce sujet.
Mettez à jour vos codes stockés pour vous assurer que votre application dispose de codes dont la durée de vie est la plus longue.
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. Les paramètres d'URL sont inclus en tant que signet, par exemple: #error={error_code}&error_description={message}
Si l’administrateur choisit de ne pas fournir de consentement à votre application, le flux redirigera vers votre URL de redirection et inclura les paramètres d’erreur.
Pour des informations détaillées sur la gestion des erreurs, voir Gestion des erreurs dans OAuth 2.0.