Table of contents
TOC
Inhaltsverzeichnis reduzieren
Inhaltsverzeichnis erweitern
Zuletzt aktualisiert: 20.06.2018

OneNote-Authentifizierung und Berechtigungen

Gilt für: Consumer-Notizbücher auf OneDrive | Enterprise-Notizbücher auf 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.

Wählen Sie Ihre Plattform aus:


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.

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

Wenn Sie die APIs nur testen möchten, können Sie eine unserer interaktiven Konsolen verwenden, um Ihre Notizbücher für Consumer auf OneDrive anzurufen. Sie können auch den Schritten in diesem Artikel folgen, um ein Zugriffstoken mit Ihrem bevorzugten Netzwerktool z. B. Fiddler zu erhalten.

Authentifizierung mit Microsoft-Konto (Apps für Unternehmen)

  1. Ihre Anwendung registrieren und eine Client-ID und einen geheimen Schlüssel erhalten
  2. OneNote-Berechtigungen auswählen
  3. Benutzer anmelden und einen Zugangscode erhalten
  4. Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist

Ihre Anwendung registrieren und eine Client-ID und 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.

  1. 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.

  2. Wählen Sie Anwendung erstellen aus.

  3. 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.

  4. Wenn Sie die Nutzungsbedingungen und die Richtlinien zu Datenschutz und Cookies akzeptieren, klicken Sie auf Ich akzeptiere ,um mit der Registrierung fortzufahren.

  5. 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.

  1. Melden Sie sich im Windows Dev Center mit Ihrem Microsoft-Konto an.
  2. Wählen Sie im Dashboard Neue App erstellen und geben Sie Ihren App-Namen ein.
  3. 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.
  4. 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.
  5. 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_createZeigt 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_appErstellt alle von der App erstellten Seiten, zeigt sie an und ändert sie.
office.onenote_updateErstellt beliebige Inhalte in den OneNote-Notizbüchern und -Seiten des Benutzers, zeigt sie an und ändert sie.
office.onenoteZeigt OneNote-Notizbücher und -Seiten an, verändert sie jedoch nicht.
wl.signinEin Microsoft-Konto-Berechtigungsbereich.
Ermöglicht Ihrer Anwendung die Nutzung der Vorteile der Funktionen des einmaligen Anmeldens.
wl.offline_zugangEin 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 nicht für den Tokenfluss 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.

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.

FlussBeschreibung
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 Abfrage-Zeichenfolge-ParameterBeschreibung
response_typeDie Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Token.
client_idDie für Ihre Anwendung erstellte Client-ID.
redirect_uriDie 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
BereichDie 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. Zu den Parametern gehören
dasaccess_token und token_type, 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:

  1. Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode.
  2. Ersetzen Sie den Autorisierungscode 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 Abfrage-Zeichenfolge-ParameterBeschreibung
response_typeDie Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Code.
client_idDie für Ihre Anwendung erstellte Client-ID.
redirect_uriDie 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
BereichDie 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 für 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 TextparameterBeschreibung
grant_typeDer Erteilungstyp der Anforderung. In diesem Fall ist es authorization_code.
client_idDie für Ihre Anwendung erstellte Client-ID.
client_secretDer für Ihre Anwendung erstellte geheime Clientschlüssel.
CodeDer Code, den Sie im vorherigen Schritt als URL-Parameter erhalten haben.
redirect_uriDie Umleitungs-URL für Ihre Anwendung. Dies muss mit redirect_uri in der ersten Anfrage übereinstimmen.

