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

Authentifizierung und Azure AD-Anwendungsberechtigungen

Gilt für: Unternehmens-Notizbücher auf Office 365

Authentifizierung mit Azure AD (Apps für Unternehmen)

  1. Ihre Anwendung registrieren und eine Client-ID und einen geheimen Schlüssel abrufen
  2. Wählen Sie OneNote Anwendungsberechtigungsbereiche
  3. Zustimmung des Administrators einholen
  4. Abrufen eines Zugriffstokens
  5. Ein neues Zugriffstoken erhalten, nachdem es abgelaufen ist

Ihre Anwendung registrieren und eine Client-ID und einen geheimen Schlüssel abrufen (Apps für Unternehmen)

Siehe Ihre Anwendung registrieren und eine Client-ID und einen geheimen Schlüssel abrufen.

Wählen Sie OneNote-Anwendungsberechtigungsbereiche wählen (Apps für Unternehmen)

Berechtigungsbereiche stellen Zugriffsebenen auf OneNote-Inhalte dar. Eine Anwendungsberechtigung wird einer Anwendung vom Administrator einer Organisation erteilt und kann nur für den Zugriff auf Daten verwendet werden, die dieser Organisation und ihren Mitarbeitern gehören. Die OneNote-API stellt beispielsweise mehrere Anwendungsberechtigungen zur Verfügung, um Folgendes zu tun:

  • Notizen für alle Benutzer anzeigen
  • Anzeigen und Ändern von Notizen für alle Benutzer

Führen Sie die folgenden Schritte aus, um Ihrer Anwendung OneNote-Anwendungsberechtigungen zuzuweisen:

  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 Anwendungsberechtigungen

Wenn Sie mit Anwendungsberechtigungen auf Notebooks zugreifen, wählen Sie aus den folgenden Bereichen.

Bereich (Unternehmen)Berechtigung im Azure-PortalBeschreibung
Notes.Read.AllNotizen für alle Benutzer anzeigenErmöglicht es der App, die OneNote-Notizen aller Benutzer in Ihrer Organisation ohne einen angemeldeten Benutzer anzuzeigen. Die App kann keine neuen Notizen erstellen, bestehende Notizen ändern oder Notizen in passwortgeschützten Bereichen anzeigen.
Notes.ReadWrite.AllAnzeigen und Ändern von Notizen für alle BenutzerErmöglicht es der App, die OneNote-Notizen aller Benutzer in Ihrer Organisation ohne einen angemeldeten Benutzer anzuzeigen und zu ändern. Die App kann nicht auf Notizen in passwortgeschützten Bereichen zugreifen.

Empfohlen: Melden Sie den Benutzer in Ihrer App an

Wenn Sie eine Anwendung erstellen, die Anwendungsberechtigungen verwendet, benötigt die Anwendung normalerweise eine Seite oder Ansicht, auf der der Administrator die Berechtigungen der Anwendung genehmigt. Diese Seite kann Teil des Anmeldeablaufs der App sein, Teil der Einstellungen der App, oder es kann ein eigener "connect"-Ablauf sein. In vielen Fällen ist es sinnvoll, dass die App diese "Connect"-Ansicht erst dann anzeigt, wenn sich ein Benutzer mit einem Arbeits- oder Schulkonto bei Microsoft angemeldet hat.

Wenn Sie den Benutzer in Ihrer App anmelden, können Sie die Organisation identifizieren, zu der der Benutzer gehört, bevor Sie ihn bitten, die Anwendungsberechtigungen zu genehmigen. Obwohl es nicht unbedingt notwendig ist, kann es Ihnen helfen, ein intuitiveres Erlebnis für Ihre Benutzer zu schaffen. Um den Benutzer anzumelden, folgen Sie unseren v2.0 Protokoll-Tutorials.

Anfordern der Berechtigungen von einem Directory-Administrator

Wenn Sie bereit sind, Berechtigungen vom Administrator der Organisation anzufordern, können Sie den Benutzer zum Endpunkt der Administrator-Zustimmung umleiten. Sie können den API-Aufruf wie folgt durchführen:

