Authentifizierung und Azure AD-Anwendungsberechtigungen

Gilt für: Unternehmensnotizbücher auf Office 365

So authentifizieren Sie mit Azure AD (Apps für Unternehmen):

1. Ihre Anwendung registrieren und eine Client-ID sowie einen geheimen Schlüssel erhalten
2. OneNote-Anwendungsberechtigungsbereiche auswählen
3. Zustimmung des Administrators einholen
4. Ein Zugriffstoken abrufen
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 diese 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.

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:

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:

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:

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.

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:

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:

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:

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.

Siehe auch

• OneNote-Entwicklung
• Entwickeln mit den OneNote-APIs
• OneNote-Dev-Center
• OneNote-Entwicklerblog
• Fragen zur OneNote-Entwicklung auf Stack Overflow
• OneNote GitHub-Repos