Authentification et autorisations OneNote
S’applique aux : Utilisateurs de blocs-notes sur OneDrive | Blocs-notes d’entreprise sur Office 365
OneNote utilise le compte Microsoft (anciennement Live Connect) et l’annuaire Azure AD pour fournir un accès sécurisé aux blocs-notes OneNote. Avant de pouvoir accéder aux blocs-notes, vous devez d’abord vous authentifier à l’aide du compte Microsoft ou Azure AD et obtenir un jeton d’accès.
Le compte Microsoft est utilisé pour accéder aux blocs-notes personnel sur OneDrive et Azure AD est utilisé pour accéder aux blocs-notes d’entreprise sur Office 365.
Les deux services d’autorisation mettent en œuvre le protocoleOAuth 2.0qui fournit des jetons d'accès nécessaires pour interagir avec OneNote. Toutes les demandes adressées à l’API OneNote doivent inclure un jeton d'accès valide dans l’en-tête d'autorisation.
Cet article décrit les processus liés à l'autorisation dont vous êtes responsable : enregistrer votre application pour obtenir un ID client, spécifier les autorisations dont vous avez besoin et appeler le service d'autorisation pour connecter les utilisateurs et obtenir un jeton d'accès.
En fonction de votre plateforme, vous avez la possiblité d'utiliser un kit de développement logiciel (SDK) pour simplifier les flux d'authentification.
Notes
OneNote prendra finalement en charge le modèle d’authentification unique et l’inscription des applications fournis par le modèle d’application v2.0. Surveillez les mises à jour connexes sur le Blog du développeur OneNote.
Essayer les API
Suivez les étapes présentées dans cet article pour savoir comment obtenir un jeton d’accès à l’aide de votre outil de réseau favori, tel que Fiddler.
Authentifiez-vous à l’aide du compte Microsoft (applications personnelles)
- Enregistrez votre application et obtenez un identifiant client et un code secret
- Choisissez les autorisations OneNote
- Ouvrez une session pour les utilisateurs et obtenez un jeton d’accès
- Obtenez un nouveau jeton d’accès après l’expiration du précédent
Enregistrez votre application et obtenez un identifiant client et un code secret (applications clients)
Pour commencer, vous devez inscrire une application avec Microsoft. Ce processus crée un principal de service que vous liez à partir de votre application et qui génère à son tour l’ID client et le secret que vous envoyez au service d’autorisation.
Faites-le si votre application accède uniquement aux blocs-notes personnels ou si elle accède à la fois aux blocs-notes personnels et d’entreprise.
Connectez-vous au Centre de développement de compte Microsoft à l’aide de votre compte Microsoft. (Si vous développez une application Windows Store, faites plutôt ceci.)
Si vous ne possédez pas de compte Microsoft, vous devez en créer un. Vous devez utiliser une adresse e-mail que vous consultez régulièrement. Nous pourrions vous contacter pour faire la promotion de votre application sur notre pageApplications du jourou si nous remarquons un trafic réseau inattendu provenant de votre application. Nous ne vous enverrons pas de messages indésirables ou ne vendrons pas vos informations.
Cliquez sur Créer une application.
Entrez le nom que les utilisateurs doivent voir lorsqu'ils sont invités à accorder des autorisations à votre application, ensuite choisissez la langue principale de votre application.
Si vous acceptez les conditions d’utilisation, ainsi que la politique de confidentialité et de gestion des cookies, cliquez sur J’acceptepour continuer l’inscription.
Sur la page Paramètres de l’API, choisissez votre type d'application et fournissez des informations sur votre application :
Applications Web (applications côté serveur)
a. Choisissez Non pour Application client mobile ou de bureau.
b. Pour le domaine cible, entrez l’URL du service.
c. Entrez l’URL de redirection vers laquelle vous souhaitez rediriger les utilisateurs après leur authentification et leur accès à votre application.
Applications natives (installées sur un périphérique)
a. Choisissez Non pour Application client mobile ou de bureau.
b. (Facultatif) Pour le domaine cible, entrez l’URL du service mobile.
c. (Facultatif) Pour l’URL de redirection, entrez une URL valide. Cela agit comme un identificateur pour votre application et ne doit pas nécessairement être un point de terminaison physique.*
Enregistrez l’ID client et le secret client affichés sur la page Paramètres de l'application et l’URL de redirection si vous en avez fourni une.
Applications Windows Store
Si vous créez une application Windows, vous enregistrerez plutôt votre application sous leCentre de développement Windows. Cela vous fournira l'identité du package (SID du package) que vous utiliserez à la place de l’ID du client.
Connectez-vous au Centre de développement Windows avec votre compte Microsoft.
Sur le tableau de bord, choisissez Créer une nouvelle application et entrez le nom de votre application.
Dans Visual Studio, cliquez avec le bouton droit sur votre projet d'application Windows Store et choisissez Boutique > Application associée à la boutique.
Dans la fenêtre Associer votre application à Windows Store, utilisez votre compte Microsoft pour vous connecter, choisissez votre application, ensuite choisissez Suivant > Associer. Cette procédure rajoutera des informations d'inscription requises par Windows Store au manifeste de l’application.
Pour une application Windows universelle, répétez les deux étapes précédentes pour le projet Windows Phone.
Choisissez les étendues d’autorisation OneNote (applications personnelles)
Les étendues d’autorisation représentent les niveaux d’accès au contenu de OneNote. Vous demandez les autorisations dont votre application a besoin et les utilisateurs accordent ou refusent l’accès lorsqu’ils se connectent à votre application. Les utilisateurs ne peuvent accorder que les autorisations dont ils disposent.
Choisissez le niveau d’autorisations le plus bas dont votre application a besoin pour faire son travail. Vous pouvez demander plusieurs étendues.
| Étendue (grand public) | Description |
|---|---|
| office.onenote_create | Peut afficher une liste des blocs-notes OneNote de l’utilisateur et créer de nouvelles pages, mais ne peut pas afficher ou modifier les pages existantes. Peut énumérer la hiérarchie du bloc-notes de l’utilisateur et créer des pages dans n'importe quel emplacement. |
| office.onenote_update_by_app | Peut créer, consulter et modifier toutes les pages créées par l’application. |
| office.onenote_update | Peut créer, afficher et modifier tout contenu des blocs-notes et pages OneNote de l’utilisateur. |
| office.onenote | Peut afficher les blocs-notes et pages OneNote, mais sans les modifier. |
| wl.signin | Uneétendue de l’autorisation de compte Microsoft. Permet à votre application de tirer parti des fonctionnalités de l’authentification unique. |
| wl.offline_access | Uneétendue de l’autorisation de compte Microsoft. Permet à votre application de recevoir un jeton d’actualisation pour travailler hors ligne, même lorsque l’utilisateur n'est pas actif. Cette étendue n’est pas disponible pour le flux dejeton. |
Pour ce qui est des autorisations utilisées pour accéder aux blocs-notes Office 365, voir Choisir les autorisations OneNote (applications d’entreprise).
Ouvrez une session pour les utilisateurs et obtenez un jeton d’accès (applications grand public)
Votre application lance le processus de connexion en contactant le service d’autorisation. Si les utilisateurs ne sont pas encore connectés ou n’ont pas encore donner leur accord, le service les invite à fournir leurs informations d’identification et à accepter les autorisations demandées par votre application. Si l’authentification et l’autorisation aboutissent, vous recevrez un jeton d’accès que vous incluerez dans vos demandes à l’API OneNote.
Important
Traitez les jetons d’accès et jetons d’actualisation aussi sûrement que vous le feriez avec le mot de passe d’un utilisateur.
Notes
En fonction de votre plateforme, vous avez la possiblité d'utiliser un kit de développement logiciel (SDK) pour simplifier les flux d'authentification.
Choisissez votre flux d’authentification. Les deux sont des flux OAuth 2.0 standard.
| Flux | Description |
|---|---|
| Flux de jeton | Permet d’obtenir un jeton d’accès en un appel. Pratique pour un accès rapide, mais ne fournit aucun jeton d’actualisation pour un accès à long terme. Également appelé flux implicite. |
| Flux de code | Permet d’obtenir un code d'autorisation lors du premier appel et échange le code contre un jeton d'accès au cours du second appel. Lorsqu'il est utilisé avec l’étendue d'autorisationwl.offline-access, votre application reçoit un jeton d’actualisation qui lui accorde un accès à long terme. Aussi appelé le flux du code d’autorisation. |
Ouvrir une session pour les utilisateurs grâce aux flux de jetons
Chargez la demande d’URL suivante dans un navigateur Web ou un contrôle de navigateur Web.
GET https://login.live.com/oauth20_authorize.srf
?response_type=token
&client_id={client_id}
&redirect_uri={redirect_uri}
&scope={scope}
| Paramètre de chaîne de requête requis | Description |
|---|---|
| response_type | Le type de flux d’authentification que vous utilisez. Dans ce cas, un jeton. |
| client_id | ID client créé pour votre application. |
| redirect_uri | L’URL de redirection que vous avez inscrite pour votre application. Les applications mobiles et de bureau pour lesquelles il n’a pas été spécifié qu'on peut utiliser ceci : https://login.live.com/oauth20_desktop.srf |
| étendue | Les étendues requises par votre application. Exemple : office.onenote%20wl.sign-in |
Une fois l’authentification et l’autorisation réussies, le navigateur web se redirige vers votre URL de redirection et ajoute des paramètres d’accès à celle-ci. Les paramètres incluent le jeton_d'accès et le type_de jeton, comme illustré dans l’exemple suivant. Le jeton d’accès est valide uniquement pour un nombre de secondes spécifié dans la propriété expires_in.
https://your-redirect-url
#access_token=EwB4Aq...%3d
&token_type=bearer
&expires_in=3600
&scope=office.onenote wl.signin
&user_id=c519ea026ece84de362cfa77dc0f2348
Ouvrez une session pour les utilisateurs grâce aux flux de code
L'obtention d’un jeton d'accès se fait en deux étapes lorsqu’on utilise le flux de code :
- Authentifiez l’utilisateur et obtenez un code d’autorisation.
- Échangez le code contre un jeton d’accès.
Étape 1. Authentifiez l’utilisateur et obtenez un code d’autorisation. Pour démarrer le processus d’authentification, chargez la demande d’URL suivante dans un navigateur Web ou un contrôle de navigateur Web.
https://login.live.com/oauth20_authorize.srf
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&scope={scope}
| Paramètre de chaîne de requête requis | Description |
|---|---|
| response_type | Le type de flux d’authentification que vous utilisez. Pour ce cas, le code. |
| client_id | ID client créé pour votre application. |
| redirect_uri | L’URL de redirection que vous avez inscrite pour votre application. Les applications mobiles et de bureau pour lesquelles il n’a pas été spécifié qu'on peut utiliser ceci : https://login.live.com/oauth20_desktop.srf |
| étendue | Les étendues requises par votre application. Exemple : office.onenote wl.signin wl.offline_access |
Une fois d’authentification et l’autorisation réussies, le navigateur Web se redirige vers votre URL de redirection à l'aide d’un paramètre code ajouté à l’URL, comme indiqué dans l'exemple suivant. Copiez la valeur de codeà utiliser à l’étape 2. Ce code est valide pour quelques minutes.
https://your-redirect-uri
?code=M57010781-9e8c-e31e-ca0d-46bc104236c4
Étape 2. Échangez le code d'autorisation contre un jeton d'accès et actualisez le jeton. Envoyez la demande HTTP suivante en incluant une chaîne d’URL correctement codée dans le corps du message.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&code={code}
&redirect_uri={redirect-uri}
| Paramètre de corps requis | Description |
|---|---|
| grant_type | Le type d’autorisation de la demande. Pour ce cas, authorization_code. |
| client_id | ID client créé pour votre application. |
| client_secret | Clé secrète client créée pour votre application. |
| code | Le code que vous avez reçu en tant que paramètre d’URL à l’étape précédente. |
| redirect_uri | L’URL de redirection pour votre application. Cela doit correspondre à redirect_uri dans la première demande. |
En cas de succès, la réponse contient une chaîne JSON qui comprend le ** jeton_ d'accès** --et le ** jeton_ d'actualisation** si vous avez demandé l'étendue de ** l'accès_ wl.offline** --comme illustré dans l'exemple suivant. Le jeton d’accès est valide uniquement pour un nombre de secondes spécifié dans la propriété expires_in.
{
"token_type":"bearer",
"expires_in":3600,
"scope":"office.onenote wl.sign-in wl.offline-access",
"access_token":"EwCAAq...wE=",
"refresh_token":"MCvePE...$$",
"user_id":"c519ea026ece84de362cfa77dc0f2348"
}
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/me/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 la date d’expiration du jeton avant de l’utiliser et obtenir un nouveau jeton d’accès si nécessaire. Les utilisateurs peuvent rester connectés. Ils n’ont plus besoin d’accorder des autorisations à moins qu’ils ne se déconnectent ou révoquent celles-ci.
Obtention d'un nouveau code d’accès après son expiration (applications grand public)
Vous pouvez demander un nouveau jeton d’accès à l’aide du jeton d’actualisation ou en répétant la demande d’authentification effectuée au début.
Lorsque le jeton d’accès expire, les demandes soumises à l’API renvoient une 401 Unauthorized réponse. Votre application doit gérer cette réponse et vérifier la date d’expiration du jeton avant d’envoyer des demandes.
Envoyez la demande HTTP suivante en incluant une chaîne d’URL correctement codée dans le corps du message.
Vous avez reçu un jeton d’actualisation si vous avez demandé l’autorisationwl.offline_accesset utilisé le flux de code.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
| Paramètre de corps requis | Description |
|---|---|
| grant_type | Le type d’autorisation de la demande. Pour ce cas, refresh_token. |
| client_id | ID client créé pour votre application. |
| client_secret | Clé secrète client créée pour votre application. |
| redirect_uri | L’URL de redirection pour votre application. Cela doit correspondre à l’URI de redirectionredirect_uri que vous avez utilisée pour obtenir les jetons. |
| refresh_token | Jeton d’actualisation que vous avez reçu précédemment. |
En cas de succès, la réponse à la demande POST contient une chaîne JSON qui inclut le ** jeton_ d'accès** et le ** jeton_d'actualisation**, comme illustré dans l'exemple suivant.
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"office.onenote wl.sign-in wl.offline-access",
"access_token":"EwB4Aq...wE=",
"refresh_token":"MCVw8k...$$",
"user_id":"c519ea026ece84de362cfa77dc0f2348"
}
Mettez à jour vos codes stockés pour vous assurer que votre application dispose de codes présentant une durée de vie plus longue.
Authentifiez les utilisateurs (applications grand public)
Pour déconnecter un utilisateur, procédez comme suit :
Supprimez tous les jetons d’accès mis en cache ou actualisez les jetons que vous avez reçus ou stockés.
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 :
https://login.live.com/oauth20_logout.srf
?client_id={client_id}
&redirect_uri={redirect_uri}
Cet appel supprime les cookies qui rendent possible l'authentification unique et garantit que l'utilisateur sera invité à se connecter.
| Paramètre de chaîne de requête requis | Description |
|---|---|
| client_id | Valeur de l’ID client créé pour votre application. |
| redirect_uri | L’URL de redirection pour votre application. Cela doit correspondre à l’URI de redirectionredirect_uri que vous avez utilisée pour obtenir les jetons. |
Après avoir supprimé les cookies, le navigateur se redirige vers votre URL de redirection. La page de redirection est chargée sans spécifier aucune option de chaîne de demande d'authentification, ce qui signifie que l'utilisateur a été déconnecté.
Révoquer l'accès
Les utilisateurs peuvent révoquer l’accès d’une application à leur compte en accédant à la page 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 recevrez la réponse suivante si vous essayez d’actualiser le jeton :
{
"error":"invalid_grant",
"error_description":"The request was denied because one or more scopes requested are unauthorized or expired. The user must first sign in and grant the client application access to the requested scope."
}
Vous devrez répéter le flux d’authentification pour demander un nouveau jeton d’accès et actualiser le jeton depuis le début.
Authentification avec Azure AD (applications pour entreprise)
Si votre application utilise des autorisations d’application (par opposition aux autorisations de délégation), veuillez vous reporter à Authentification OneNote et autorisations d’application Azure AD
- Enregistrez votre application et obtenez un identifiant client et un code secret
- Choisissez les autorisations OneNote
- Ouvrez une session pour les utilisateurs et obtenez un jeton d’accès
- Obtenez un nouveau jeton d’accès après l’expiration du précédent
Enregistrez votre application et obtenez un ID client et un code secret (applications d’entreprise)
Pour commencer, vous devez inscrire une application avec Microsoft. Ce processus crée un principal de service que vous liez à partir de votre application et qui génère à son tour l’ID client et le secret que vous envoyez au service d’autorisation.
Faites-le si votre application accède uniquement aux blocs-notes personnels ou si elle accède à la fois aux blocs-notes personnels et d’entreprise.
Pour enregistrer votre application sur un client Azure AD associé à un abonnement Office 365, vous devez :
Obtenir un compte Office 365 avec des autorisations d’administrateur général pour un client Office 365
Vous pouvez essayer ou acheter un abonnement Office 365 Developer, ou souscrire à un plan de qualification.
Mettez en service un client OneDrive entreprise
Cela rend l’application OneNote disponible afin que vous puissiez spécifier les autorisations OneNote. Pour vérifier si OneDrive entreprise est configuré, connectez-vous à OneNote en ligne avec vos informations d'identification Office 365 (utilisez un professionnel ou scolaire tel que
someone@example.comousomeone@example.onmicrosoft.com).Si vous pouvez voir vos blocs-notes cela signifiera que la configuration est terminée. Si vous voyez le message « Désolé, il semble que nous ne soyons pas en mesure de recupérer vos blocs-notes...», choisissez Accéder à mon Compte > Prochain. Lors du chargement de OneDrive entreprise, revenez et actualisez OneNote Online pour terminer l’attribution des privilèges d’accès.
Notes
Les sites personnels de vos utilisateurs doivent être configurés avant que vous ne puissiez accéder à leurs blocs-notes. L’API OneNote tentera d’attribuer des privilèges d’accès automatiquement à leurs sites si nécessaire.
Associez votre abonnement Office 365 à un abonnement Azure
Cela vous permet d’enregistrer et de gérer votre application dans Azure AD. (En savoir plus)
Si vous n’avez pas d'abonnement Azure, appliquez l’option 1 dans la section suivante. Si vous en avez un, choisissez l’option 2.
Important
Vous et vos utilisateurs devez posséder un compte Office 365 et une licence Office 365 valide. Les comptes d’utilisateurs sans licences valides ne pourront pas voir les blocs-notes sur OneNote Online et les appels d’API vers leurs blocs-notes échoueront. Les administrateurs Office 365 peuvent vérifier l’état et attribuer des licences non attribuées.
Notes
Abonnés MSDN : vous pouvez bénéficier d'un abonnement Office 365 Developer gratuit, mais aussi d'économies supplémentaires lorsque vous activez votre avantage Azure. Vérifiez vos avantages sur la Page d’abonnements MSDN.
Associez votre abonnement Azure à votre abonnement Office 365
Option 1 : Souscrivez à un abonnement Azure en utilisant les informations d’identification de l’administrateur pour votre abonnement Office 365. Faites-le si vous n'avez pas d’abonnement Azure. Ce processus associe les abonnements.
Authentifiez-vous sur le portail de gestion Azure avec vos informations d’identification d’administrateur Office 365 (un compte professionnel ou scolaire comme
someone@example.comousomeone@example.onmicrosoft.com).Dans la page Aucun abonnement trouvé, choisissez Inscrivez-vous à Microsoft Azure. La page d’inscription se chargera et affichera quelques informations de votre abonnement Office 365. Ce compte deviendra un administrateur de service pour le nouvel abonnement Azure.
L’expérience d'inscription varie selon que vous disposez d’un abonnement d’essai Office 365 ou d’un abonnement payant :
Si vous disposez d'un abonnement d’essai, entrez vos informations de paiement sur la page Essai gratuit. Vous ne serez pas facturé à moins que vous ne décidiez de passer à un abonnement payant.
Si vous acceptez le contrat d’abonnement, les détails de l’offre et la déclaration de confidentialité, cochez la case et choisissez Acheter. La page Abonnements de votre nouveau compte Azure s'ouvre. Les abonnements d’essai sont alimentés d’un crédit de 200,00 $ qui peut être utilisé pendant les 30 jours. Vous pouvez annuler l’abonnement à partir de cette page à tout moment.
Si vous disposez d’un abonnement payant, complétez vos coordonnées, puis choisissez S’inscrire. Une fois votre abonnement créé, choisissez Commencer à gérer mon servicepour ouvrir le portail de gestion Azure.
Option 2 : Associez un abonnement Azure existant à un abonnement Office 365. Pour ce faire, vous disposez d'un compte Microsoft qui est un administrateur de service ou un co-administrateur pour votre abonnement Azure. Ce processus fait du compte Microsoft un administrateur général du client Office 365.
Authentifiez-vous sur leportail de gestion Azure avec vos informations d’identification de compte Microsoft (telles que
someone@live.com).Dans le tiroir au bas de la page, choisissez Nouveau > Services d’application > Active Directory > Répertoire > Création personnalisée.
Dans la fenêtre Ajouter un répertoire, choisissez Utiliser le répertoire existant pour identifier l’annuaire.
Choisissez Je suis prêt à être déconnecté à présent et cochez la case. Vous serez alors déconnecté du portail.
Connectez-vous à nouveau en utilisant les informations d’identification d’administrateur général pour le client Office 365 que vous souhaitez associer (un compte professionnel ou scolaire
someone@example.comousomeone@example.onmicrosoft.com).Lorsque vous êtes invité à utiliser le répertoire avec Azure, choisissez continuer > Se déconnecter maintenant.
Fermez le navigateur, puis rouvrez le Portail de gestion Azure.
Connectez-vous à nouveau avec vos informations d’identification de compte Microsoft, puis choisissez Active Directory dans le volet de navigation. Votre répertoire Office 365 doit être répertorié dans l’onglet Répertoire.
Enregistrez votre application sur le portail de gestion Azure
|||UNTRANSLATED_CONTENT_START|||Sign in to the Azure Management Portal.|||UNTRANSLATED_CONTENT_END||| Utilisez les informations d’identification d’administrateur pour votre abonnement Azure.
Dans le volet de navigation, choisissez Active Directory.
Choisissez le répertoire dans lequel vous souhaitez enregistrer votre application, puis ouvrez l’onglet Applications.
Dans le tiroir au bas de la page, choisissez Ajouter > Ajouter une application que mon organisation développe.
Entrez un nom convivial pour l’application et choisissez le type d’application :
Application Web ou API Web (applications basées sur un navigateur ou sur un serveur)
a. Choisissez Application Web et/ou API Web.
b. Pour l’URL de connexion, entrez l’URL à laquelle les utilisateurs se connectent et utilisent votre application.
c. Pour l’URI ID d’application, entrez un identificateur unique pour votre application. Cela doit être dans un domaine personnalisé vérifié.
d. Pour l’URL de réponse, entrez l'URL vers laquelle rediriger en réponse à une demande OAuth 2.0. Cela ne doit pas nécessairement être un point de terminaison physique, mais il doit s’agir d'un URI valide.
e. Pour que l’application soit disponible pour les clients Azure externes, choisissez Oui pour signifier que l’application est multi-clients.
Application cliente native (applications installées sur un appareil)
a. Choisissez Application cliente native.
b. Entrez un URI de redirection pour y être redirigé en réponse à une demande OAuth 2.0. Cela ne doit pas nécessairement être un point de terminaison physique, mais il doit s’agir d'un URI valide.
Pour les applications Web, Azure génère à la fois un ID client et un secret (ou clé secrète) d'application. Pour les applications client natives, Azure génère un ID client. Enregistrez ces valeurs.
Voir la Documentation Office 365 pour obtenir des instructions détaillées sur l’inscription d’applications.
Choisissez les étendues d’autorisation d’application OneNote (applications pour entreprise)
Les étendues d’autorisation représentent les niveaux d’accès au contenu de OneNote. Vous demandez les autorisations dont votre application a besoin et les utilisateurs accordent ou refusent l’accès lorsqu’ils se connectent à votre application. Les utilisateurs ne peuvent accorder que les autorisations dont ils disposent.
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 attribué des privilèges d’accès à votre client OneDrive entreprise.
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 des blocs-notes personnels appartenant à l’utilisateur actuel
Si vous êtes travaillezseulementavec des blocs-notes personnels sur OneDrive entreprise, choisissez parmi les étendues suivantes.
| Étendue (entreprise) | Autorisation dans le portail Azure | Description |
|---|---|---|
| Notes.Create | Créer des pages dans les blocs-notes OneNote | Peut afficher les titres de vos blocs-notes et des sections ; Création de pages dans n’importe quel emplacement. L’utilisateur ne peut pas afficher ou modifier les pages existantes. |
| Notes.ReadWrite.CreatedByApp | Accès au bloc-notes OneNote par application uniquement | Peut afficher les titres de vos blocs-notes et des sections ; créer des pages ; renommer des sections ; afficher et modifier des pages créées par l’application. Impossible d’afficher ou de modifier des pages créées par d’autres applications ou dans les sections protégées par mot de passe. |
| Notes.Read | Afficher des blocs-notes OneNote | Peut afficher le contenu de vos blocs-notes et des sections. Ne peut pas créer de nouvelles pages ; modifier les pages existantes ; et accéder aux sections protégées par un mot de passe. |
| Notes.ReadWrite | Afficher et modifier des blocs-notes OneNote | Peut afficher les titres de vos blocs-notes et des sections ; afficher et modifier toutes les pages ; créer des pages ; renommer des sections. L’utilisateur ne peut pas accéder aux sections protégées par un mot de passe. |
Étendues pour les blocs-notes de site et de groupe auxquels l’utilisateur actuel peut accéder
Si vous travaillez avec des blocs-notes du site SharePoint ou du groupe unifié, choisissez parmi les étendues suivantes. Ces autorisations s’appliquent également aux blocs-notes personnels de l’utilisateur actuel, mais pas aux blocs-notes personnels partagés par d’autres utilisateurs. L’accès au contenu personnel partagé n’est actuellement pas pris en charge.
| Étendue (entreprise) | Autorisation dans le portail Azure | Description |
|---|---|---|
| Notes.Read.All | Afficher des blocs-notes OneNote dans votre organisation | Peut afficher le contenu des blocs-notes et des sections dans tous les ordinateurs portables auxquels l’utilisateur a accès. Ne peut pas créer de nouvelles pages ; modifier les pages existantes ; et accéder aux sections protégées par un mot de passe. |
| Notes.ReadWrite.All | Afficher et modifier des blocs-notes OneNote dans votre organisation | Peut afficher les titres des blocs-notes et des sections ; afficher et modifier toutes les pages ; renommer toutes les sections ; créer de nouveles pages dans tous les blocs-notes auxquels l’utilisateur connecté a accès. L’utilisateur ne peut pas accéder aux sections protégées par un mot de passe. |
Pour les autorisations utilisées pour accéder aux blocs-notes personnels sur OneDrive, voir Choisissez les autorisations OneNote (applications pour client indiviuel).
Authentifiez les utilisateurs et obtenez un jeton d’accès (applications d’entreprise)
Votre application lance le processus de connexion en contactant le service d’autorisation. Si les utilisateurs ne sont pas encore connectés ou n’ont pas encore donner leur accord, le service les invite à fournir leurs informations d’identification et à accepter les autorisations demandées par votre application. Si l’authentification et l’autorisation aboutissent, vous recevrez un jeton d’accès que vous incluerez dans vos demandes à l’API OneNote.
Important
Traitez les jetons d’accès et jetons d’actualisation aussi sûrement que vous le feriez avec le mot de passe d’un utilisateur.
Notes
En fonction de votre plateforme, vous avez la possiblité d'utiliser un kit de développement logiciel (SDK) pour simplifier les flux d'authentification.
L’obtention d’un jeton d’accès se fait en deux étapes lorsqu’on utilise le flux de code :
- Authentifiez l’utilisateur et obtenez un code d’autorisation.
- Échangez le code contre un jeton d’accès.
Ce processus représente le flux d’autorisation via le code d’autorisation. Si vous souhaitez utiliser le flux implicite, vous devez modifier le fichier manifeste. Voir Configurez votre application pour autoriser le flux d’autorisation implicite OAuth 2.0 dans Inscrivez votre application Web basée sur le navigateur.
Étape 1. Authentifiez l’utilisateur et obtenez un code d’autorisation. Pour démarrer le processus d’authentification, chargez la demande d’URL suivante dans un navigateur Web ou un contrôle de navigateur Web.
L’URL ci-dessous utilise le point de terminaison commun, qui est valide pour toute application.
https://login.microsoftonline.com/common/oauth2/authorize
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&resource=https://onenote.com/
| Paramètre de chaîne de requête requis | Description |
|---|---|
| response_type | Le type de flux d’authentification que vous utilisez. Pour ce cas, le code. |
| client_id | ID client créé pour votre application. |
| redirect_uri | L’URL de redirection pour votre application. |
| ressource | La ressource à laquelle vous devez accéder Dans ce cas, https://onenote.com/ |
Une fois l’authentification et l’autorisation réussies, le navigateur Web se redirige vers votre URL de redirection à l’aide d’un code de paramètre ajouté à l’URL, comme indiqué dans l’exemple suivant. Copiez la valeur de codeà utiliser à l’étape 2. Ce code est valide pour quelques minutes.
https://your-redirect-uri/
?code=AAABAA...AA
&session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b
Étape 2. Échangez le code d'autorisation contre un jeton d'accès et actualisez le jeton. Envoyez la demande HTTP suivante en incluant une chaîne d’URL correctement codée dans le corps du message.
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&code={code}
&resource=https://onenote.com/
| Paramètre de corps requis | Description |
|---|---|
| grant_type | Le type d’autorisation de la demande. Pour ce cas, authorization_code. |
| client_id | ID client créé pour votre application. |
| client_secret | Applications Web et API Web uniquement. Clé secrète client créée pour votre application. |
| code | Le code que vous avez reçu en tant que paramètre d’URL à l’étape précédente. |
| redirect_uri | L’URL de redirection pour votre application. Cela doit correspondre à redirect_uri dans la première demande. |
| ressource | La ressource à laquelle vous devez accéder Dans ce cas, https://onenote.com/ |
En cas de succès, la réponse à la demande POST contient une chaîne JSON qui inclut le jeton d’accèsaccess_token et le jeton d’actualisationrefresh_token, comme indiqué dans l’exemple suivant. Le jeton d’accès est valide uniquement pour un nombre de secondes spécifié dans la propriété expires_in.
{
"token_type":"Bearer",
"expires_in":"3600",
"scope":"Notes.ReadWrite",
"expires_on":"1446588136",
"not_before":"1446584236",
"resource":"https://onenote.com/",
"access_token":"eyJ0eX...2-w",
"refresh_token":"AAABAAA...IAA",
"id_token":"eyJ0eX...fQ."
}
Voir Flux d’autorisation via un code d’autorisation pour en savoir plus sur l'implémentation Azure AD du flux d’autorisation via un code, y compris les paramètres supplémentaires que vous pouvez utiliser dans les demandes.
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/me/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 la date d’expiration du jeton avant de l’utiliser et obtenir un nouveau jeton d’accès si nécessaire. Les utilisateurs peuvent rester connectés. Ils n’ont plus besoin d’accorder des autorisations à moins qu’ils ne se déconnectent ou révoquent celles-ci.
Obtenir un nouveau code d’accès après son expiration
Vous pouvez demander un nouveau jeton d’accès à l’aide du jeton d’actualisation ou en répétant la demande d’authentification effectuée au début.
Lorsque le jeton d’accès expire, les demandes soumises à l’API renvoient une 401 Unauthorized réponse. Votre application doit gérer cette réponse et vérifier la date d’expiration du jeton avant d’envoyer des demandes.
Envoyez la demande HTTP suivante en incluant une chaîne d’URL correctement codée dans le corps du message.
L’URL de l’exemple suivant utilise le point de terminaison commun, qui est valide pour toute application.
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
&resource={resource-id}
| Paramètre de corps requis | Description |
|---|---|
| grant_type | Le type d’autorisation de la demande. Pour ce cas, refresh_token. |
| client_id | ID client créé pour votre application. |
| client_secret | Applications Web et API Web uniquement. Clé secrète client créée pour votre application. |
| redirect_uri | L’URL de redirection pour votre application. |
| refresh_token | Jeton d’actualisation que vous avez reçu précédemment. |
| ressource | La ressource à laquelle vous devez accéder Dans ce cas, https://onenote.com/ |
En cas de succès, la réponse à la demande POST contient une chaîne JSON qui inclut le jeton d’accèsaccess_token et le jeton d’actualisation refresh_token, comme indiqué dans l’exemple suivant.
{
"token_type":"Bearer",
"expires_in":"3600",
"scope":"Group.Read.All Notes.ReadWrite",
"expires_on":"1447656020",
"not_before":"1447652120",
"resource":"https://onenote.com/",
"access_token":"eyJ0eX...Jww",
"refresh_token":"AAABAAA...IAA"
}
Mettez à jour vos codes stockés pour vous assurer que votre application dispose de codes présentant une durée de vie plus longue.
Les SDK pour le développement de OneNote
Les applications OneNote peuvent utiliser le kit de développement logiciel (SDK) de l’API OneDrive pour obtenir les jetons d’accès nécessaires pour toutes les demandes de OneNote API. Le SDK rend l’authentification plus facile pour vous. Vous fournissez simplement vos informations d’identité et intégrez quelques appels. Le SDK s’occupe alors de tout, de la connexion et consentement jusqu’à l’obtention, le stockage et le rafraîchissement des jetons. Ensuite, vous pouvez effectuer des appels REST à OneNote API. Notre didacticiel iOS montre comment vous pouvez utiliser le SDK dans une application OneNote.
Toutes les versions du SDK prennent en charge l’authentification de compte Microsoft (pour les blocs-notes grand public) et certaines prennent également en charge Azure Active Directory (pour les blocs-notes portables d’entreprise). Référez-vous à la documentation OneDrive pour la liste actuelle des plateformes prises en charge.
Notes
Le SDK de l’API OneDrive remplace le SDK Live. Le SDK Live est obsolète mais continuera à prendre en charge les applications OneNote existantes qui l’utilisent. Pour un nouveau développement, utilisez le SDK de l’API OneDrive.
Il est possible qu’à un moment donné, nous proposions des bibliothèques qui gèrent à la fois l’authentification et les appels natifs vers OneNote API, mais pour l’instant, vous pouvez utiliser le SDK de l’API OneDrive.
Une autre solution pour les applications d’entreprise consiste à utiliser la Bibliothèque d’authentification Active Directory (ADAL) pour accéder aux blocs-notes Office 365 et hébergés par SharePoint. Vous pouvez envisager d’utiliser ADAL directement s’il n'y a pas de SDK disponible pour votre plateforme ou si vous souhaitez plus de contrôle sur le processus d’authentification. Notre didacticiel ASP.NET MVC montre comment vous pouvez utiliser ADAL dans une application OneNote.
Important
Pour interagir avec le contenu et les ressources OneNote, vous devez toujours utiliser OneNote API. N’utilisez pas l’API OneDrive.
Erreurs
En cas d’erreur d’authentification, le navigateur web est redirigé vers une page d’erreur. La page d’erreur affiche toujours un message convivial, mais l’URL de la page inclut des paramètres supplémentaires qui peuvent vous aider à déboguer l'erreur survenue. 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 accorder d’autorisation à la 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.