// Line breaks are for legibility only.

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

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

Sie können die obige Anfrage auch in einem Browser ausprobieren, geben Sie die folgende URL in die Adressleiste Ihres Browsers ein (erstellen Sie eine gültige URL nach den Anweisungen unten).

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

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

Die folgende Tabelle beschreibt die in der obigen Anforderung verwendeten Parameter:

ParameterBedingungBeschreibung
tenantErforderlichDer Directory-Mandant, von dem Sie die Erlaubnis anfordern möchten. Dies kann im GUID- oder im benutzerfreundlichen Namensformat erfolgen. Wenn Sie nicht wissen, zu welchem Mandanten der Benutzer gehört und Sie ihn mit einem beliebigen Mandanten anmelden lassen möchten, verwenden Sie common.
client_idErforderlichDie Anwendungs-ID, die Ihrer App vom App-Registrierungsportal zugewiesen wurde.
redirect_uriErforderlichDer Umleitungs-URI, an den die Antwort für die Weiterarbeitung durch Ihre App gesendet werden soll. Er muss genau mit einem der Umleitung-URIs übereinstimmen, die Sie im Portal registriert haben, mit der Ausnahme, dass er URL-codiert sein muss und zusätzliche Pfadsegmente enthalten kann.
stateEmpfohlenEin Wert, der in der Anforderung enthalten ist und ebenfalls in der Tokenantwort zurückgegeben wird. Es kann eine Zeichenfolge beliebigen Inhalts sein. Der Status wird verwendet, um Informationen über den Status des Benutzers in der App vor dem Versand der Authentifizierungsanforderung zu codieren, z. B. die Seite oder die Ansicht, auf bzw. in der sich der Benutzer befunden hat.

Sie erhalten einen Administrator-Zustimmungsdialog, den Sie genehmigen können.

Erfolgreiche Antwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung genehmigt, sieht die erfolgreiche Antwort wie folgt aus:

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

Die folgende Tabelle beschreibt die in der obigen Antwort zurückgegebenen Werte:

ParameterBeschreibung
tenantDer Verzeichnismandant, der Ihrer Anwendung die angeforderten Berechtigungen gewährt hat, im GUID-Format.

Fehlerantwort

Wenn der Administrator die Berechtigungen für Ihre Anwendung nicht genehmigt, sieht die fehlgeschlagene Antwort so aus:

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

Additional technical information: 
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988 
Timestamp: 2017-01-18 05:36:57Z 
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators. 

Die folgende Tabelle beschreibt die in der obigen Antwort zurückgegebenen Werte:

ParameterBeschreibung
tenantDer Verzeichnismandant, der Ihrer Anwendung die angeforderten Berechtigungen gewährt hat, im GUID-Format.

Nachdem Sie eine erfolgreiche Antwort vom App-Provisioning-Endpunkt erhalten haben, hat Ihre Anwendung die von ihr angeforderten direkten Anwendungsberechtigungen erhalten. Nun können Sie einen Token für die gewünschte Ressource anfordern.

Hinweise:

  1. Die Einwilligung des Administrators ist ein einmaliger Schritt für einen bestimmten Mandanten
  2. Wenn Ihre Anwendung in anderen Mandanten laufen soll, müssen Sie sie als Anwendung mit mehreren Mandanten in AAD konfigurieren
  3. Unabhängig davon, ob die Anwendung in einem eigenen oder einem anderen Mandanten läuft, ist die Zustimmung des Administrators ein notwendiger Schritt
  4. Ihre Anwendung kann zusätzlich zu den Anwendungsberechtigungen auch Delegate-Berechtigungen wählen (die Zustimmung des Administrators ist jedoch weiterhin erforderlich)

Zugriffstoken abrufen (Unternehmens-App)

