Table of contents
TOC
Réduire la table des matières
Développer la table des matières
Dernière mise à jour: 20/06/2018

Authentification OneNote et autorisations de l’application Azure AD

S'applique aux : bloc-notes d'entreprise sur Office 365

Authentification avec Azure AD (applications d'entreprise)

  1. Enregistrez votre application et obtenez un identifiant client et un secret
  2. Choisissez les étendues d'autorisation d'application OneNote
  3. Obtenir le consentement de l'administrateur
  4. Obtenir un code d’accès
  5. Obtenir un nouveau code d'accès après l'expiration du précédent

Enregistrez votre application et obtenez un identifiant client et un secret (applications d'entreprise)

Voir la section Enregistrez votre application et obtenez 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 les étapes ci-dessous pour attribuer des autorisations d’application OneNote à votre application :

  1. Dans le Portail de gestion Azure, dans la section Autorisations pour d'autres applications de la page de configuration de l'application, choisissez Ajouter une application.

  2. Choisissez l’application OneNote, puis cliquez sur la coche dans le coin inférieur droit. Si OneNote n’est pas répertorié, assurez-vous d'avoir OneDrive for Business pour votre locataire.

  3. 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 AzureDescription
Notes.Read.AllAfficher les notes pour tous les utilisateursPermet à 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.AllAfficher et modifier les notes pour tous les utilisateursPermet à 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.

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 signer 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 AAD assigned application id

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Vous pouvez également essayer la demande ci-dessus dans un navigateur, tapez l'URL suivante dans la barre d'adresse de votre navigateur (construisez une URL valide en suivant les instructions ci-après).

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your AAD assigned application id

https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=http://localhost/myapp/permissions

Le tableau ci-dessous décrit les paramètres utilisés dans la demande ci-dessus:

ParamètreConditionDescription
clientObligatoireLe client du répertoire dont vous souhaitez demander l'autorisation. Cela peut être dans GUID ou un format de nom convivial. Si vous ne connaissez pas le locataire auquel l'utilisateur appartient et que vous souhaitez le laisser se connecter avec un locataire, utilisez commun.
client_idObligatoireID d’application que le portail d’enregistrement de l’application a affecté à votre application.
redirect_uriObligatoireURI 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.
étatRecommandé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 réussie

Si l’administrateur approuve les autorisations relatives à votre application, la réponse réussie ressemble à ceci :

GET https://login.microsoftonline.com/{tenant}/Consent/Grant

Le tableau ci-dessous décrit les valeurs renvoyées dans la réponse ci-dessus:

ParamètreDescription
clientClient du répertoire ayant accordé à votre application les autorisations demandées au format GUID.

Réponse d’erreur

Si l'administrateur n'approuve pas les autorisations pour votre application, la réponse échouée 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. 

Le tableau ci-dessous décrit les valeurs renvoyées dans la réponse ci-dessus:

ParamètreDescription
clientClient 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

  1. Le consentement de l'administrateur est une étape unique pour un locataire spécifique
  2. Si vous souhaitez que votre application s'exécute dans d'autres locataires, vous devez la configurer en tant qu'application multi-locataires dans AAD.
  3. Que l'application soit en cours d'exécution chez son propre locataire ou chez un autre locataire, le consentement de l'administrateur est une étape obligatoire
  4. Votre application est autorisée à choisir des autorisations de délégué 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 codes d'accès pour les API. Pour obtenir un jeton en se servant de l'aide de 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 AAD assigned application id
// Replace {app_secret} with an AAD 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

Le tableau ci-dessous décrit les paramètres utilisés dans la demande ci-dessus:

ParamètreConditionDescription
Type-de donObligatoireDoit être client_credentials.
client_idObligatoireID d’application que le portail d’enregistrement de l’application a affecté à votre application.
client_secretObligatoireClé 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
ressourceObligatoireLa 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 informe le point de terminaison de code que, parmi toutes les autorisations d'application directe que vous avez configurées pour votre application, elle doit émettre un code pour celles associées à la ressource que vous souhaitez utiliser.

Réponse réussie

Une réponse correcte se présente comme suit :

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "resource": "https:\/\/onenote.com\/",
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

Le tableau ci-dessous décrit les valeurs renvoyées dans la réponse ci-dessus:

ParamètreDescription
type-de codeIndique la valeur du type de jeton. Le seul type pris en charge par Azure AD est bearer.
expires_inValidité du code d’accès (en secondes).
resourceL'identificateur de ressource (ID d'application URI) de la ressource sur laquelle ce code peut être utilisé.
access_tokenLe 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 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"
}

Le tableau ci-dessous décrit les valeurs renvoyées dans la réponse ci-dessus:

ParamètreDescription
errorChaî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_descriptionUn message d'erreur spécifique qui pourrait vous aider à identifier la cause première d'une erreur d'authentification.
erreur_codesUne liste de codes d'erreur spécifiques à STS pouvant aider au diagnostic.
cachettempsL'heure à laquelle l'erreur s'est produite.
tracer_idUn identifiant unique pour la demande qui pourrait aider avec les diagnostics.
correlation_idUn identifiant unique pour la demande qui pourrait aider avec les diagnostics entre les composants.

Inclure le code d'accès dans votre demande à l'API OneNote

Toutes vos demandes à l'API OneNote doivent envoyer le code d'accès en tant que code de support dans le Autorisation entête. Par exemple, la requête 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 codes frais 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.

Ressources supplémentaires

© 2018 Microsoft