Wenn erfolgreich, enthält die Antwort eine JSON-Zeichenfolge, der access_token und refresh_token enthält, wenn Sie den Bereichwl.offline_access 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 vorne 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 TextparameterBeschreibung
grant_typeDer Erteilungstyp der Anforderung. In diesem Fall ist es refresh_token.
client_idDie für Ihre Anwendung erstellte Client-ID.
client_secretDer für Ihre Anwendung erstellte geheime Clientschlüssel.
redirect_uriDie Umleitungs-URL für Ihre Anwendung. Dies muss mit der redirect_uri übereinstimmen, die Sie verwendet haben, um die Token zu erhalten.
refresh_tokenDas zuvor erhaltene Aktualisierungstoken.

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":"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:

  1. Löschen Sie alle zwischengespeicherten Zugriffstoken oder Aktualisierungstoken, die Sie erhalten oder gespeichert haben.
  2. Führen Sie alle Abmeldeaktionen in Ihrer Anwendung aus (beispielsweise das Bereinigen des lokalen Status, das Entfernen zwischengespeicherter Elemente usw.).
  3. 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 Abfrage-Zeichenfolge-ParameterBeschreibung
client_idDer für Ihre Anwendung erstellte Client-ID-Wert.
redirect_uriDie 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.

Widerrufen des Zugriffs

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 Authentifizierungsfluss 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), beziehen Sie sich bitte auf OneNote-Authentifizierung und Azure AD Anwendungsberechtigungen

  1. Ihre Anwendung registrieren und eine Client-ID und einen geheimen Schlüssel erhalten
  2. OneNote-Berechtigungen auswählen
  3. Benutzer anmelden und einen Zugangscode erhalten
  4. Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist

Ihrer Anwendung registrieren und eine Client-ID und 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 jemand@example.com oder jemand@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 ihre 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.

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.

  1. Melden Sie sich im Azure-Verwaltungsportal mit Ihren Office 365-Administrationsdaten an (ein Arbeits- oder Schulkonto wie jemand@example.com oder jemand@example.onmicrosoft.com).

  2. 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.

  1. Melden Sie sich bei dem Azure-Verwaltungsportal mit Ihren vorhandenen Microsoft-Konto-Anmeldeinformationen an (z. B. jemand@live.com).

  2. Wählen Sie in der Schublade unten auf der Seite Neu > App-Dienste > Active Directory > Verzeichnis > Benutzerdefiniert erstellen.

  3. Im Fenster Verzeichnis hinzufügen wählen Sie für das Verzeichnis Vorhandenes Verzeichnis verwenden.

  4. Wählen Sie Ich bin jetzt für die Abmeldung bereit, und klicken Sie auf das Häkchen. Das meldet Sie vom Portal ab.

  5. 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 jemand@example.com oder jemand@example.onmicrosoft.com).

  6. Wenn Sie gefragt werden, ob Sie das Verzeichnis mit Azure verwenden möchten, wählen Sie Weiter > Jetzt abmelden.

  7. Schließen Sie den Browser und öffnen Sie dann das Azure-Verwaltungsportal.

  8. 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

  1. Melden Sie sich am Microsoft Azure-Verwaltungsportal an. Verwenden Sie die Administrator-Anmeldeinformationen für Ihr Azure-Abonnement.

  2. Wählen Sie im Navigationsbereich Active Directory auswählen.

  3. Wählen Sie das Verzeichnis aus, in dem Sie Ihre Anwendung registrieren möchten, und öffnen Sie dann die Registerkarte Anwendungen.

  4. Wählen Sie in der Schublade unten auf der Seite Hinzufügen > Eine von meinem Unternehmen entwickelte Anwendung hinzufügen aus.

  5. 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.

  1. Wählen Sie im Abschnitt Azure-Verwaltungsportal, im Abschnitt Berechtigungen für andere Anwendungen auf der App-Konfigurationsseite Anwendung hinzufügen.

  2. 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.

  3. 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-PortalBeschreibung
Notes.CreateBenutzernotizen erstellen

Ermöglicht dem Benutzer, OneNote-Notizen für den angemeldeten Benutzer zu erstellen.

Der Benutzer kann vorhandene Seiten nicht anzeigen oder bearbeiten.

Notes.ReadWrite.CreatedByAppNotizen anzeigen und bearbeiten, die mit einer bestimmten Anwendung erstellt wurden

Ermöglicht dem Benutzer die mit dieser App erstellten OneNote-Notizen anzuzeigen und zu verändern.

