OneNote-Authentifizierung und Berechtigungen
Gilt für: Heimanwender-Notizbücher in OneDrive | Unternehmensnotizbücher in Office 365
OneNote verwendet Microsoft-Konto (früher Live Connect) und Azure Active Directory, um einen sicheren Zugriff auf OneNote-Notizbücher zu ermöglichen. Bevor Sie auf Notizbücher zugreifen können, müssen Sie sich zunächst mit einem Microsoft-Konto oder der Azure AD-Authentifizierung authentifizieren und ein Zugriffstoken erhalten.
Microsoft-Konto wird für den Zugriff auf Notizbücher für Consumer auf OneDrive verwendet und Azure AD für den Zugriff auf Notizbücher für Unternehmen auf Office 365.
Beide Autorisierungsdienste implementieren das OAuth 2.0-Protokoll, um die Zugriffstoken bereitzustellen, die für die Interaktion mit OneNote erforderlich sind. Alle Anforderungen an die OneNote-API müssen ein gültiges Zugriffstoken im Autorisierungs-Header enthalten.
Dieser Artikel beschreibt die authentifizierten Prozesse, für die Sie verantwortlich sind: Registrieren Sie Ihre App, um eine Client-ID zu erhalten. Geben Sie die erforderlichen Berechtigungen an und rufen Sie den Autorisierungsdienst auf, um Benutzer anzumelden und ein Zugriffstoken zu erhalten.
Abhängig von Ihrer Plattform können Sie eine SDK verwenden, um die Authentifizierungsflüsse zu vereinfachen.
Hinweis
OneNote unterstützt schließlich das einzelne Authentifizierungsmodell und die App-Registrierung, die durch das v2.0 App-Modell bereitgestellt werden. Achten Sie auf OneNote Entwickler-Blog auf relevante Updates.
APIs testen
Folgen Sie den Schritten in diesem Artikel, um ein Zugriffstoken mit Ihrem bevorzugten Netzwerktool z. B. Fiddler zu erhalten.
Authentifizierung mit Microsoft-Konto (Apps für Unternehmen)
- Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten
- OneNote-Berechtigungen auswählen
- Benutzer anmelden und einen Zugangscode erhalten
- Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist
Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten (Apps für Consumer)
Zunächst müssen Sie eine Anwendung bei Microsoft registrieren. Dieser Prozess erstellt ein Dienstprinzipal, auf das Sie von Ihrer App aus verknüpfen, und generiert die Client-ID und den geheimen Schlüssel, den Sie an den Autorisierungsdienst senden.
Tun Sie dies, wenn Ihre App nur auf Notizbücher für Consumer zugreift, oder wenn sie sowohl auf Consumer- als auch auf Notizbücher für Unternehmen zugreift.
Melden Sie sich im Microsoft-Konto Developer Center mit Ihrem Microsoft-Konto an. (Wenn Sie eine Windows Store App entwickeln, machen Sie stattdessen dies.)
Wenn Sie kein Microsoft-Konto haben, müssen Sie eineserstellen. Sie sollten eine E-Mail-Adresse verwenden, die Sie regelmäßig überprüfen. Wir könnten versuchen, Sie zu kontaktieren, um Ihre Anwendung auf unserer Seite Ausgewählte Apps hervorzuheben, oder wenn wir unerwarteten Netzwerkverkehr von Ihrer App bemerken. Wir werden Sie Ihnen keinen Spam senden oder Ihre Informationen verkaufen.
Wählen Sie Anwendung erstellen aus.
Geben Sie den Namen ein, den Benutzer sehen sollen, wenn sie aufgefordert werden, Ihrer App Berechtigungen zu erteilen, und wählen Sie die Hauptsprache für Ihre App aus.
Wenn Sie die Nutzungsbedingungen und die Richtlinien zu Datenschutz und Cookies akzeptieren, klicken Sie auf Ich akzeptiere, um mit der Registrierung fortzufahren.
Wählen Sie auf der Seite API-Einstellungen Ihren App-Typ aus und geben Sie Informationen über Ihre App an:
Web-App (serverseitige Apps)
a) Wählen Sie Nein für Mobile oder Desktop-Client-Appaus.
b) Geben Sie für die Zieldomäne die Dienst-URL ein.
c) Geben Sie die Umleitungs-URL ein, an die die Benutzer weitergeleitet werden sollen, nachdem sie authentifiziert wurden und Zugriff auf Ihre App erhalten haben.
Systemeigene Anwendungen (auf einem Gerät installiert)
a) Wählen Sie Ja für Mobile oder Desktop-Client-App aus.
b) (Optional) Geben Sie für die Zieldomäne die mobile Dienst-URL ein.
c) (Optional) Geben Sie für die Umleitungs-URL eine gültige URL ein. Dies dient als Bezeichner für Ihre App und muss kein physischer Endpunkt sein.*
Speichern Sie die Client-ID und den geheimen Clientschlüssel, die auf der Seite App-Einstellungen angezeigt werden, sowie die Umleitungs-URL, falls Sie eine solche angegeben haben.
Windows Store-Apps
Wenn Sie eine Windows-App erstellen, registrieren Sie Ihre Anwendung stattdessen unter Windows Dev Center. Dadurch erhalten Sie die Paket-Identität (Paket-SID), die Sie anstelle der Client-ID verwenden.
Melden Sie sich im Windows Dev Center mit Ihrem Microsoft-Konto an.
Wählen Sie im Dashboard Neue App erstellen und geben Sie Ihren App-Namen ein.
Klicken Sie in Visual Studio mit der rechten Maustaste auf Ihr Windows Store App-Projekt und wählen Sie Store > App mit Store verknüpfen.
Melden Sie sich im Fenster "App mit dem Windows Store verknüpfen" mit Ihrem Microsoft-Konto an, wählen Sie Ihre App und dann Weiter > Zuordnen. Dadurch werden die erforderlichen Windows-Store-Registrierungsinformationen dem Anwendungsmanifest hinzugefügt.
Für eine universelle Windows-App wiederholen Sie die beiden vorherigen Schritte für das Windows Phone-Projekt.
OneNote-Berechtigungsbereiche wählen (Apps für Unternehmen)
Berechtigungsbereiche stellen Zugriffsebenen auf OneNote-Inhalte dar. Sie fordern die Berechtigungen an, die Ihre App benötigt, und Benutzer gewähren oder verweigern den Zugriff, wenn sie sich bei Ihrer App anmelden. Benutzer können nur die Berechtigungen vergeben, die sie haben.
Wählen Sie die unterste Ebene der Berechtigungen aus, die Ihre App für ihre Arbeit benötigt. Sie können mehrere Bereiche anfordern.
| Bereich (Consumer) | Beschreibung |
|---|---|
| office.onenote_create | Zeigt eine Liste der OneNote-Notizbücher des Benutzers an und erstellt neue Seiten, zeigt aber keine vorhandenen Seiten an oder bearbeitet sie. Zählt die Notizbuchhierarchie des Benutzers au und erstellt Seiten an einer beliebigen Stelle. |
| office.onenote_update_by_app | Kann alle von der App erstellten Seiten erstellen, anzeigen und ändern. |
| office.onenote_update | Kann beliebige Inhalte in den OneNote-Notizbüchern und -Seiten des Benutzers erstellen, anzeigen und ändern. |
| office.onenote | Kann OneNote-Notizbücher und -Seiten anzeigen, sie jedoch nicht verändern. |
| wl.signin | Ein Microsoft-Konto-Berechtigungsbereich. Ermöglicht Ihrer Anwendung die Nutzung der Vorteile der Funktionen des einmaligen Anmeldens. |
| wl.offline_zugang | Ein Microsoft-Konto-Berechtigungsbereich. Ermöglicht Ihrer Anwendung, einen Aktualisierungs-Token zu erhalten, sodass sie offline arbeiten kann, auch wenn der Benutzer nicht aktiv ist. Dieser Bereich ist für den Token-Ablauf nicht verfügbar. |
Berechtigungen für den Zugriff auf Office 365-Notizbücher finden Sie unter OneNote-Berechtigungen auswählen (Apps für Unternehmen).
Benutzer anmelden und einen Zugangscode erhalten (Apps für Consumer)
Ihre App leitet den Anmeldevorgang ein, indem sie den Autorisierungsdienst kontaktiert. Wenn Benutzer noch nicht angemeldet sind oder noch nicht eingewilligt haben, fordert der Dienst sie zur Eingabe von Anmeldeinformationen und zur Zustimmung zu den von Ihrer App angeforderten Berechtigungen auf. Wenn die Authentifizierung und Autorisierung erfolgreich waren, erhalten Sie ein Zugriffstoken, das Sie in Ihre Anforderungen an die OneNote-API einschließen.
Wichtig
Behandeln Sie Zugriffstoken und Aktualisierungstoken so sicher wie das Kennwort eines Benutzers.
Hinweis
Abhängig von Ihrer Plattform können Sie eine SDK verwenden, um die Authentifizierungsflüsse zu vereinfachen.
Wählen Sie Ihren Authentifizierungsfluss aus. Beide sind standardmäßige OAuth 2.0-Flüsse.
| Hyperion | Beschreibung |
|---|---|
| Tokenfluss | Ruft ein Zugriffstoken in einem Aufruf ab. Hilfreich für den schnellen Zugriff, aber kein Aktualisierungtoken für den langfristigen Zugriff. Auch impliziter Fluss genannt. |
| Codefluss | Ruft beim ersten Aufruf einen Autorisierungscode ab und tauscht den Code gegen einen Zugriffstoken beim zweiten Aufruf aus. Wird es mit dem Berechtigungsbereich wl.offline-access verwendet, erhält Ihre Anwendung ein Aktualisierungstoken, das einen langfristigen Zugriff ermöglicht. Auch Autorisierungscode-Fluss genannt. |
Benutzer mit dem Tokenfluss anmelden
Laden Sie die folgende URL-Anforderung in einen Web-Browser oder eine Webbrowsersteuerung.
GET https://login.live.com/oauth20_authorize.srf
?response_type=token
&client_id={client_id}
&redirect_uri={redirect_uri}
&scope={scope}
| Erforderlicher Parameter der Abfragezeichenfolge | Beschreibung |
|---|---|
| response_type | Die Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Token. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| redirect_uri | Die Umleitungs-URL, die Sie für Ihre Anwendung registriert haben. Mobile und Desktop-Apps, die keine Angabe gemacht haben, können dies nutzen: https://login.live.com/oauth20_desktop.srf |
| Bereich | Die Bereiche, die Ihre Anwendung benötigt. Beispiel: office.onenote%20wl.sign-in |
Nach erfolgreicher Authentifizierung und Autorisierung leitet der Webbrowser zu Ihrer Umleitungs-URL um und hängt die Zugriffsparameter an die URL an. Die Parameter umfassen den Access_-Token und den Token_-Typ, wie im folgenden Beispiel gezeigt. Das Zugriffstoken gilt nur für die Anzahl von Sekunden, die in der Eigenschaft expires_in angegeben sind.
https://your-redirect-url
#access_token=EwB4Aq...%3d
&token_type=bearer
&expires_in=3600
&scope=office.onenote wl.signin
&user_id=c519ea026ece84de362cfa77dc0f2348
Benutzer mit dem Codefluss anmelden
Erhalten eines Zugriffstokens ist mit dem Codefluss ein zweistufiger Prozess:
- Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode.
- Ersetzen Sie den Code durch ein Zugriffstoken.
Schritt 1: Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode. Laden Sie die folgende URL-Anforderung in einen Web-Browser oder eine Webbrowsersteuerung, um den Anmeldeprozess zu beginnen.
https://login.live.com/oauth20_authorize.srf
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&scope={scope}
| Erforderlicher Parameter der Abfragezeichenfolge | Beschreibung |
|---|---|
| response_type | Die Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Code. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| redirect_uri | Die Umleitungs-URL, die Sie für Ihre Anwendung registriert haben. Mobile und Desktop-Apps, die keine Angabe gemacht haben, können dies nutzen: https://login.live.com/oauth20_desktop.srf |
| Bereich | Die Bereiche, die Ihre Anwendung benötigt. Beispiel: office.onenote wl.signin wl.offline_access |
Nach erfolgreicher Authentifizierung und Autorisierung leitet der Webbrowser mit einem Parameter Code zu Ihre Umleitungs-URL um, wie im folgenden Beispiel gezeigt. Kopieren Sie den in Schritt 2 zu verwendenden Wert Code. Dieser Code ist für einige Minuten gültig.
https://your-redirect-uri
?code=M57010781-9e8c-e31e-ca0d-46bc104236c4
Schritt 2: Tauschen Sie den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken aus. Senden Sie die folgende HTTP-Anforderung mit einem korrekt kodierten URL-String im Nachrichtentext.
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}
| Benötigte Textparameter | Beschreibung |
|---|---|
| grant_type | Der Erteilungstyp der Anforderung. In diesem Fall ist es authorization_code. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| client_secret | Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| Code | Der Code, den Sie im vorherigen Schritt als URL-Parameter erhalten haben. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. Dies muss mit redirect_uri in der ersten Anfrage übereinstimmen. |
Wenn erfolgreich, enthält die Antwort einen JSON-String, der das Zugriffs_-Token--und die Aktualisierungs_-Token enthält, wenn Sie den Bereich wl.offline_-Zugriff angefordert haben, wie im folgenden Beispiel gezeigt. Das Zugriffstoken gilt nur für die Anzahl von Sekunden, die in der Eigenschaft expires_in angegeben sind.
{
"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"
}
Schließen Sie das Zugriffstoken in Ihre Anforderung an die OneNote-API ein
Alle Ihre Anforderungen an die OneNote-API müssen das Zugriffstoken als Inhaber-Token im Autorisierungs-Header senden. Zum Beispiel erhält die folgende Anforderung fünf Ihrer Notizbücher, alphabetisch nach Namen sortiert:
GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}
Zugriffstoken sind nur für eine Stunde gültig, sodass Sie nach Ablauf dieser Zeit neue Token erhalten müssen. Sie sollten den Ablauf des Tokens überprüfen, bevor Sie es verwenden, und sich bei Bedarf ein neues Zugriffstoken besorgen. Benutzer können angemeldet bleiben und müssen sich nicht erneut mit den Berechtigungen einverstanden erklären, es sei denn, sie melden sich ab oder widerrufen die Berechtigungen.
Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist (Apps für Consumer)
Sie können ein neues Zugriffstoken anfordern, indem Sie das Aktualisierungstoken verwenden oder den Authentifizierungsprozess von Anfang an wiederholen.
Wenn ein Zugriffstoken abgelaufen ist, erhalten Sie bei Anforderungen an die API eine 401 Unauthorized-Antwort. Ihre App sollte diese Antwort verarbeiten und den Ablauf des Token überprüfen, bevor sie Anforderungen sendet.
Senden Sie die folgende HTTP-Anforderung mit einem korrekt kodierten URL-String im Nachrichtentext.
Sie haben ein Aktualisierungs-Token erhalten, wenn Sie die Berechtigung wl.offline_access angefordert und den Codefluss verwendet haben.
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}
| Benötigte Textparameter | Beschreibung |
|---|---|
| grant_type | Der Erteilungstyp der Anforderung. In diesem Fall ist es refresh_token. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| client_secret | Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. Dies muss mit der redirect_uri übereinstimmen, die Sie verwendet haben, um die Token zu erhalten. |
| refresh_token | Das zuvor erhaltene Aktualisierungstoken. |
Wenn erfolgreich, enthält die Antwort für die POST-Anforderung einen JSON-String, der das Zugriffs_-Token und das Aktualisierungs_-Token enthält, wie im folgenden Beispiel gezeigt.
{
"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"
}
Aktualisieren Sie Ihre gespeicherten Token, um sicherzustellen, dass Ihre App Token mit der längsten Lebensdauer hat.
Benutzer abmelden (Apps für Consumer)
Führen Sie die folgenden Schritte aus, um einen Benutzer abzumelden:
Löschen Sie alle zwischengespeicherten Zugriffstoken oder Aktualisierungstoken, die Sie erhalten oder gespeichert haben.
Führen Sie alle Abmeldeaktionen in Ihrer Anwendung aus (beispielsweise das Bereinigen des lokalen Status, das Entfernen zwischengespeicherter Elemente usw.).
Senden Sie mit der folgenden URL einen Aufruf an den Autorisierungsdienst:
https://login.live.com/oauth20_logout.srf
?client_id={client_id}
&redirect_uri={redirect_uri}
Dieser Aufruf entfernt alle Cookies, die einmaliges Anmelden ermöglichen und stellt sicher, dass der Benutzer zur Anmeldung aufgefordert wird.
| Erforderlicher Parameter der Abfragezeichenfolge | Beschreibung |
|---|---|
| client_id | Der für Ihre Anwendung erstellte Client-ID-Wert. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. Dies muss mit der redirect_uri übereinstimmen, die Sie verwendet haben, um die Token zu erhalten. |
Nach dem Entfernen von Cookies leitet der Browser auf Ihre Umleitungs-URL um. Die Umleitungsseite wird ohne Angabe von Optionen von Authentifizierungs-Abfrage-Zeichenfolgen geladen, was bedeutet, dass der Benutzer abgemeldet wurde.
Zugriff widerrufen
Benutzer können den Zugriff einer Anwendung auf ihr Konto widerrufen, indem Sie die Seite Microsoft-Konto Verwalten besuchen.
Wenn die Zustimmung für Ihre App widerrufen wird, sind zuvor für Ihre App bereitgestellte Aktualisierungstokens nicht mehr gültig. Sie erhalten die folgende Antwort, wenn Sie versuchen, das Token zu aktualisieren:
{
"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."
}
Sie müssen den Authentifizierungs-Prozess wiederholen, um zu Beginn ein neues Zugriffs- und Aktualisierungstoken anzufordern.
Authentifizierung mit Azure AD (Apps für Unternehmen)
Wenn Ihre Anwendung Anwendungsberechtigungen verwendet (im Gegensatz zu delegierten Berechtigungen), siehe OneNote-Authentifizierung und Azure AD Anwendungsberechtigungen.
- Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten
- OneNote-Berechtigungen auswählen
- Benutzer anmelden und einen Zugangscode erhalten
- Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist
Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten (Apps für Unternehmen)
Zunächst müssen Sie eine Anwendung bei Microsoft registrieren. Dieser Prozess erstellt ein Dienstprinzipal, auf das Sie von Ihrer App aus verknüpfen, und generiert die Client-ID und den geheimen Schlüssel, den Sie an den Autorisierungsdienst senden.
Tun Sie dies, wenn Ihre App nur auf Notizbücher für Unternehmen zugreift, oder wenn sie sowohl auf Consumer- als auch auf Notizbücher für Unternehmen zugreift.
Sie müssen zum Registrieren Ihrer App bei einem Azure AD-Mandanten, der mit einem Office 365-Abonnement verbunden ist, Folgendes tun:
Ein Office 365-Konto mit globalen Administratorrechten für einen Office 365-Mandanten
Sie können ein Office 365 Developer-Abonnement testen oder kaufen oder einen Qualifizierungsplanabonnieren.
Bereitstellung von OneDrive for Business für Ihren Mandanten
Dadurch wird die OneNote-Anwendung verfügbar, sodass Sie OneNote-Berechtigungen angeben können. Melden Sie sich zur Überprüfung, ob OneDrive for Business bereitgestellt wird, bei OneNote Online mit Ihren Office 365 Zugangsdaten an (ein Arbeits- oder Schulkonto wie
someone@example.comodersomeone@example.onmicrosoft.com).Wenn Sie Ihre Notizbücher sehen, sind Sie bereit. Wenn Sie "Entschuldigung, wir können Ihre Notizbücher nicht abrufen ..." sehen, wählen Sie Zum Konto > Weiter. Wenn Ihre OneDrive for Business-Seite geladen wird, gehen Sie zurück und aktualisieren Sie OneNote Online, um das Provisioning abzuschließen.
Hinweis
Die persönlichen Sites Ihrer Benutzer müssen bereitgestellt werden, bevor Sie auf deren Notizbücher zugreifen können. Die OneNote-API versucht, ihre Websites bei Bedarf automatisch bereitzustellen.
Ihr Office 365-Abonnement einem Azure-Abonnement zuordnen
So können Sie Ihre App in Azure AD registrieren und verwalten. (Mehr erfahren)
Wenn Sie kein Azure-Abonnement haben, gehen Sie zu Option 1 im nächsten Abschnitt. Wenn Sie eines haben, gehen Sie zu Option 2.
Wichtig
Sie und Ihre Benutzer müssen über ein Office 365-Konto mit einer gültigen Office 365-Lizenz verfügen. Benutzerkonten ohne gültige Lizenzen können keine Notizbücher auf OneNote Online sehen, und API-Aufrufe ihrer Notizbücher werden fehlschlagen. Office 365-Administratoren können den Status prüfen und Lizenzen aufheben.
Hinweis
MSDN-Abonnenten: Möglicherweise haben Sie Anspruch auf ein kostenloses Office 365 Developer-Abonnement sowie auf zusätzliche Einsparungen, wenn Sie Ihren Azure-Vorteil aktivieren. Überprüfen Sie Ihre Vorteile auf der Seite MSDN-Abonnements.
Ihr Azure-Abonnement Ihrem Office 365-Abonnement zuordnen
Option 1: Registrieren Sie sich mit Admin-Anmeldeinformationen für Ihr Office 365-Abonnement für ein Azure-Abonnement. Tun Sie dies, wenn Sie kein Azure-Abonnement haben. Dieser Prozess verbindet die Abonnements.
Melden Sie sich im Azure-Verwaltungsportal mit Ihren Office 365-Administrationsdaten an (ein Arbeits- oder Schulkonto wie
someone@example.comodersomeone@example.onmicrosoft.com).Wählen Sie auf der Seite Keine Abonnements gefunden Bei Microsoft Azure anmelden. Die Anmeldungsseite wird geladen und zeigt einige Informationen aus Ihrem Office 365-Abonnement an. Dieses Konto wird zum Dienstadministrator für das neue Azure-Abonnement.
Die Anmeldeerfahrung hängt davon ab, ob Sie ein Test- oder ein bezahltes Office 365-Abonnement haben:
Wenn Sie eine Testversion haben, geben Sie Ihre Zahlungsinformationen auf der Seite Kostenlose Testversion ein. Sie werden nicht belastet, es sei denn, Sie entscheiden sich für ein kostenpflichtiges Abonnement.
Wenn Sie den Abonnementvertrag, die Angebotsdetails und die Datenschutzbestimmung akzeptieren, aktivieren Sie das Kontrollkästchen und wählen Sie Kaufen aus. Die Seite Abonnements wird für Ihr neues Azure-Konto geöffnet. Testversionabonnements erhalten ein Guthaben von $ 200,00, das innerhalb von 30 Tagen genutzt werden kann. Sie können das Abonnement jederzeit auf dieser Seite kündigen.
Wenn Sie ein bezahltes Abonnement haben, vervollständigen Sie Ihre Kontaktdaten und wählen Sie dann Registrieren. Wählen Sie nach der Erstellung Ihres Abonnements Mit der Verwaltung meines Diensts beginnen, um das Azure-Verwaltungsportal zu öffnen.
Option 2: Ordnen Sie ein vorhandenes Azure-Abonnement einem Office 365-Abonnement zu. Danach haben Sie ein Microsoft-Konto, das einen Dienstadministrator oder Co-Administrator für Ihr Azure-Abonnement ist. Dieser Prozess verwandelt das Microsoft-Konto zum globalen Administrator des Office 365-Mandanten.
Melden Sie sich bei dem [Azure-Verwaltungsportal] aad-portal mit Ihren vorhandenen Microsoft-Konto-Anmeldeinformationen an (z. B.
someone@live.com).Wählen Sie in der Schublade unten auf der Seite Neu > App-Dienste > Active Directory > Verzeichnis > Benutzerdefiniert erstellen.
Im Fenster Verzeichnis hinzufügen wählen Sie für das Verzeichnis Vorhandenes Verzeichnis verwenden.
Wählen Sie Ich bin jetzt für die Abmeldung bereit, und klicken Sie auf das Häkchen. Das meldet Sie vom Portal ab.
Melden Sie sich wieder mit den globalen Adminstrator-Anmeldeinformationen für den Office 365-Mandanten an, den Sie zuordnen möchten (ein Arbeits- oder Schulkonto wie
someone@example.comodersomeone@example.onmicrosoft.com).Wenn Sie gefragt werden, ob Sie das Verzeichnis mit Azure verwenden möchten, wählen Sie Weiter > Jetzt abmelden.
Schließen Sie den Browser und öffnen Sie dann das Azure-Verwaltungsportal.
Melden Sie sich erneut mit Ihren Microsoft-Anmeldeinformationen an und wählen Sie im Navigationsbereich Active Directory. Ihr Office 365-Verzeichnis sollte auf der Registerkarte Verzeichnis aufgeführt sein.
Registrieren Sie Ihre App auf dem Azure-Verwaltungsportal
Melden Sie sich am [Microsoft Azure-Verwaltungsportal] aad-portal an. Verwenden Sie die Administrator-Anmeldeinformationen für Ihr Azure-Abonnement.
Wählen Sie im Navigationsbereich Active Directory aus.
Wählen Sie das Verzeichnis aus, in dem Sie Ihre Anwendung registrieren möchten, und öffnen Sie dann die Registerkarte Anwendungen.
Wählen Sie in der Schublade unten auf der Seite Hinzufügen > Eine von meinem Unternehmen entwickelte Anwendung hinzufügen aus.
Geben Sie einen benutzerfreundlichen Namen für die Anwendung ein und wählen Sie den Anwendungstyp aus:
Webanwendung oder Web-API (Browser- oder Server-Apps)
a) Wählen Sie Webanwendung und/oder Web-API aus.
b) Geben Sie für die Anmelde-URL die URL ein, unter der sich die Benutzer anmelden und Ihre App verwenden.
c) Geben Sie für die URI der App-ID eine eindeutige ID für Ihre App ein. Diese muss sich in einer verifizierten benutzerdefinierten Domäne befinden.
d) Geben Sie für die Antwort-URL die URL ein, auf die als Antwort auf eine OAuth 2.0-Anforderung umgeleitet werden soll. Dies muss kein physischer Endpunkt sein, aber es muss ein gültiger URI sein.
e) Wählen Sie Ja für Die Anwendung ist mehrinstanzfähig, um die App für externe Azure-Mandanten verfügbar zu machen.
Systemeigene Clientanwendung (auf einem Gerät installierte Apps)
a) Wählen Sie Systemeigene Clientanwendung aus.
b) Geben Sie eine Umleitungs-URI ein, auf die als Antwort auf eine OAuth 2.0-Anforderung umgeleitet werden soll. Dies muss kein physischer Endpunkt sein, aber es muss ein gültiger URI sein.
Für Webanwendungen generiert Azure sowohl eine Client-ID als auch ein App-Geheimnis (oder einen geheimen App-Schlüssel). Für systemeigene Client-Apps generiert Azure eine Client-ID. Speichern Sie diese Werte.
Ausführliche Anweisungen über die Registrierung von Apps finden Sie in der Office 365-Dokumentation.
OneNote-Berechtigungsbereiche wählen (Apps für Unternehmen)
Berechtigungsbereiche stellen Zugriffsebenen auf OneNote-Inhalte dar. Sie fordern die Berechtigungen an, die Ihre App benötigt, und Benutzer gewähren oder verweigern den Zugriff, wenn sie sich bei Ihrer App anmelden. Benutzer können nur die Berechtigungen vergeben, die sie haben.
Wählen Sie im Abschnitt Azure-Verwaltungsportal, im Abschnitt Berechtigungen für andere Anwendungen auf der App-Konfigurationsseite Anwendung hinzufügen.
Wählen Sie die OneNote-Anwendung und klicken Sie dann auf das Häkchen in der unteren rechten Ecke. Wenn OneNote nicht aufgeführt wird, stellen Sie sicher, dass Sie OneDrive for Business für Ihren Mandanten bereitgestellt haben.
Wählen Sie die unterste Ebene der Berechtigungen aus, die Ihre App für ihre Arbeit benötigt und speichern Sie die Änderungen. Sie können mehrere Bereiche anfordern.
Bereiche für persönliche Notizbücher, die sich im Besitz des aktuellen Benutzers befinden
Wenn Sie nur mit persönlichen Notizbüchern auf OneDrive for Business arbeiten, wählen Sie aus den folgenden Bereichen.
| Bereich (Unternehmen) | Berechtigung im Azure-Portal | Beschreibung |
|---|---|---|
| Notes.Create | Erstellen von Seiten in OneNote-Notizbüchern | Die Titel der Abschnitte und Notizbücher können angezeigt werden. Neue Seiten können an beliebiger Stelle erstellt werden. Kann vorhandene Seiten nicht anzeigen oder bearbeiten. |
| Notes.ReadWrite.CreatedByApp | OneNote-Notizbuch-Zugriff nur für Anwendung | Die Titel Ihrer Notizbücher und Abschnitte können angezeigt werden; neue Seiten können erstellt werden; Abschnitte können umbenannt werden; von der App erstellte Seiten können angezeigt und geändert werden. Seiten, die von anderen Anwendungen oder in kennwortgeschützten Bereichen erstellt wurden, können nicht angezeigt oder geändert werden. |
| Notes.Read | Anzeigen von OneNote-Notizbüchern | Die Inhalte Ihrer Notizbücher und Abschnitte können angezeigt werden. Es können keine neuen Seiten erstellt, bestehende Seiten geändert, kennwortgeschützte Abschnitte aufgerufen werden. |
| Notes.ReadWrite | Anzeigen und Ändern von OneNote-Notizbüchern | Die Titel Ihrer Notizbücher und Abschnitte können angezeigt werden; alle Ihre Seiten können angezeigt und geändert werden; neue Seiten können erstellt werden; Abschnitte können umbenannt werden. Auf kennwortgeschützte Bereiche kann nicht zugegriffen werden. |
Bereiche für Site- und Gruppen-Notizbücher, auf die der aktuelle Benutzer zugreifen kann
Wenn Sie mit SharePoint-Website-Notizbüchern oder einheitlichen Gruppen-Notizbüchern arbeiten, wählen Sie aus den folgenden Bereichen. Diese Berechtigungen gelten auch für die persönlichen Notizbücher des aktuellen Benutzers, nicht jedoch für persönliche Notizbücher, die von anderen Benutzern gemeinsam genutzt werden. Der Zugriff auf freigegebene persönliche Inhalte wird derzeit nicht unterstützt.
| Bereich (Unternehmen) | Berechtigung im Azure-Portal | Beschreibung |
|---|---|---|
| Notes.Read.All | Anzeigen von OneNote-Notizbüchern in Ihrer Organisation | Die Inhalte von Notizbüchern und Abschnitten in allen Notizbüchern, auf die der angemeldete Benutzer Zugriff hat, können angezeigt werden. Es können keine neuen Seiten erstellt, bestehende Seiten geändert, kennwortgeschützte Abschnitte aufgerufen werden. |
| Notes.ReadWrite.All | Anzeigen und Ändern von OneNote-Notizbüchern in Ihrer Organisation | Die Titel von Notizbüchern und Abschnitten können angezeigt werden; alle Seiten können angezeigt und geändert werden; alle Abschnitte können umbenannt werden; neue Seiten können in allen Notizbüchern erstellt werden, auf die der angemeldete Benutzer Zugriff hat. Auf kennwortgeschützte Bereiche kann nicht zugegriffen werden. |
Berechtigungen für den Zugriff auf persönliche Notizbücher auf OneDrive finden Sie unter OneNote-Berechtigungen auswählen (Apps für Consumer).
Benutzer anmelden und einen Zugangscode erhalten (Apps für Unternehmen)
Ihre App leitet den Anmeldevorgang ein, indem sie den Autorisierungsdienst kontaktiert. Wenn Benutzer noch nicht angemeldet sind oder noch nicht eingewilligt haben, fordert der Dienst sie zur Eingabe von Anmeldeinformationen und zur Zustimmung zu den von Ihrer App angeforderten Berechtigungen auf. Wenn die Authentifizierung und Autorisierung erfolgreich waren, erhalten Sie ein Zugriffstoken, das Sie in Ihre Anforderungen an die OneNote-API einschließen.
Wichtig
Behandeln Sie Zugriffstoken und Aktualisierungstoken so sicher wie das Kennwort eines Benutzers.
Hinweis
Abhängig von Ihrer Plattform können Sie eine SDK verwenden, um die Authentifizierungsflüsse zu vereinfachen.
Erhalten eines Zugriffstokens ist ein zweistufiger Prozess:
- Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode.
- Ersetzen Sie den Code durch ein Zugriffstoken.
Dieser Prozess repräsentiert den Autorisierungscode-Erteilungsfluss. Wenn Sie den impliziten Fluss verwenden möchten, müssen Sie die Manifestdatei bearbeiten. Siehe unter Ihre App konfigurieren, um dem OAuth 2.0 impliziten Erteilungfluss zu erlauben in Ihre browserbasierte Webanwendung.
Schritt 1: Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode. Laden Sie die folgende URL-Anforderung in einen Web-Browser oder eine Webbrowsersteuerung, um den Anmeldeprozess zu beginnen.
Diese URL verwendet den allgemeinen Mandantenendpunkt und gilt für eine beliebige Anwendung.
https://login.microsoftonline.com/common/oauth2/authorize
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&resource=https://onenote.com/
| Erforderlicher Parameter der Abfragezeichenfolge | Beschreibung |
|---|---|
| response_type | Die Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Code. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. |
| Ressource | Die Ressource, auf die Sie zugreifen müssen. In diesem Fall ist https://onenote.com/ |
Nach erfolgreicher Authentifizierung und Autorisierung leitet der Webbrowser mit einem Parameter Code zu Ihre Umleitungs-URL um, wie im folgenden Beispiel gezeigt. Kopieren Sie den in Schritt 2 zu verwendenden Wert Code. Dieser Code ist für einige Minuten gültig.
https://your-redirect-uri/
?code=AAABAA...AA
&session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b
Schritt 2: Tauschen Sie den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken aus. Senden Sie die folgende HTTP-Anforderung mit einem korrekt kodierten URL-String im Nachrichtentext.
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/
| Benötigte Textparameter | Beschreibung |
|---|---|
| grant_type | Der Erteilungstyp der Anforderung. In diesem Fall ist es authorization_code. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| client_secret | Nur Webanwendungen und Web-APIs. Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| Code | Der Code, den Sie im vorherigen Schritt als URL-Parameter erhalten haben. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. Dies muss mit redirect_uri in der ersten Anfrage übereinstimmen. |
| Ressource | Die Ressource, auf die Sie zugreifen müssen. In diesem Fall ist https://onenote.com/ |
Wenn erfolgreich, enthält die Antwort eine JSON-Zeichenfolge, die access_token und refresh_token enthält, wie im folgenden Beispiel gezeigt. Das Zugriffstoken gilt nur für die Anzahl von Sekunden, die in der Eigenschaft expires_in angegeben sind.
{
"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."
}
Siehe Authorisierungscode Erteilungsablauf, um mehr über die Azure AD-Implementierung des Code-Erteilungsablauf zu erfahren, einschließlich der zusätzlichen Parameter, die Sie in den Anfragen verwenden können.
Schließen Sie das Zugriffstoken in Ihre Anforderung an die OneNote-API ein
Alle Ihre Anforderungen an die OneNote-API müssen das Zugriffstoken als Inhaber-Token im Autorisierungs-Header senden. Zum Beispiel erhält die folgende Anforderung fünf Ihrer Notizbücher, alphabetisch nach Namen sortiert:
GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}
Zugriffstoken sind nur für eine Stunde gültig, sodass Sie nach Ablauf dieser Zeit neue Token erhalten müssen. Sie sollten den Ablauf des Tokens überprüfen, bevor Sie es verwenden, und sich bei Bedarf ein neues Zugriffstoken besorgen. Benutzer können angemeldet bleiben und müssen sich nicht erneut mit den Berechtigungen einverstanden erklären, es sei denn, sie melden sich ab oder widerrufen die Berechtigungen.
Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist (Apps für Unternehmen)
Sie können ein neues Zugriffstoken anfordern, indem Sie das Aktualisierungstoken verwenden oder den Authentifizierungsprozess von Anfang an wiederholen.
Wenn ein Zugriffstoken abgelaufen ist, erhalten Sie bei Anforderungen an die API eine 401 Unauthorized-Antwort. Ihre App sollte diese Antwort verarbeiten und den Ablauf des Token überprüfen, bevor sie Anforderungen sendet.
Senden Sie die folgende HTTP-Anforderung mit einem korrekt kodierten URL-String im Nachrichtentext.
Diese URL in dem folgenden Beispiel verwendet den allgemeinen Mandantenendpunkt und gilt für eine beliebige Anwendung.
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}
| Benötigte Textparameter | Beschreibung |
|---|---|
| grant_type | Der Erteilungstyp der Anforderung. In diesem Fall ist es refresh_token. |
| client_id | Die für Ihre Anwendung erstellte Client-ID. |
| client_secret | Nur Webanwendungen und Web-APIs. Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| redirect_uri | Die Umleitungs-URL für Ihre Anwendung. |
| refresh_token | Das zuvor erhaltene Aktualisierungstoken. |
| Ressource | Die Ressource, auf die Sie zugreifen müssen. In diesem Fall ist https://onenote.com/ |
Wenn erfolgreich, enthält die Antwort auf die POST-Anforderung eine JSON-Zeichenfolge, die access_token und refresh_token enthält, wie im folgenden Beispiel gezeigt.
{
"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"
}
Aktualisieren Sie Ihre gespeicherten Token, um sicherzustellen, dass Ihre App Token mit der längsten Lebensdauer hat.
SDKs für die OneNote-Entwicklung
OneNote-Apps können das OneDrive API-SDK verwenden, um die Zugriffstoken zu erhalten, die für alle Anfragen an die OneNote-API erforderlich sind. Das SDK erleichtert Ihnen die Authentifizierung. Sie stellen lediglich Ihre Identitätsinformationen bereit und integrieren einige Aufrufe, und das SDK kümmert sich um alles, von der Anmeldung und Zustimmung bis hin zum Abrufen, Speichern und Aktualisieren von Token. Anschließend können Sie REST-Aufrufe an die OneNote-API durchführen. Unser iOS-Lernprogramm zeigt Ihnen, wie Sie das SDK in einer OneNote-App verwenden können.
Alle Versionen des SDK unterstützen die Microsoft-Kontenauthentifizierung (für Consumer-Notebooks) und einige unterstützen auch Azure Active Directory (für Unternehmens-Notebooks). Die aktuelle Liste der unterstützten Plattformen finden Sie in der OneDrive-Dokumentation.
Hinweis
Das OneDrive API SDK ersetzt das Live SDK. Das Live-SDK ist veraltet, wird aber weiterhin bestehende OneNote-Anwendungen, die es verwenden, unterstützen. Verwenden Sie für die neue Entwicklung das OneDrive API SDK.
Zu einem bestimmten Zeitpunkt können wir Bibliotheken bereitstellen, die sowohl die Authentifizierung als auch systemeigene Aufrufe der OneNote-API unterstützen, doch Sie können jetzt das OneDrive API-SDK verwenden.
Unternehmens-Apps können auch die Active Directory-Authentifizierungsbibliothek (ADAL) verwenden, um auf von Office 365 und SharePoint gehostete Notebooks zuzugreifen. Sie können ADAL direkt verwenden, wenn für Ihre Plattform kein SDK verfügbar ist oder wenn Sie mehr Kontrolle über den Authentifizierungsprozess wünschen. Unser ASP.NET MVC-Lernprogramm zeigt Ihnen, wie Sie ADAL in einer OneNote-App verwenden können.
Wichtig
Für die Interaktion mit OneNote-Inhalten und -Ressourcen sollten Sie immer die OneNote-API verwenden. Verwenden Sie nicht die OneDrive-API.
Fehler
Wenn Fehler bei der Authentifizierung auftreten, wird der Webbrowser zu einer Fehlerseite umgeleitet. Die Fehlerseite zeigt immer eine benutzerfreundliche, für Endbenutzer lesbare Meldung. Die für die Seite umfasst jedoch weitere Parameter, die Ihnen beim Debuggen helfen können. Die URL-Parameter werden z. B. als Lesezeichen eingebunden: #error={error_code}&error_description={message}
Wenn der Benutzer sich entscheidet, Ihrer Anwendung keine Genehmigung zu erteilen, wird der Ablauf auf Ihre Umleitungs-URL umgeleitet und enthält die Fehlerparameter.
Weitere Informationen zum Umgang mit Fehlern finden Sie in Fehlerhandhabung in OAuth 2.0.