Nachdem Sie die erforderliche Berechtigung für Ihre Anwendung erworben haben, fahren Sie mit dem Erwerb von Zugriffstoken für APIs fort. Um ein Token unter Verwendung der Client-Anmeldeinformationen zu erhalten, senden Sie eine POST-Anfrage wie unten beschrieben:

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

POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F

Die folgende Tabelle beschreibt die in der obigen Anforderung verwendeten Parameter:

ParameterBedingungBeschreibung
grant_typeErforderlichMuss client_credentials sein.
client_idErforderlichDie Anwendungs-ID, die Ihrer App vom App-Registrierungsportal zugewiesen wurde.
client_secretErforderlichDas Anwendungsgeheimnis, das Sie im App-Registrierungsportal für Ihre App generiert haben. Es ist sehr wichtig, dass diese URL verschlüsselt ist
resourceErforderlichDer Wert, der für den resource Parameter in dieser Anforderung übergeben wird, sollte der Ressourcen-Bezeichner (Anwendungs-ID-URI) der gewünschten Ressource sein. Für die OneNote-API ist der Wert https://onenote.com/. Dieser Wert teilt dem Token-Endpunkt mit, dass er von allen direkten Anwendungsberechtigungen, die Sie für Ihre Anwendung konfiguriert haben, ein Token für diejenigen ausgeben sollte, die mit der Ressource verknüpft sind, die Sie verwenden möchten.

Erfolgreiche Antwort

Eine erfolgreiche Antwort sieht wie folgt aus:

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

Die folgende Tabelle beschreibt die in der obigen Antwort zurückgegebenen Werte:

ParameterBeschreibung
token_typeGibt den Tokentypwert an. Der einzige von Azure AD unterstützte Typ ist bearer.
expires_inGültigkeit des Zugriffstokens (in Sekunden).
resourceDer Resssourcen-Bezeichner (Anwendungs-ID-URI) der Ressource, gegen die dieses Token verwendet werden kann.
access_tokenDas angeforderte Zugriffstoken. Die Anwendung kann dieses Token verwenden, um sich bei der gesicherten Ressource, z.B. bei einer Web-API, zu authentifizieren.

Fehlerantwort

Eine Fehlerantwort sieht so aus (in diesem Beispiel wird ein ungültiger Wert für client_secret in der Anforderung angegeben):

{
  "error": "invalid_client",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
  "error_codes": [
    70002,
    50012
  ],
  "timestamp": "2017-01-19 20:34:11Z",
  "trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
  "correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}

Die folgende Tabelle beschreibt die in der obigen Antwort zurückgegebenen Werte:

ParameterBeschreibung
errorEine Fehlercode-Zeichenfolge, mit der Sie auftretende Fehlerarten klassifizieren und auf Fehler reagieren können.
error_descriptionEine spezielle Fehlermeldung, die Ihnen helfen könnte, die Grundursache eines Authentifizierungsfehlers zu identifizieren.
error_codesEine Liste von STS-spezifischen Fehlercodes, die bei der Diagnose helfen können.
timestampDer Zeitpunkt, an dem der Fehler aufgetreten ist.
trace_idEin eindeutiger Bezeichner für die Anforderung, die bei der Diagnose helfen könnte.
correlation_idEin eindeutiger Bezeichner für die Anfrage, der bei der komponentenübergreifenden Diagnose helfen kann.

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/users/foo@example.com/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. Administratoren müssen die Berechtigungen nicht erneut genehmigen, es sei denn, sie widerrufen die Berechtigungen.

Ein neues Zugriffstoken abrufen, nachdem es abgelaufen ist (Apps für Unternehmen)

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.

Sie können ein neues Zugriffstoken anfordern, indem Sie den im Abschnitt Ein Zugriffstoken abrufen eher in diesem Thema beschriebenen Vorgang wiederholen.

Aktualisieren Sie Ihre gespeicherten Token, um sicherzustellen, dass Ihre App Token mit der längsten Lebensdauer hat.

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 Administrator Ihrer Anwendung keine Genehmigung erteilt, werden Sie vom Ablauf 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