OneDrive-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 Autorisierung und Anmeldung für OneDrive in Microsoft Graph folgen.
Erste Schritte
Um die OneDrive-API 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. In diesem Abschnitt erfahren Sie, wie Sie:
- Ihre Anwendung registrieren, um eine Client-ID und einen geheimen Clientschlüssel zu erhalten.
- Ihren Benutzer mithilfe des Tokenflusses oder Codeflusses bei den angegebenen Bereichen in OneDrive anmelden.
- Den Benutzer abmelden (optional).
Die OneDrive-API verwendet das standardmäßige OAuth 2.0-Authentifizierungsschema zum Authentifizieren von Benutzern und Generieren von Zugriffstokens. Sie müssen ein Zugriffstoken für jeden API-Aufruf über eine der folgenden Möglichkeiten bereitstellen.
- Einen HTTP-Header:
Authorization: bearer {token}
Registrieren der App
Um Ihre App zu authentifizieren, müssen Sie Ihre App bei Microsoft registrieren und Einzelheiten zu Ihrer App angeben.
So registrieren Sie die App
Im Thema Registrierung Ihrer App für die OneDrive-API finden Sie Informationen zum Registrieren Ihrer App.
Benutzer anmelden
Die App muss den Anmeldeprozess initiieren, indem der Autorisierungswebdienst des Microsoft-Kontos mit einem angegebenen Bereich kontaktiert und ein Zugriffstoken abgerufen wird. Der Fluss folgt standardmäßigen OAuth 2.0-Authentifizierungsflüssen und erfordert Aufrufe von einem Webbrowser oder Webbrowser-Steuerelement.
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 | Erforderlich |
|---|---|---|
| offline_access | Ermöglicht es Ihrer App, offline zu arbeiten, auch wenn der Benutzer nicht aktiv ist. Dadurch erhält die App ein Aktualisierungstoken, das bei Bedarf zum Generieren zusätzlicher Zugriffstoken verwendet werden kann. Dieser Bereich ist nicht für den Tokenfluss verfügbar. | Nein |
| onedrive.readonly | Gewährt die Berechtigung ausschließlich zum Lesen sämtlicher OneDrive-Dateien eines Benutzers, einschließlich Dateien, die für den Benutzer freigegeben wurden. | Ja |
| onedrive.readwrite | Gewährt Lese- und Schreibberechtigungen für alle OneDrive-Dateien eines Benutzers, einschließlich Dateien, die für den Benutzer freigegeben wurden. Dieser Bereich ist zum Erstellen von Freigabelinks erforderlich. | Ja |
| onedrive.appfolder | Gewährt Lese- und Schreibberechtigungen für einen bestimmten Ordner für die Anwendung. | Ja |
Eine typische Anwendung kann beispielsweise die folgenden Bereiche anfordern:
onedrive.readwrite offline_access
Unterstützte Authentifizierungsflüsse
Sie können aus zwei unterstützten Authentifizierungsflüssen auswählen:
Tokenfluss
Der Tokenfluss ist der einfachste Authentifizierungsfluss. Dieser Fluss ist hilfreich, um schnell ein Zugriffstoken zu erhalten und die OneDrive-API interaktiv verwenden zu können. Dieser Fluss liefert kein Aktualisierungstoken, er kann also nicht für langfristigen Zugriff auf die OneDrive-API verwendet werden.
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.live.com/oauth20_authorize.srf?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. |
Verwenden Sie diese Umleitungs-URL für mobile und Desktopanwendungen https://login.live.com/oauth20_desktop.srf.
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://login.live.com/oauth20_authorize.srf#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 die OneDrive-API 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.live.com/oauth20_authorize.srf?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://login.live.com/oauth20_authorize.srf?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.live.com/oauth20_token.srf
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-Konto 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 die OneDrive-API 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 Zugriff auf wl.offline_access 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.live.com/oauth20_token.srf
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 auf der Live SDK App-Verwaltungswebsite 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 wl.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 nun das access_token speichern und verwenden, um authentifizierte Anforderungen an die OneDrive-API 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.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}
Mit diesem Aufruf werden alle für Single Sign-On erforderlichen Cookies entfernt, sodass sichergestellt ist, dass der Benutzer aufgefordert wird, einen Benutzernamen und ein Kennwort einzugeben, wenn Ihre App das nächste Mal die Anmeldeoberfläche startet.
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. 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
Benutzer 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 Ihre 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.
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 Informationen sind nicht immer auf der Fehlerseite enthalten, die im Browser angezeigt wird.
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}
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.
Fehlerparameter
| Parametername | Wert | Beschreibung |
|---|---|---|
| error | string | Fehlercode, der den aufgetretenen Fehler identifiziert. |
| error_description | string | Eine Beschreibung des Fehlers. |
Verwandte Themen
Die folgenden Themen enthalten einen allgemeinen Überblick über andere Konzepte, die mit der OneDrive-API verbunden sind.