Der Benutzer kann Notizen, die von anderen Apps oder in kennwortgeschützten Abschnitten erstellt wurden, nicht anzeigen oder ändern.

Notes.ReadBenutzernotizen anzeigen

Ermöglicht dem Benutzer, OneNote-Notizen für den angemeldeten Benutzer anzuzeigen.

Der Benutzer kann keine neuen Seiten erstellen, vorhandene Seiten ändern und auf kennwortgeschützte Abschnitte zugreifen.

Notes.ReadWriteBenutzernotizen anzeigen, ändern

Ermöglicht dem Benutzer, OneNote-Notizen für den angemeldeten Benutzer anzuzeigen und zu verändern.

Der Benutzer kann nicht auf kennwortgeschützte Abschnitte zugreifen.


Bereiche für Site- und Gruppen-Notizbücher, auf die der aktuelle Benutzer zugreifen kann

Wenn Sie mit SharePoint-Website-Notizbüchern oder Office 365-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-PortalBeschreibung
Notes.Read.AllBenutzernotizen und mit dem Benutzer geteilte Notizen anzeigen

Ermöglicht dem Benutzer, OneNote-Notizen anzuzeigen, auf die der angemeldete Benutzer in der Organisation Zugriff hat.

Der Benutzer kann keine neuen Seiten erstellen, vorhandene Seiten ändern und auf kennwortgeschützte Abschnitte zugreifen.

Notes.ReadWrite.AllBenutzernotizen und mit dem Benutzer geteilte Notizen anzeigen und bearbeiten

Ermöglicht dem Benutzer, OneNote-Notizen anzuzeigen und zu ändern, auf die der angemeldete Benutzer in der Organisation Zugriff hat.

Der Benutzer kann nicht auf kennwortgeschützte Abschnitte zugreifen.

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.

Abhängig von Ihrer Plattform können Sie eine SDK verwenden, um die Authentifizierungsflüsse zu vereinfachen.

Erhalten eines Zugriffstokens ist ein zweistufiger Prozess:

  1. Melden Sie den Benutzer an und Sie erhalten einen Autorisierungscode.
  2. Ersetzen Sie den Autorisierungscode 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 Abfrage-Zeichenfolge-ParameterBeschreibung
response_typeDie Art des von Ihnen verwendeten Authentifizierungsflusses. In diesem Fall ist es Code.
client_idDie für Ihre Anwendung erstellte Client-ID.
redirect_uriDie Umleitungs-URL für Ihre Anwendung.
RessourcenDie 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 für 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 TextparameterBeschreibung
grant_typeDer Erteilungstyp der Anforderung. In diesem Fall ist es authorization_code.
client_idDie für Ihre Anwendung erstellte Client-ID.
client_secretNur Webanwendungen und Web-APIs. Der für Ihre Anwendung erstellte geheime Clientschlüssel.
CodeDer Code, den Sie im vorherigen Schritt als URL-Parameter erhalten haben.
redirect_uriDie Umleitungs-URL für Ihre Anwendung. Dies muss mit redirect_uri in der ersten Anfrage übereinstimmen.
RessourcenDie 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 vorne 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 TextparameterBeschreibung
grant_typeDer Erteilungstyp der Anforderung. In diesem Fall ist es refresh_token.
client_idDie für Ihre Anwendung erstellte Client-ID.
client_secretNur Webanwendungen und Web-APIs. Der für Ihre Anwendung erstellte geheime Clientschlüssel.
redirect_uriDie Umleitungs-URL für Ihre Anwendung.
refresh_tokenDas zuvor erhaltene Aktualisierungstoken.
RessourcenDie 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.

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 für Endbenutzer lesbare Meldung, doch die URL für die Seite umfasst 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 Ihrer Anwendung keine Genehmigung erteilt, werden Sie vom Fluss zu Ihrer Umleitungs-URL umgeleitet und es sind dieselben Fehlerparameter enthalten.

Weitere Informationen zum Umgang mit Fehlern finden Sie in Fehlerhandhabung in OAuth 2.0.

Zusätzliche Ressourcen

© 2018 Microsoft