Authentifizierung und Azure AD-Anwendungsberechtigungen
Gilt für: Unternehmensnotizbücher auf Office 365
So authentifizieren Sie mit Azure AD (Apps für Unternehmen):
- Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten
- OneNote-Anwendungsberechtigungsbereiche auswählen
- Zustimmung des Administrators einholen
- Ein Zugriffstoken abrufen
- 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 diese Schritte aus, um Ihrer Anwendung OneNote-Anwendungsberechtigungen zuzuweisen:
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 Anwendungsberechtigungen
Wenn Sie mit Anwendungsberechtigungen auf Notebooks zugreifen, wählen Sie aus den folgenden Bereichen.
| Bereich (Unternehmen) | Berechtigung im Azure-Portal | Beschreibung |
|---|---|---|
| Notes.Read.All | Notizen für alle Benutzer anzeigen | Ermö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.All | Anzeigen und Ändern von Notizen für alle Benutzer | Ermö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. |
Zustimmung des Administrators einholen
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. Folgen Sie unseren v2.0 Protokoll-Lernprogrammen, um den Benutzer anzumelden.
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 Azure AD assigned application id
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://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 nachstehenden Anweisungen).
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions
Diese Tabelle beschreibt die in der vorherigen Anforderung verwendeten Parameter:
| Parameter | Bedingung | Beschreibung |
|---|---|---|
| Mandant | Erforderlich | Der Directory-Mandant, von dem Sie die Berechtigung 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_id | Erforderlich | Die Anwendungs-ID, die Ihrer App vom App-Registrierungsportal zugewiesen wurde. |
| redirect_uri | Erforderlich | Der 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. |
| Zustand | Empfohlen | Ein 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
Diese Tabelle beschreibt die in der vorherigen Antwort zurückgegebenen Werte:
| Parameter | Beschreibung |
|---|---|
| Mandant | Der Directory-Mandant, 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.
Diese Tabelle beschreibt die in der vorherigen Antwort zurückgegebenen Werte:
| Parameter | Beschreibung |
|---|---|
| Mandant | Der Directory-Mandant, 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.
Hinweis
- Die Zustimmung des Administrators ist ein einmaliger Schritt für einen bestimmten Mandanten.
- Wenn Ihre Anwendung in anderen Mandanten laufen soll, müssen Sie sie in Azure AD als Anwendung mit mehreren Mandanten konfigurieren.
- Unabhängig davon, ob die Anwendung in einem eigenen oder einem anderen Mandanten läuft, ist die Zustimmung des Administrators ein notwendiger Schritt
- 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.
Senden Sie, um ein Token unter Verwendung der Client-Anmeldeinformationen zu erhalten, wie nachstehend beschrieben, eine POST-Anfrage:
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
// Replace {app_secret} with an Azure AD 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
Diese Tabelle beschreibt die in der vorherigen Anforderung verwendeten Parameter:
| Parameter | Bedingung | Beschreibung |
|---|---|---|
| grant_type | Erforderlich | Muss client_credentials sein. |
| client_id | Erforderlich | Die Anwendungs-ID, die Ihrer App vom App-Registrierungsportal zugewiesen wurde. |
| client_secret | Erforderlich | Der geheime Schlüssel der Anwendung, den Sie im App-Registrierungsportal für Ihre App generiert haben. Es ist sehr wichtig, dass diese URL verschlüsselt ist |
| Ressource | Erforderlich | Der 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..."
}
Diese Tabelle beschreibt die in der vorherigen Anforderung verwendeten Werte:
| Parameter | Beschreibung |
|---|---|
| token_type | Gibt den Tokentypwert an. Der einzige von Azure AD unterstützte Typ ist bearer. |
| expires_in | Gültigkeit des Zugriffstokens (in Sekunden). |
| Ressource | Der Resssourcen-Bezeichner (Anwendungs-ID-URI) der Ressource, gegen die dieses Token verwendet werden kann. |
| access_token | Das 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"
}
Diese Tabelle beschreibt die in der vorherigen Anforderung verwendeten Werte:
| Parameter | Beschreibung |
|---|---|
| Fehler | Eine Fehlercode-Zeichenfolge, mit der Sie auftretende Fehlerarten klassifizieren und auf Fehler reagieren können. |
| error_description | Eine spezielle Fehlermeldung, die Ihnen helfen könnte, die Grundursache eines Authentifizierungsfehlers zu identifizieren. |
| error_codes | Eine Liste von STS-spezifischen Fehlercodes, die bei der Diagnose helfen können. |
| Zeitstempel | Der Zeitpunkt, an dem der Fehler aufgetreten ist. |
| trace_id | Ein eindeutiger Bezeichner für die Anforderung, die bei der Diagnose helfen könnte. |
| correlation_id | Ein eindeutiger Bezeichner für die Anfrage, der bei der komponentenübergreifenden Diagnose helfen kann. |
Einschließen des Zugriffstokens in Ihre Anforderung an die OneNote-API
Alle Ihre Anforderungen an die OneNote-API müssen das Zugriffstoken als Bearer-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 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 Administrator Ihrer Anwendung keine Zustimmung erteilt, werden Sie vom Ablauf zu Ihrer Umleitungs-URL umgeleitet und es sind dieselben Fehlerparameter enthalten.
Weitere Informationen zum Umgang mit Fehlern finden Sie unter Fehlerhandhabung in OAuth 2.0.