OneDrive for Business-Authentifizierung und -Anmeldung
Verwenden von Microsoft Graph
Dieses Thema enthält Informationen zur Autorisierung einer Anwendung mit Microsoft-Konten für OneDrive Personal. Dieser Ansatz wird jedoch nicht mehr empfohlen. Neue Anwendungen sollten mit Microsoft Graph entwickelt werden und dem Autorisierungsprozess in Authorization and sign-in for OneDrive in Microsoft Graph (Autorisierung und Anmeldung für OneDrive in Microsoft Graph) folgen.
Verwenden von Azure Active Directory für die Authentifizierung
Um die OneDrive-API mit OneDrive for Business zu verwenden, müssen Sie über ein Zugriffstoken verfügen, mit dem Ihre App mit einer bestimmten Reihe von Berechtigungen für einen Benutzer authentifiziert wird.
Die Konfiguration einer Anwendung für den Zugriff auf OneDrive for Business ist eine Herausforderung. Wir arbeiten an der Vereinfachung dieses Prozess und bitten um Geduld.
In diesem Abschnitt erfahren Sie, wie Sie:
Die OneDrive-API verwendet das standardmäßige OAuth 2.0-Authentifizierungsschema zum Authentifizieren von Benutzern und Generieren von Zugriffstokens. Sie stellen ein Zugriffstoken für jeden API-Aufruf über einen HTTP-Header bereit:
Authorization: bearer {token}
Sie greifen auf die API zu, indem Sie HTTP-Anforderungen an eine bestimmte Endpunkt-URL senden.
Die Stamm-URL basiert auf dem Hostnamen des Servers, der als REST-Endpunkt dient.
Sie können die Such-API verwenden, um Endpunkte für Office 365-Dienste zu finden.
Weitere Informationen finden Sie in Common endpoint discovery tasks using the Discovery Service API (Allgemeine Endpunkt-Suchaufgaben mit der Ermittlungsdienst-API).
Ihre Stamm-URL erscheint im nächsten Beispiel, in dem {tenant} auf Ihre gefundene Endpunkt-URL zurückzuführen ist.
https://{tenant}-my.sharepoint.com/_api/v2.0/
Registrieren Ihrer App mit Azure Active Directory
Bevor Sie sich anmelden können, müssen Sie Ihre App mit Azure Active Directory registrieren und die Berechtigungen festlegen, die Ihre App erfordert. Weitere Informationen finden Sie unter Register your app for SharePoint Server 2016 or OneDrive for Business (Registrieren Ihrer App für SharePoint Server 2016 oder OneDrive for Business).
Anmelden bei OneDrive for Business
Wenn Sie sich erstmals bei OneDrive for Business anmelden, benötigt Ihre App die folgenden Werte:
- Client-ID und Schlüssel (geheimer Clientschlüssel), wie bei Azure Active Directory (AAD) registriert
- Autorisierungscode, der vom OAuth 2-Autorisierungscodefluss erhalten wurde
- OneDrive for Business-API-Endpunkt-URL
- Zugriffstoken für die OneDrive for Business-Ressource
- Aktualisierungstoken, um zusätzliche Zugriffstokens zu generieren, wenn das aktuelle Token abläuft
Die folgenden Schritte führen Sie durch die nötigen Anforderungen, um alle diese Werte zu erhalten.
Der Fluss folgt standardmäßigen OAuth 2.0-Authentifizierungsflüssen und erfordert Aufrufe von einem Webbrowser oder Webbrowser-Steuerelement. Sehen Sie sich den Überblick zu Office 365-App-Authentifizierungskonzepten an, um allgemeine Informationen zur Office 365-Authentifizierung zu erhalten. Um alle erforderlichen Werte für die Verwendung der OneDrive for Business-API zu erhalten, sind jedoch weitere Schritte erforderlich.
Der Codefluss für die Authentifizierung ist ein Prozess mit drei Schritten mit separaten Aufrufen zum Authentifizieren und Autorisieren der Anwendung und zum Generieren eines Zugriffstokens zum Verwenden der OneDrive-API. Dieser Prozess erstellt und sendet zudem ein Aktualisierungstoken an Ihre Anwendung. Mit dem Aktualisierungstoken ist eine langfristige Verwendung der API möglich, wenn der Benutzer Ihre Anwendung nicht aktiv verwendet.
Jedes Zugriffstoken, das von Azure Active Directory generiert wird, gilt speziell für eine einzige Ressource. Um den OneDrive for Business-API-Endpunkt zu finden und Aufrufe an diesen Endpunkt zu senden, benötigen Sie zwei Zugriffstokens, eins für jeden API-Endpunkt (Ressource).
Ein einzelnes Aktualisierungstoken kann verwendet werden, um Zugriffstokens für jeden Endpunkt zu generieren, auf den Ihre App zugreifen darf.
Schritt 1: Anmelden und Anfordern eines Autorisierungscodes
Zunächst lädt Ihre App den allgemeinen Azure Active Directory OAuth 2-Endpunkt in einem Webbrowser, der den Benutzer auffordert, sich mit seinen Anmeldeinformationen anzumelden. Diese URL verwendet den allgemeinen Mandantenendpunkt und gilt für eine beliebige Anwendung.
GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}
Erforderliche Parameter der Abfragezeichenfolge
| Parametername | Wert | Beschreibung |
|---|---|---|
| client_id | string | Die für Ihre App erstellte Client-ID. |
| response_type | string | Specifies the requested response type. In an authorization code grant request, the value must be code. |
| redirect_uri | string | Die Umleitungs-URL, an die der Browser gesendet wird, wenn die Authentifizierung abgeschlossen ist. |
Hinweis Die Umleitungs-URI muss einer der Umleitungs-URIs entsprechen, die Sie im Azure-Verwaltungsportal angegeben haben.
Antwort
Bei erfolgreicher Authentifizierung des Benutzers und Autorisierung Ihrer Anwendung wird der Webbrowser – wie im nächsten Beispiel gezeigt – zu Ihrer Umleitungs-URL umgeleitet und es werden zusätzliche Parameter zur URL hinzugefügt.
https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...
Der Code-Abfragezeichenfolgenwert ist der Autorisierungscode, den Sie für den nächsten Schritt benötigen.
Schritt 2: Einlösen des Autorisierungscodes für Tokens
Nachdem Sie den code-Wert erhalten haben, können Sie diesen Code für einen Satz von Tokens einlösen, die Ihnen die Authentifizierung bei verschiedenen Office 365-APIs ermöglichen.
Senden Sie zum Einlösen des Codes eine Anforderung an den Token-Endpunkt für Azure Active Directory, wie im Beispiel gezeigt:
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code&resource={resource_id}
Der Text für diese Anforderung ist eine URL-codierte Zeichenfolge mit den folgenden erforderlichen Parametern:
| Parametername | Wert | Beschreibung |
|---|---|---|
| client_id | string | Der für Ihre Anwendung erstellte Client-ID-Wert. |
| redirect_uri | string | Die Umleitungs-URL, an die der Browser gesendet wird, wenn die Authentifizierung abgeschlossen ist. Diese sollte mit dem redirect_uri-Wert übereinstimmen, der in der ersten Anforderung verwendet wird. |
| client_secret | string | Einer der für die Anwendung erstellten Schlüsselwerte. |
| code | string | Der Autorisierungscode, den Sie in der ersten Authentifizierungsanforderung erhalten haben. |
| resource | string | Die Ressource, auf die Sie zugreifen möchten. |
In den meisten Fällen ist die OneDrive for Business-API-Endpunkt-URL nicht bekannt.
Um die Endpunkt-URL zu ermitteln, müssen Sie einen Aufruf an die Office 365-Such-API durchführen.
Um sich bei der Such-API zu authentifizieren, müssen Sie ein Zugriffstoken für Ressource https://api.office.com/discovery/ anfordern.
Vergewissern Sie sich, dass Sie das nachstehende „/“-Zeichen eingeben, da Ihre App andernfalls keinen Zugriff auf die Such-API erhält.
Antwort
Wenn der Aufruf erfolgreich ist, ist der Antworttext eine JSON-Zeichenfolge, die access_token-, expires_in- und refresh_token-Eigenschaften umfasst.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Hinweis: In der Antwort können zusätzliche Eigenschaften enthalten sein. Diese Eigenschaften sind für die Verwendung der APIs nicht erforderlich.
Wichtig: Behandeln Sie die Werte von access_token und refresh_token mit dem Maß an Sicherheit, das Sie auch bei einem Benutzerpasswort anwenden.
Das Zugriffstoken gilt nur für die Anzahl von Sekunden, die in der Eigenschaft expires_in angegeben sind. Sie können ein neues Zugriffstoken anfordern, indem Sie das Aktualisierungstoken verwenden oder die Authentifizierungsanforderung von vorne wiederholen.
Schritt 3: Ermitteln der OneDrive for Business-Ressourcen-URI
Da verschiedene Benutzer und Mandanten eine andere URL verwenden, um den API-Zugriff zu ermöglichen, muss Ihre App die URL für die OneDrive for Business-Instanz des angemeldeten Benutzers ermitteln. Dafür kann Ihre App die Office 365-Such-API verwenden, um eine Liste von Diensten und API-Endpunkten anzufordern, die für Ihre App und den angemeldeten Benutzer verfügbar sind.
Durch Verwendung eines Zugriffstokens, den Sie für Ressource https://api.office.com/discovery/ erhalten haben, können Sie eine Anforderung an die Such-API senden, um zu erfahren, welche Services verfügbar sind:
GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}
| Parametername | Wert | Beschreibung |
|---|---|---|
| access_token | string | Ein gültiges Zugriffstoken für Ressource https://api.office.com/discovery/ |
Antwort
Wenn der Aufruf erfolgreich ist, enthält der Antworttext JSON-Daten mit Informationen über die Dienste, die für den Benutzer und Ihre App verfügbar sind. Sie können diese Antwort zerlegen, um die Endpunkt-URL für die OneDrive for Business-API zu finden.
{
"@odata.context": "https:\/\/api.office.com\/discovery\/v1.0\/me\/$metadata#allServices",
"value": [
{
"@odata.type": "#Microsoft.DiscoveryServices.ServiceInfo",
"capability": "MyFiles",
"serviceApiVersion": "v2.0",
"serviceEndpointUri": "https:\/\/contoso-my.sharepoint.com\/_api\/v2.0",
"serviceResourceId": "https:\/\/contoso-my.sharepoint.com\/"
}
]
}
Hinweis: Weitere Eigenschaften werden im ServiceInfo-Objekt ausgegeben. Dieses Beispiel ist auf die wichtigsten Eigenschaften gekürzt.
Um die Endpunkt-URL für die OneDrive for Business-Instanz des Benutzers zu ermitteln, müssen Sie das ServiceInfo-Objekt in der value-Sammlung finden, das dem folgenden Prädikat entspricht.
capability = "MyFiles" AND serviceApiVersion = "v2.0"
Wenn Ihre App ein passendes ServiceInfo-Objekt für die OneDrive for Business-Instanz des Benutzers findet, müssen Sie den Wert von zwei Eigenschaften dieses Objekts speichern: serviceResourceId und serviceEndpointUri. Diese Werte werden in den nächsten Schritten zur Beschaffung eines neuen Zugriffstokens und zum Senden von OneDrive-API aufrufen verwendet.
Schritt 4: Einlösen eines Aktualisierungstokens für ein Zugriffstoken zum Aufrufen der OneDrive-API
Nun, da Ihre App die URL der Ressource und des Endpunkts für die OneDrive for Business-Instanz des Benutzers kennt, kann das in Schritt 2 erhaltene Aktualisierungstoken für ein Zugriffstoken eingelöst werden, das mit der OneDrive-API verwendet werden kann.
Das Einlösen des Aktualisierungstokens für ein neues Zugriffstoken erfolgt mittels folgender Anforderung:
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token&resource={resource_id}
Der Anforderungstext ist eine URL-codierte Zeichenfolge mit den folgenden erforderlichen Parametern:
| Parametername | Wert | Beschreibung |
|---|---|---|
| client_id | string | Die für Ihre Anwendung erstellte Client-ID. |
| redirect_uri | string | The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri value used in the first request. |
| client_secret | string | Einer der für die Anwendung erstellten Schlüsselwerte. |
| refresh_token | string | Das zuvor erhaltene Aktualisierungstoken. |
| resource | string | Die Ressource, auf die Sie zugreifen möchten. Dies sollte der zuvor ermittelte ServiceResourceId-Wert sein. |
Hinweis Der Umleitungs-URI muss mit dem Umleitungs-URI übereinstimmen, den Sie im Azure-Verwaltungsportal angegeben haben.
Antwort
Wenn der Aufruf erfolgreich ist, ist der Antworttext eine JSON-Zeichenfolge, die access_token, expires_in und refresh_token umfasst.
{
"expires_in": 3600,
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Hinweis: Ersetzen Sie die Werte von Aktualisierungstokens, die Sie zuvor gespeichert haben, mit den bei nachfolgenden Aufrufen des Token-Diensts erhaltenen Werten, um sicherzustellen, dass Ihre App über ein Token mit der längsten Laufzeit verfügt.
Der Wert der access_token-Eigenschaft kann jetzt für authentifizierte Anforderungen an die OneDrive-API verwendet werden. Weitere Informationen zu Aktualisierungstokens finden Sie in Refresh Tokens for Multiple Resources (Aktualisierungstokens für mehrere Ressourcen).
Wichtig: Behandeln Sie die Werte von access_token und refresh_token mit dem Maß an Sicherheit, das Sie auch bei einem Benutzerpasswort anwenden.
Das Zugriffstoken gilt nur für die Anzahl von Sekunden, die in der Eigenschaft expires_in angegeben sind (in der Regel 1 Stunde). Sie können ein neues Zugriffstoken anfordern, indem Sie das Aktualisierungstoken verwenden (sofern verfügbar) oder die Authentifizierungsanforderung von vorne wiederholen.
Wenn das Zugriffstoken abgelaufen ist, erhalten Sie bei Anforderungen an die API eine 401 Unauthorized-Antwort.
Wenn Sie diese Antwort bei einer authentifizierten Anforderung erhalten, sollten Sie mithilfe Ihres gespeicherten Aktualisierungstokens ein neues Zugriffstoken erstellen.
Schritt 5: Senden einer neuen Anforderung an die OneDrive-API
Da Ihre App nun über ein Zugriffstoken verfügt, das für den OneDrive for Business API-Endpunkt des Benutzers gültig ist, kann sie eine authentifizierte Anforderung an die OneDrive-API senden.
Um die Anforderung zu machen, benötigen Sie den aus der Such-API abgerufenen serviceEndpointUri-Wert und das vom Token-Dienst erhaltene Zugriffstoken.
Um beispielsweise Details zum OneDrive for Business des Benutzers zu erhalten, können Sie eine Anforderung an den /drive-API-Pfad senden:
GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}
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 Fehlerseite umfasst weitere Informationen, die Ihnen beim Debugging helfen können. Diese Art von Informationen ist nicht immer auf der Fehlerseite enthalten, die im Browser angezeigt wird.
Die URL enthält Abfrageparameter, die Sie verwenden können, um den Fehler zu analysieren und entsprechend zu reagieren.
Diese Parameter sind immer als Textmarke enthalten (nach dem #-Zeichen).
Die Seite enthält immer eine generische Fehlermeldung für den Benutzer.
Wenn der Benutzer Ihrer Anwendung keine Genehmigung erteilt, werden Sie vom Fluss zu Ihrer redirect_uri umgeleitet und es sind dieselben Fehlerparameter enthalten.
Weitere Informationen zum Umgang mit Fehlern erhalten Sie in Error Handling in OAuth 2.0 (Fehlerhandhabung in OAuth 2.0).
Verwandte Themen
Die folgenden Themen enthalten einen allgemeinen Überblick über andere Konzepte, die mit der OneDrive-API verbunden sind.