Autorisierung und Anmeldung für OneDrive in Microsoft Graph
Um die OneDrive-API über Microsoft Graph zu verwenden, müssen Sie über ein Zugriffstoken verfügen, mit dem Ihre App mit einer bestimmten Reihe von Berechtigungen für einen Benutzer autorisiert wird. In diesem Abschnitt erfahren Sie, wie Sie:
- Ihre Anwendung registrieren, um eine Anwendungs-ID zu erhalten.
- Ihren Benutzer mithilfe des Tokenflusses oder Codeflusses bei den angegebenen Bereichen anmelden.
- Den Benutzer abmelden (optional).
Die OneDrive-API verwendet das standardmäßige OAuth 2.0-Autorisierungsframework zum Autorisieren von Apps und Generieren von Zugriffstokens. Sie müssen mithilfe eines HTTP-Headers ein Zugriffstoken für jeden authentifizierten API-Aufruf bereitstellen:
Authorization: bearer {token}
Hinweis: Das empfohlenen Autorisierungsframework verwendet den Azure AD v2.0-Endpunkt. In einigen Unternehmensszenarios muss jedoch der ursprüngliche Azure AD-Endpunkt verwendet werden. Weitere Informationen finden Sie unter App-Authentifizierung mit Microsoft Graph.
Registrieren der App
Der erste Schritt besteht darin, die App bei Microsoft zu registrieren und Details zu Ihrer App bereitzustellen. Sie können Ihre Anwendung registrieren und eine neue App-ID auf der Seite Azure-App Registrierungen erhalten.
Detaillierte Schritte zum Registrieren der Anwendung finden Sie im Artikel zur Registrierung Ihrer App für die OneDrive-API.
Benutzer anmelden
Ihre App muss den Anmeldevorgang initiieren, indem sie den Azure Active Directory-Autorisierungsendpunkt mit einem bestimmten Bereich kontaktiert. Der Fluss folgt standardmäßigen OAuth 2.0-Autorisierungsflüssen und erfordert Aufrufe von einem Webbrowser oder Webbrowser-Steuerelement. Das Ergebnis des Autorisierungsflusses stellt ein Zugriffstoken und optional weitere Tokens bereit, die Ihre App für den Zugriff auf die API verwenden kann.
Authentifizierungsbereiche
Bereiche bestimmen, welche Art von Zugriff der App gewährt wird, wenn der Benutzer angemeldet ist. Alle Bereiche unterstützen Single Sign-On im Web, was bedeutet, dass ein Benutzer, der bereits bei OneDrive angemeldet ist, den Authentifizierungsfluss überspringen und direkt zum Autorisierungsfluss übergehen kann.
| Bereichsname | Beschreibung |
|---|---|
| offline_access | Ermöglicht es Ihrer App, offline zu arbeiten, auch wenn der Benutzer nicht aktiv ist. Erfordert die Verwendung von Codefluss. |
| files.read | Gewährt die Berechtigung ausschließlich zum Lesen sämtlicher OneDrive-Dateien eines Benutzers. |
| files.read.all | Gewährt die Berechtigung ausschließlich zum Lesen sämtlicher OneDrive-Dateien eines Benutzers, einschließlich Dateien, die für den Benutzer freigegeben wurden. |
| files.readwrite | Gewährt Lese- und Schreibberechtigungen für alle OneDrive-Dateien eines Benutzers. |
| files.readwrite.all | Gewährt Lese- und Schreibberechtigungen für alle OneDrive-Dateien eines Benutzers, einschließlich Dateien, die für den Benutzer freigegeben wurden. |
Eine typische Anwendung kann beispielsweise die folgenden Bereiche anfordern:
files.readwrite offline_access
Unterstützte Authentifizierungsflüsse
Azure Active Directory unterstützt zwar mehrere Autorisierungsflüsse, doch die beiden gängigsten sind die folgenden:
Tokenfluss
Der einfachste Autorisierungsfluss ist der Tokenfluss. Dieser Fluss ist hilfreich, um schnell ein Zugriffstoken zu erhalten und die OneDrive-API interaktiv verwenden zu können. Dieser Fluss stellt kein Aktualisierungstoken bereit und ist deshalb nicht geeignet, wenn langfristiger Ressourcenzugriff benötigt wird.
Verwenden Sie einen Webbrowser oder ein Webbrowser-Steuerelement zum Laden einer URL-Anforderung, um mit dem Anmeldeprozess mit dem Tokenfluss zu beginnen.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
&response_type=token&redirect_uri={redirect_uri}
Erforderliche Parameter der Abfragezeichenfolge
| 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. |
| response_type | string | Der Typ der Antwort, die vom Autorisierungsfluss erwartet wird. Für diesen Fluss muss der Wert token sein. |
| scope | string | Eine mit Leerzeichen getrennte Liste der Bereiche, die Ihre Anwendung benötigt. |
Antwort
Bei erfolgreicher Authentifizierung und Autorisierung Ihrer Anwendung wird der Webbrowser zur angegebenen Umleitungs-URL umgeleitet und es werden zusätzliche Parameter zur URL hinzugefügt.
https://myapp.com/auth-redirect#access_token=EwC...EB
&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
&scope=onedrive.readwrite&user_id=3626...1d
Die Werte für access_token, authentication_token und user_id sind im vorherigen Beispiel abgeschnitten. Die Werte für access_token und authentication_token sind sehr lang.
Sie können den Wert von access_token für Anforderungen an Microsoft Graph verwenden.
Codefluss
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. Dies ermöglicht es Ihrer Anwendung auch, ein Aktualisierungstoken für die langfristige Nutzung der API in einigen Szenarien zu erhalten, um den Zugriff zu ermöglichen, wenn der Benutzer Ihre Anwendung nicht aktiv verwendet.
Schritt 1: Anfordern eines Autorisierungscodes
Verwenden Sie einen Webbrowser oder ein Webbrowser-Steuerelement zum Laden dieser URL-Anforderung, um mit dem Anmeldeprozess mit dem Codefluss zu beginnen.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}
&response_type=code&redirect_uri={redirect_uri}
Erforderliche Parameter der Abfragezeichenfolge
| Parametername | Wert | Beschreibung |
|---|---|---|
| client_id | string | Die für Ihre App erstellte Client-ID. |
| scope | string | Eine mit Leerzeichen getrennte Liste der Bereiche, die Ihre App benötigt. |
| redirect_uri | string | Die Umleitungs-URL, an die der Browser gesendet wird, wenn die Authentifizierung abgeschlossen ist. |
| response_type | string | Der Typ der Antwort, die vom Autorisierungsfluss erwartet wird. Für diesen Fluss muss der Wert code sein. |
Antwort
Bei erfolgreicher Authentifizierung und Autorisierung Ihrer Anwendung wird der Webbrowser zu Ihrer Umleitungs-URL umgeleitet und es werden zusätzliche Parameter zur URL hinzugefügt.
https://myapp.com/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c
Schritt 2: Einlösen des Codes für Zugriffstokens
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 der OneDrive-API ermöglichen.
Sie können den Code mithilfe der folgenden Anforderung einlösen:
POST https://login.microsoftonline.com/common/oauth2/v2.0/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
Erforderliche Parameter für den Anforderungstext
Der Anforderungstext ist eine ordnungsgemäß codierte URL-Zeichenfolge mit einigen 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 | Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| code | string | Der Autorisierungscode, den Sie in der ersten Authentifizierungsanforderung erhalten haben. |
Hinweis Bei Web-Apps muss der Domänenteil des Umleitungs-URI mit dem Domänenteil des Umleitungs-URI übereinstimmen, den Sie im Microsoft Developer Center angegeben haben.
Antwort
Wenn der Aufruf erfolgreich ist, enthält die Antwort auf die POST-Anforderung eine JSON-Zeichenfolge, die mehrere Eigenschaften umfasst, einschließlich access_token, token_type und refresh_token (wenn Sie den wl.offline_access-Bereich angefordert haben).
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Sie können nun das bereitgestellte access_token speichern und verwenden, um authentifizierte Anforderungen an Microsoft Graph zu senden.
Wichtig: Behandeln Sie die Werte von access_token und refresh_token in dieser Antwort 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 (sofern verfügbar) oder die Authentifizierungsanforderung von vorne wiederholen.
Schritt 3: Abrufen eines neuen Zugriffstokens oder Aktualisierungstokens
Wenn Ihre App den offline_access-Bereich angefordert hat, wird in diesem Schritt ein refresh_token zurückgegeben, das für die Generierung weiterer Zugriffstokens nach Ablauf des anfänglichen Tokens verwendet werden kann.
Sie können das Aktualisierungstoken mithilfe folgender Anforderung für ein neues Zugriffstoken einlösen:
POST https://login.microsoftonline.com/common/oauth2/v2.0/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
Erforderliche Parameter für den Anforderungstext
Der Anforderungstext ist eine ordnungsgemäß codierte URL-Zeichenfolge mit einigen 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 | Der für Ihre Anwendung erstellte geheime Clientschlüssel. |
| refresh_token | string | Das zuvor erhaltene Aktualisierungstoken. |
Hinweis Bei Web-Apps muss der Domänenteil des Umleitungs-URI mit dem Domänenteil des Umleitungs-URI übereinstimmen, den Sie im Microsoft Developer Center angegeben haben.
Antwort
Wenn der Aufruf erfolgreich ist, enthält die Antwort auf die POST-Anforderung eine JSON-Zeichenfolge, die mehrere Eigenschaften umfasst, einschließlich access_token, authentication_token und refresh_token, wenn Sie den offline_access-Bereich angefordert haben.
{
"token_type":"bearer",
"expires_in": 3600,
"scope": "wl.basic onedrive.readwrite wl.offline_access",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
Sie können das access_token nun speichern und verwenden, um authentifizierte Anforderungen an Microsoft Graph zu senden.
Wichtig: Behandeln Sie die Werte von access_token und refresh_token in dieser Antwort 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 (sofern verfügbar) oder die Authentifizierungsanforderung von vorne wiederholen.
Den Benutzer abmelden
Führen Sie die folgenden Schritte aus, um einen Benutzer abzumelden:
- Löschen Sie alle im Cache gespeicherten
access_token- oderrefresh_token-Werte, die Sie zuvor vom OAuth-Fluss erhalten haben. - Führen Sie alle Abmeldeaktionen in Ihrer Anwendung aus (beispielsweise das Bereinigen des lokalen Status, das Entfernen zwischengespeicherter Elemente usw.).
- Senden Sie mit der folgenden URL einen Aufruf an den Autorisierungswebdienst:
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}
Mit diesem Aufruf werden alle für Single Sign-On erforderlichen Cookies entfernt, sodass sichergestellt ist, dass der Benutzer sich erneut anmelden muss, wenn Ihre App das nächste Mal den Autorisierungsfluss startet. Durch die Verwendung des Abmeldeflusses werden keine Inhalte entfernt, die der Anwendung zuvor zur Verfügung gestellt wurden.
Erforderliche Parameter der Abfragezeichenfolge
| Parametername | Wert | Beschreibung |
|---|---|---|
| redirect_uri | string | Die Umleitungs-URL, an die der Browser gesendet wird, wenn die Authentifizierung abgeschlossen ist. Dies muss exakt dem redirect_uri-Wert entsprechen, der in der Anforderung zum Abrufen des Tokens verwendet wurde. |
Nach dem Entfernen des Cookies wird der Browser zu der Umleitungs-URL umgeleitet, die Sie angegeben haben. Wenn der Browser Ihre Umleitungsseite lädt, sind keine Abfragezeichenfolgenparameter für die Authentifizierung eingestellt. Daraus können Sie schließen, dass der Benutzer abgemeldet wurde.
Widerrufen des Zugriffs
Microsoft-Kontobenutzer können den Zugriff einer App auf ihr Konto widerrufen, indem Sie die Seite zur Zustimmungsverwaltung für Microsoft-Konten besuchen.
Wenn die Zustimmung für eine App widerrufen wird, sind zuvor für Ihre App bereitgestellte Aktualisierungstokens nicht mehr gültig. Sie müssen den Authentifizierungsfluss wiederholen, um ein komplett neues Zugriffs- und Aktualisierungstoken anzufordern.
Verwandte Themen
Die folgenden Themen enthalten einen allgemeinen Überblick über andere Konzepte, die mit der OneDrive-API verbunden sind.