Autorisierungscode-OAuth-Fluss für SharePoint-Add-InsAuthorization Code OAuth flow for SharePoint Add-ins

Hinweis

In diesem Artikel wird davon ausgegangen, dass Sie mit dem Erstellen von SharePoint-Add-Ins, die die Autorisierung mit niedriger Vertrauensebene verwenden, und den Konzepten und Prinzipien von OAuth vertraut sind.This article assumes that you are familiar with Creating SharePoint Add-ins that use low-trust authorization and with the concepts and principles behind OAuth. Weitere Informationen zu OAuth finden Sie unter OAuth.net und Webautorisierungsprotokoll (oauth).For more information about OAuth, see OAuth.net and Web Authorization Protocol (oauth).

Wichtig

Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.

In einigen Szenarien kann ein Add-In die Berechtigung für den Zugriff auf SharePoint-Ressourcen im laufenden Betrieb anfordern, d. h. dass ein Add-In die Berechtigung für den Zugriff auf SharePoint-Ressourcen dynamisch zur Laufzeit anstatt bei der Installation des Add-Ins anfordern kann.In some scenarios, an add-in can request permission to access SharePoint resources on the fly; that is, an add-in can request permission to access SharePoint resources dynamically at runtime, instead of at add-in installation time. Diese Art von Add-In muss nicht aus SharePoint gestartet und auch nicht auf SharePoint installiert werden.This type of add-in does not have to be launched from, or even installed on, SharePoint. Es kann sich beispielsweise um ein natives Gerät-Add-In handeln, also ein Add-In, das von einer beliebigen Website gestartet wird, oder um ein Office-Add-In, das über eine Office-Anwendung gestartet wird und im laufenden Betrieb auf Ressourcen in SharePoint zugreifen möchte.For example, it could be a native device add-in, an add-in that is launched from any website, or an Office Add-in launched from an Office application that wants to access resources on SharePoint on the fly.

Hinweis

Dieser Add-In-Typ kann nur von Benutzern mit Verwaltungsberechtigungen für die Ressourcen ausgeführt werden, auf die das Add-In zugreifen möchte. Wenn ein Add-In beispielsweise nur die Leseberechtigung für eine Website anfordert, kann ein Benutzer das Add-In mit der Berechtigung "Lesen" ohne die Berechtigung "Verwalten" nicht ausführen.This type of add-in can only be run by users who have Manage permissions to the resources the add-in wants to access. For example, if an add-in requests only Read permission to a website, a user who has Read, but not Manage, rights to the website cannot run the add-in.

Um sich in SharePoint einwählen können, muss diese Art von Add-In zunächst über das Händler-Dashboard oder die Seite "appregnew.aspx" registriert werden.To be able to call in to SharePoint, this type of add-in must first be registered through the Seller Dashboard or the appregnew.aspx page. Weitere Informationen zum Registrieren von Add-Ins über das Händler-Dashboard oder appregnew.aspx finden Sie unter Registrieren von SharePoint-Add-Ins.For more information about registering add-ins via the Seller Dashboard or appregnew.aspx, see Register SharePoint Add-ins.

Nachdem Sie das Add-In registriert haben, ist es ein Sicherheitsprinzipal und verfügt wie Benutzer und Gruppen über eine Identität.After you've registered your add-in, it is a security principal and has an identity just as users and groups do. Diese Identität wird als Add-In-Prinzipal bezeichnet.This identity is referred to as an add-in principal. Wie Benutzer und Gruppen besitzt ein Add-In-Prinzipal bestimmte Berechtigungen.Like users and groups, an add-in principal has certain permissions. Weitere Informationen über Add-In-Prinzipale finden Sie unter Registrieren von SharePoint-Add-Ins.For more information about add-in principals, see Register SharePoint Add-ins.

Wenn Sie das Add-In registrieren, erhalten Sie eine Client-ID, einen geheimen Clientschlüssel, eine Add-In-Domäne und einen Umleitungs-URI für den Add-In-Prinzipal.When you register the add-in, you'll get a client ID, client secret, add-in domain, and redirect URI for the add-in principal. Diese Informationen werden beim Autorisierungsserver, winazureacslong, registriert.This information is registered with the authorization server, Microsoft Azure Access Control Service (ACS).

Autorisierungscode-OAuth-Ablauf für Add-Ins, die Berechtigungen dynamisch anfordernAuthorization Code OAuth flow for add-ins that request permissions on the fly

Dieser Abschnitt fasst den OAuth-Authentifizierungs- und Autorisierungsablauf für ein SharePoint-Add-In zusammen, das Berechtigungen im laufenden Betrieb anfordert.This section summarizes the OAuth authentication and authorization flow for a SharePoint add-in requesting permissions on the fly. Dieser Ablauf wird als Authentifizierungscode-Ablauf bezeichnet.The flow is called the Authentication Code flow. Die Sequenz beschreibt, wie ein Add-In, das nicht aus SharePoint gestartet wird, auf Ressourcen in SharePoint zugreifen kann.The sequence describes how an add-in that is not launched from within SharePoint can access resources in SharePoint.

Hinweis

Der Ablauf umfasst eine Reihe von Interaktionen zur Laufzeit zwischen Ihrem Add-In, SharePoint, dem Server für die Autorisierung (ACS) und dem Endbenutzer.The flow involves a series of interactions between your add-in, SharePoint, the authorization server (which is ACS), and the end user at runtime. Der Ablauf benötigt entweder SharePoint Online oder eine SharePoint-Farm, die mit dem Internet verbunden ist, um mit ACS kommunizieren zu können.So the flow requires either SharePoint Online or a SharePoint farm that is connected to the Internet, so it can communicate with ACS. SharePoint-Farmen, die nicht mit dem Internet verbunden sind, müssen das Autorisierungssystem mit hoher Vertrauenswürdigkeit verwenden.SharePoint farms that are not connected to the Internet must use the high-trust authorization system.

Es muss eine Webanwendung oder ein Webdienst vorhanden sein, die bzw. der separat von SharePoint gehostet wird.There has to be a web application or service that is hosted separately from SharePoint. Auch wenn es sich bei dem Add-In um ein Gerät-Add-In handelt, muss es über eine Webanwendung oder Dienst-URL verfügen, die mit ACS registriert werden kann, auch wenn die Webkomponente für nichts anderes verwendet wird.Even if the add-in is a device add-in, it has to have a web application or service URL that can be registered with ACS, even if the web component is used for nothing else.

Der Einfachheit halber wird in diesem Artikel davon ausgegangen, dass das Add-In eine Webanwendung namens „Contoso.com“ ist.For simplicity, this article assumes that the add-in is a web application called Contoso.com. Die Anwendung verwendet das SharePoint-Clientobjektmodell (CSOM) oder die SharePoint-REST-APIs für Aufrufe an SharePoint.The application uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. Wenn die Anwendung erstmalig versucht, auf SharePoint zuzugreifen, fordert SharePoint einen Autorisierungscode von ACS an, um diesen an die Anwendung Contoso.com zu senden.When the application first attempts to access SharePoint, SharePoint requests an authorization code from ACS that it can send to the Contoso.com application. Die Anwendung verwendet dann den Autorisierungscode, um ein Zugriffstoken bei ACS anfordern.The application then uses the authorization code to request an access token from ACS. Nachdem die Anwendung Contoso.com das Zugriffstoken erhalten hat, fügt sie es in alle Anfragen an SharePoint ein.After it has the access token, the Contoso.com application includes it in all its requests to SharePoint.

Ausführliches Beispiel des AblaufsDetailed example of the flow

Nehmen wir an, dass Contoso einen Online-Fotodruckdienst bereitstellt.Suppose that Contoso provides a photo-printing service online. Ein Benutzer möchte einige Fotos drucken.A user wants to print some photos. Der Benutzer möchte es dem Fotodruckdienst von Contoso ermöglichen, auf Fotos in unterschiedlichen Fotobibliotheken zuzugreifen, die der Benutzer auf einer SharePoint Online-Website, fabrikam.sharepoint.com, aufbewahrt, und diese zu drucken.The user wants to give consent to a Contoso photo-printing service to access and print photos from a set of photo libraries that the user keeps on a SharePoint Online site fabrikam.sharepoint.com.

OAuth

Die Fotodruck-Anwendung ist registriert, daher verfügt sie über eine Client-ID, einen geheimen Clientschlüssel und einen Umleitungs-URI.The photo-printing application is registered, so it has a client ID, client secret, and redirect URI. Der Umleitungs-URI, den Contoso bei der Registrierung der Add-In bereitgestellt hat, lautet https://contoso.com/RedirectAccept.aspx.The redirect URI that Contoso provided when it registered the add-in is https://contoso.com/RedirectAccept.aspx. Die Informationen zur Client-ID und zum geheimen Clientschlüssel werden in der Datei web.config der Fotodruck-Anwendung gespeichert.The client ID and client secret information are stored in the photo-printing application's web.config file. Es folgt ein Beispiel dazu, wie die Client-ID und der geheime Clientschlüssel in die Datei web.config eingetragen werden.The following is an example of how the client ID and client secret are entered in the web.config file.

    <configuration>
    <appSettings>
        <add key="ClientId" value="c78d058c-7f82-44ca-a077-fba855e14d38 "/>
        <add key="ClientSecret" value="SbALAKghPXTjbBiLQZP+GnbmN+vrgeCMMvptbgk7T6w= "/>
    </appSettings>
    </configuration>

Schritte des Authentifizierungscode-AblaufsAuthentication Code flow steps

Im Folgenden sind die Schritte des Authentifizierungscodeablaufs aufgeführt.Following are the steps in the Authentication Code flow.

Tipp

Diese Schritte beziehen sich auf Methoden in der Datei TokenHelper.cs (oder TokenHelper.vb) file. Dieser verwaltete Code ist nicht kompiliert, es gibt dazu also keine Referenzthemen. However, the file itself is fully commented with descriptions of every class, member parameter, and return value. Consider having a copy of it open to refer to as you read these steps.These steps refer to methods in the TokenHelper.cs (or .vb) file. This managed code is not compiled, so there are no reference topics for it. However, the file itself is fully commented with descriptions of every class, member parameter, and return value. Consider having a copy of it open to refer to as you read these steps.

Schritt 1: Der Client öffnet eine Anwendung und leitet sie an eine SharePoint-Website für Daten um.Step 1: Client opens an application and then directs it to a SharePoint site for data

OAuth

Ein Benutzer öffnet die Contoso-Fotodruck-Website und findet auf der Benutzeroberfläche den Hinweis, dass er Fotos drucken kann, die auf einer beliebigen SharePoint Online-Website aufbewahrt werden.A user browses to the Contoso photo-printing website, where the UI indicates that the user can print photos that are kept on any SharePoint Online site.

In diesem Beispiel ist die URL https://contoso.com/print/home.aspxIn this example, the URL is https://contoso.com/print/home.aspx

Das Fotodruck-Add-In fordert den Benutzer zur Eingabe der URL der Fotosammlung auf.The photo-printing add-in asks the user to enter the URL of the photo collection. Der Benutzer gibt eine URL ein, die auf die SharePoint Online-Website verweist: https://fabrikam.sharepoint.com/The user enters a URL pointing to the SharePoint Online site: https://fabrikam.sharepoint.com/

Schritt 2: Das Add-In wird an die Autorisierungs-URL der SharePoint-Website weitergeleitet.Step 2: The add-in redirects to the SharePoint site authorization URL

OAuth

Wenn der Benutzer die Schaltfläche zum Abrufen der Fotos auswählt, leitet das Contoso-Fotodruck-Add-In den Browser an https://fabrikam.sharepoint.com/ um. Diese Umleitung ist eine HTTP-302-Umleitungsantwort.When the user selects the button to get the photos, the Contoso photo-printing add-in redirects the browser to https://fabrikam.sharepoint.com/; this redirect is an HTTP 302 Redirect Response.

Bei Verwendung von Microsoft .NET ist *Response.Redirect* eine von mehreren Möglichkeiten zum Implementieren der Umleitung in Ihrem Code. Mithilfe der Datei Tokenhelper.cs (oder Tokenhelper.vb) in Ihrem Projekt können Sie die überladene *GetAuthorizationUrl*-Methode (mit drei Argumenten) aufrufen. Durch diese Methode wird die Umleitungs-URL für "OAuthAuthorize.aspx" automatisch konstruiert. Sie können die URL aber auch manuell konstruieren. If you're using Microsoft .NET, Response.Redirect is one of several ways you can do the redirect from your code. Using the TokenHelper.cs (or .vb) file in your project, your code can call the overloaded GetAuthorizationUrl method (using the overload with three arguments). This method constructs the OAuthAuthorize.aspx redirect URL for you. Or, your code can manually construct the URL.

Wenn Sie beispielsweise die GetAuthorizationUrl-Methode aufrufen, um die Umleitungs-URL für "OAuthAuthorize.aspx" automatisch zu konstruieren, ergibt sich bei Verwendung der Datei TokenHelper.cs (TokenHelper.vb) in Ihrem Projekt folgender Code: Response.Redirect(TokenHelper.GetAuthorizationUrl( sharePointSiteUrl.ToString(), "Web.Read List.Write", "https://contoso.com/RedirectAccept.aspx"));For example, if you choose to call the GetAuthorizationUrl method to construct the OAuthAuthorize.aspx redirect URL for you, using the TokenHelper.cs (or .vb) in your project, the code is as follows: Response.Redirect(TokenHelper.GetAuthorizationUrl( sharePointSiteUrl.ToString(), "Web.Read List.Write", "https://contoso.com/RedirectAccept.aspx"));

Wenn Sie sich die Überlastungsliste der drei Parameter der GetAuthorizationUrl-Methode in TokenHelper.cs (oder .vb) ansehen, werden Sie feststellen, dass der zweite Parameter ein Berechtigungsbereich-Parameter ist, bei dem es sich um eine durch Leerzeichen getrennte Liste von Berechtigungen handelt, die das Add-In im Kurzschriftformat anfordert.If you look at the three-parameter overload of the GetAuthorizationUrl method in TokenHelper.cs (or .vb), you see that the second parameter is a permission scope parameter, which is a space-delimited list of permissions the add-in requests in shorthand format. Weitere Informationen zu Berechtigungsbereichen finden Sie unter Berechtigungsbereichsaliasen und die Verwendung der OAuthAuthorize.aspx-Seite.For more information about permission scopes, see Permission scope aliases and the use of the OAuthAuthorize.aspx page.

Der dritte Parameter muss der gleiche Umleitungs-URI sein, der bei der Registrierung des Add-Ins verwendet wurde.The third parameter must be the same redirect URI that is used when the add-in is registered. Weitere Informationen zur Registrierung finden Sie unter Registrieren von SharePoint-Add-Ins. Die zurückgegebene Zeichenfolge ist eine URL, einschließlich der Parameter der Abfragezeichenfolge.For more information about registration, see Register SharePoint Add-ins. The returned string is a URL including query string parameters. Sie können die Umleitungs-URL OAuthAuthorize.aspx auch manuell erstellen.If you prefer, you can manually construct the OAuthAuthorize.aspx redirect URL. Beispielsweise lautet die URL, zu der das Contoso-Fotodruck-Add-In den Benutzer umleitet, https://fabrikam.sharepoint.com/_layouts/15/OAuthAuthorize.aspx?client_id=client_GUID&amp;scope=app_permissions_list&amp;response_type=code&amp;redirect_uri=redirect_uri.For example, the URL that the Contoso photo-printing add-in redirects the user to in this case is: https://fabrikam.sharepoint.com/_layouts/15/OAuthAuthorize.aspx?client_id=client_GUID&amp;scope=app_permissions_list&amp;response_type=code&amp;redirect_uri=redirect_uri

Wie im Beispiel zu sehen, sendet das Contoso-Fotodruck-Add-In die OAuth-Client-ID und den Umleitungs-URI als Abfragezeichenfolge-Parameter an die Fabrikam-Website. As the example shows, the Contoso photo-printing add-in sends the OAuth client ID and redirect URI to the Fabrikam site as query string parameters. Es folgt ein Beispiel für die GET-Anforderung mit Beispielwerten für die Abfragezeichenfolge.The following is an example of the GET request with sample query string values. Aus Gründen der Übersichtlichkeit wurden Zeilenumbrüche hinzugefügt.Line breaks have been added for clarity. Die tatsächlichen Ziel-URL ist eine einzelne Linie.The actual target URL is a single line. GET /authcode HTTP/1.1 Host: fabrikam.sharepoint.com /oauthauthorize.aspx ?client_id= c78d058c-7f82-44ca-a077-fba855e14d38 &amp;scope=list.read &amp;response_type=code &amp;redirect_uri= https%3A%2F%2Fcontoso%2Ecom%2Fredirectaccept.aspx

Wenn Sie ein separates Popupfenster zum Einholen der Zustimmung verwenden möchten, können Sie dem URL-Konstrukt den Abfrageparameter IsDlg=1 hinzufügen, wie hier gezeigt: /oauthauthorize.aspx?IsDlg=1&amp;client_id= c78d058c-7f82-44ca-a077-fba855e14d38&amp;scope=list.read&amp;response_type=code&amp;redirect_uri= https%3A%2F%2Fcontoso%2Ecom%2Fredirectaccept.aspxIf you want a separate consent pop-up dialog, you can add the query parameter IsDlg=1 to the URL construct as shown here: /oauthauthorize.aspx?IsDlg=1&amp;client_id= c78d058c-7f82-44ca-a077-fba855e14d38&amp;scope=list.read&amp;response_type=code&amp;redirect_uri= https%3A%2F%2Fcontoso%2Ecom%2Fredirectaccept.aspx

OAuth

Falls der Benutzer noch nicht bei der Fabrikam-SharePoint Online-Website angemeldet ist, wird er aufgefordert, sich anzumelden.If the user is not already signed into the Fabrikam SharePoint Online site, the user is prompted to sign in. Ist der Benutzer bereits angemeldet, wird eine HTML-Zustimmungsseite von SharePoint gerendert.When the user is signed in, SharePoint renders an HTML consent page. Die Zustimmungsseite fordert den Benutzer auf, dem Contoso-Fotodruck-Add-In die Berechtigungen zu erteilen (oder zu verweigern), die das Add-In anfordert.The consent page prompts the user to grant (or deny) the Contoso photo-printing add-in the permissions that the add-in requests. In diesem Fall gewährt der Benutzer dem Add-In den Lesezugriff auf die Bildbibliothek des Benutzers auf Fabrikam.In this case, the user would be granting the add-in read access to the user's picture library on Fabrikam.

Schritt 4: SharePoint fordert bei ACS einen kurzfristigen Autorisierungscode an.Step 4: SharePoint requests a short-lived authorization code from ACS

OAuth

Die Fabrikam-SharePoint Online-Website fordert den Zugriffssteuerungsdienst auf, für diese Kombination aus Benutzer und Add-In einen kurzfristigen (ca. 5 Minuten gültigen) eindeutigen Autorisierungscode zu erstellen.The Fabrikam SharePoint Online site asks ACS to create a short-lived (approximately 5 minutes) authorization code unique to this combination of user and add-in. ACS sendet den Autorisierungscode an die Fabrikam-Website.ACS sends the authorization code to the Fabrikam site.

Schritt 5: Die SharePoint Online-Website wird an den registrierten Umleitungs-URI des Add-Ins weitergeleitet und übergibt dabei den Autorisierungscode an das Add-In.Step 5: The SharePoint Online site redirects to the app's registered redirect URI, passing the authorization code to the add-in

OAuth

Die Fabrikam-SharePoint Online-Website leitet den Browser über die Antwort HTTP 302 zurück zu Contoso.The Fabrikam SharePoint Online site redirects the browser back to Contoso via HTTP 302 Response. Das URL-Konstrukt für diese Umleitung verwendet den Umleitungs-URI, der bei der Registrierung des Fotodruck-Add-Ins angegeben wurde.The URL construct for this redirection uses the redirect URI that was specified when the photo-printing add-in was registrated. Es beinhaltet zudem den Autorisierungscode als Abfragezeichenfolge.It also includes the authorization code as a query string.

Die Umleitungs-URL ist folgendermaßen strukturiert: https://contoso.com/RedirectAccept.aspx?code=<authcode>The redirect URL is structured like the following: https://contoso.com/RedirectAccept.aspx?code=<authcode>

Schritt 6: Das Add-In verwendet den Autorisierungscode, um bei ACS ein Zugriffstoken anzufordern. ACS validiert die Anforderung, macht den Autorisierungscode ungültig und sendet dann Zugriffs- und Aktualisierungstoken dann an das Add-In.Step 6: The add-in uses the authorization code to request an access token from ACS, which validates the request, invalidates the authorization code, and then sends access and refresh tokens to the add-in

OAuth

Contoso ruft den Autorisierungscode aus dem Abfrageparameter ab und fügt ihn dann zusammen mit der Client-ID und dem geheimen Clientschlüssel in eine Anforderung an ACS für ein Zugriffstoken ein.Contoso retrieves the authorization code from the query parameter, and then includes it, along with the client ID and client secret, in a request to ACS for an access token.

Wenn Sie verwalteten Code und SharePoint CSOM, die Datei TokenHelper.cs (oder .vb) verwenden, lautet die Methode für die Anforderung an ACS GetClientContextWithAuthorizationCode.If you are using managed code and the SharePoint CSOM, the TokenHelper.cs (or .vb) file, the method that makes the request to ACS is GetClientContextWithAuthorizationCode. In diesem Fall sieht der Code ähnlich aus wie Folgt (wobei authCode die Variable ist, der der Autorisierungscode zugewiesen wurde): TokenHelper.GetClientContextWithAuthorizationCode( "https://fabrikam.sharepoint.com/", "00000003-0000-0ff1-ce00-000000000000", authCode, "1ee82b34-7c1b-471b-b27e-ff272accd564", new Uri(Request.Url.GetLeftPart(UriPartial.Path)));In this case the code looks similar to the following (where authCode is a variable to which the authorization code has been assigned): TokenHelper.GetClientContextWithAuthorizationCode( "https://fabrikam.sharepoint.com/", "00000003-0000-0ff1-ce00-000000000000", authCode, "1ee82b34-7c1b-471b-b27e-ff272accd564", new Uri(Request.Url.GetLeftPart(UriPartial.Path)));

Wenn Sie sich die Datei TokenHelper.cs (oder .vb) ansehen, ist der zweite Parameter der Methode GetClientContextWithAuthorizationCode targetPrincipalName.If you look at the TokenHelper.cs (or .vb) file, the second parameter of the GetClientContextWithAuthorizationCode method is the targetPrincipalName. Dieser Wert ist immer die Konstante 00000003-0000-0ff1-ce00-000000000000 in einem Add-In, das auf SharePoint zugreift.This value is always the constant 00000003-0000-0ff1-ce00-000000000000 in an add-in that is accessing SharePoint. Wenn Sie die Anrufhierarchie von GetClientContextWithAuthorizationCode nachverfolgen, sehen Sie die Client-ID und den Schlüssel aus der Datei web.config.If you trace the call hierarchy from GetClientContextWithAuthorizationCode, it obtains the client ID and secret from the web.config file.

ACS erhält die Anforderung von Contoso und überprüft die Client-ID, den geheimen Clientschlüssel, den Umleitungs-URI und den Autorisierungscode.ACS receives Contoso's request and validates the client ID, client secret, redirect URI, and authorization code. Wenn alle gültig sind, macht ACS den Autorisierungscode ungültig (er kann nur einmal verwendet werden) und erstellt ein Aktualisierungstoken und ein Zugriffstoken, die an Contoso zurückgegeben werden.If all are valid, the ACS invalidates the authorization code (it can be used only once) and creates a refresh token and an access token, which it returns to Contoso. Die Contoso-Anwendung kann diesen Zugriffstoken für die Wiederverwendung bei späteren Anfragen zwischenspeichern.The Contoso application can cache this access token for reuse on later requests. Standardmäßig sind Zugriffstoken 12 Stunden gültig.By default, access tokens are good for about 12 hours.

Jedes Zugriffstoken gilt nur für das Benutzerkonto, das in der ursprünglichen Anforderung für die Autorisierung angegeben ist, und gewährt nur auf die Dienste Zugriff, die in dieser Anforderung festgelegt wurden.Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the services that are specified in that request. Das Add-In sollte das Zugriffstoken sicher speichern.Your add-in should store the access token securely. Die Contoso-Anwendung kann auch das Aktualisierungstoken zwischenspeichern.The Contoso application can also cache the refresh token. Standardmäßig sind Aktualisierungstoken 6 Monate gültig.By default, refresh tokens are good for 6 months. Das Aktualisierungstoken kann gegen ein neues Zugriffstoken von ACS eingetauscht werden, bis das Aktualisierungstoken abläuft.The refresh token can be redeemed for a new access token from ACS whenever the access token expires.

Ausführliche Informationen zu Token finden Sie unter Handhabung von Sicherheitstoken in vom Anbieter gehosteten Add-Ins für SharePoint mit niedriger Vertrauensebene.For more information about tokens, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

Schritt 7: Das Add-In kann jetzt das Zugriffstoken verwenden, um Daten von der SharePoint-Website anzufordern, die sie dem Benutzer anzeigen kann.Step 7: The add-in can now use the access token to request data from the SharePoint site, which it can display to the user

OAuth

Contoso schließt das Zugriffstoken ein, um eine REST-API- oder CSOM-Aufforderung an SharePoint durchzuführen und übergibt dabei das OAuth-Zugriffstoken im HTTP- Authorization-Header.Contoso includes the access token to make a REST API call or CSOM request to SharePoint, passing the OAuth access token in the HTTP Authorization header. SharePoint gibt die von Contoso angeforderten Informationen zurück.SharePoint returns the information that Contoso requested.

Ausführliche Informationen zur Durchführung dieser Anforderung finden Sie unter Handhabung von Sicherheitstoken in vom Anbieter gehosteten Add-Ins mit niedriger Vertrauensebene für SharePoint.For more information about how this request is made, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

Berechtigungsbereichsaliasen und Verwendung der OAuthAuthorize.aspx-SeitePermission scope aliases and the OAuthAuthorize.aspx page

In diesem Abschnitt wird davon ausgegangen, dass Sie mit dem Artikel Add-In-Berechtigungen in SharePoint vertraut sind.This section assumes that you are familiar with the article Add-in permissions in SharePoint. In Tabelle 1 sind dieselben URIs für den Add-In-Berechtigungsanforderungsbereich aufgeführt wie in diesem Artikel, mit der Ausnahme, dass die Tabelle über eine zusätzliche Spalte (Bereichsalias) verfügt und das Recht "FullControl" nicht in der Spalte Verfügbare Rechte verfügbar ist, da ein Add-In, das die Berechtigung für den Zugriff auf SharePoint-Ressourcen dynamisch anfordert, keinen Vollzugriff anfordern kann.Table 1 shows the same add-in permission request scope URIs that are shown in that article, except it has one additional column (Scope alias), and the FullControl right is not available in the Available rights column, because an add-in that requests permission to access SharePoint resources on the fly can't request the FullControl right.

Die in der Spalte Bereichsalias aufgelisteten Werte sind Kurzformen ihrer Entsprechungen in der Spalte Bereichs-URI.The values listed in the Scope alias column are shorthand versions of their counterparts in the Scope URI column. Die Aliase können nur von Add-Ins verwendet werden, die die Berechtigung für den Zugriff auf SharePoint-Ressourcen im laufenden Betrieb anfordern.The aliases can be used only by add-ins that request permission to access SharePoint resources on the fly. (Die Werte des Bereichs-URI werden im Add-In-Manifest von Add-Ins verwendet, die über SharePoint gestartet werden.(The scope URI values are used in the add-in manifest of add-ins that are launched from SharePoint. Diese Add-Ins fordern Berechtigungen während der Installation an.)These add-ins request permissions during add-in installation.)

Die Bereichsaliase kommen nur im Rahmen der Verwendung der OAuthAuthorize.aspx-Umleitungsseite zum Einsatz.The scope aliases are used only in the context of using the OAuthAuthorize.aspx redirect page. Wie in Schritt 2 des im vorherigen Abschnitt beschriebenen OAuth-Ablaufs gezeigt, werden die Aliase, wenn das Add-In verwalteten Code verwendet, beim Aufrufen der Methode GetAuthorizationUrl von „TokenHelper.cs“ (oder .vb) in Ihrem Projekt benutzt.As shown in step 2 of the OAuth flow described in the previous section, when the add-in is using managed code, the aliases are used when you call the GetAuthorizationUrl method of TokenHelper.cs (or .vb) in your project. Es folgt ein weiteres Beispiel.The following is another example:

Response.Redirect(TokenHelper.GetAuthorizationUrl(
    sharePointSiteUrl.ToString(), 
    "Web.Read List.Write ", 
    "https://contoso.com/RedirectAccept.aspx "));

Der Bereich-Parameterwert, Web.Read List.Write, ist ein Beispiel dafür, wie Sie Berechtigungen mithilfe der Bereichsaliasen anfordern würden.The scope parameter value, Web.Read List.Write, is an example of how you would request permissions by using the scope aliases. Der Bereich-Parameter ist ein durch Leerzeichen getrennter Satz von Berechtigungsbereich- und Berechtigungsanfragen.The scope parameter is a space-delimited set of permission scope and right requests.

Wenn Sie keinen verwalteten Code verwenden, werden die Bereichsaliase im Bereichsfeld der Umleitungs-URL verwendet. Beispiel:If you are not using managed code, the scope aliases are used in the scope field in the redirect URL. For example:

https://fabrikam.sharepoint.com/_layout/15/OAuthAuthorize.aspx?client_id=c78d058c-7f82-44ca-a077-fba855e14d38&amp;scope=list.write&amp;response_type=code&amp;redirect_uri=https%3A%2F%2Fcontoso%2Ecom%2Fredirectaccept.aspx

Hinweis

Eine Beschreibung der Bereiche finden Sie unter Add-In-Berechtigungen in SharePoint.For a description of the scopes, see Add-in permissions in SharePoint.


Tabelle 1. Berechtigungsanforderungsbereichs-URIs für SharePoint-Add-Ins und die entsprechenden AliaseTable 1. SharePoint add-in permission request scope URIs and their corresponding aliases

Bereichs-URIScope URI BereichsaliasScope alias Verfügbare RechteAvailable rights
http://sharepoint/content/sitecollection WebsiteSite Read, Write, ManageRead, Write, Manage
http://sharepoint/content/sitecollection/web WebWeb Read, Write, ManageRead, Write, Manage
http://sharepoint/content/sitecollection/web/list ListeList Read, Write, ManageRead, Write, Manage
http://sharepoint/content/tenant AllSitesAllSites Read, Write, ManageRead, Write, Manage
http://sharepoint/bcs/connection Keine (wird derzeit nicht unterstützt)None (currently not supported) ReadRead
http://sharepoint/search SucheSearch QueryAsUserIgnoreAppPrincipalQueryAsUserIgnoreAppPrincipal
http://sharepoint/projectserver ProjectAdminProjectAdmin VerwaltenManage
http://sharepoint/projectserver/projects ProjekteProjects Read, WriteRead, Write
http://sharepoint/projectserver/projects/project ProjectProject Read, WriteRead, Write
http://sharepoint/projectserver/enterpriseresources ProjectResourcesProjectResources Read, WriteRead, Write
http://sharepoint/projectserver/statusing ProjectStatusingProjectStatusing SubmitStatusSubmitStatus
http://sharepoint/projectserver/reporting ProjectReportingProjectReporting ReadRead
http://sharepoint/projectserver/workflow ProjectWorkflowProjectWorkflow ElevateElevate
http://sharepoint/social/tenant AllProfilesAllProfiles Read, Write, ManageRead, Write, Manage
http://sharepoint/social/core SozialSocial Read, Write, ManageRead, Write, Manage
http://sharepoint/social/microfeed MicroFeedMicrofeed Read, Write, ManageRead, Write, Manage
http://sharepoint/taxonomy TermStoreTermStore Read, WriteRead, Write

Umleitungs-URIs und Beispiel-UmleitungsseitenRedirect URIs and a sample redirect page

Der Umleitungs-URI, der von Add-Ins verwendet wird, die Berechtigungen im laufenden Betrieb anfordern, ist der URI, zu dem SharePoint den Browser umleitet, nach dem eine Zustimmung gewährt wurde (mit dem Autorisierungscode als Abfrageparameter inbegriffen).The redirect URI that is used by add-ins that request permission on the fly is the URI that SharePoint redirects the browser to after consent is granted (with the authorization code included as a query parameter). Schritt 2 des OAuth-Ablaufs bietet ein Beispiel, in dem der URI in einer Abfrage an die GetAuthorizationUrl-Methode hartcodiert ist.Step 2 of the OAuth flow gives an example where the URI is hardcoded in a call to GetAuthorizationUrl method. Alternativ kann ein ASP.NET-Add-In den Umleitungs-URI auch in der Datei web.config speichern, wie im folgenden Beispiel gezeigt:Alternatively, an ASP.NET add-in can also store the redirect URI in the web.config file as shown in this example:

    <configuration>
        <appSettings>
            <add key="RedirectUri" value="https://contoso.com/RedirectAccept.aspx" />
        </appSettings>
    <configuration>

Der Wert kann mit einem Aufruf von WebConfigurationManager.AppSettings.Get("RedirectUri") abgerufen werden.The value can be retrieved with a call to WebConfigurationManager.AppSettings.Get("RedirectUri").

Der Endpunkt des Umleitungs-URI erhält den Autorisierungscode vom Abfrageparameter und verwendet ihn, um ein Zugriffstoken zu erhalten, das dann für den Zugriff auf SharePoint verwendet werden kann.The endpoint at the redirect URI gets the authorization code from the query parameter and uses it to get an access token, which can then be used to access SharePoint. In der Regel ist der Endpunkt dieselbe Seite oder Controllermethode oder Webmethode, die ursprünglich versucht hat, auf SharePoint zuzugreifen.Typically, the endpoint is the same page, or controller method, or web method that originally attempted to access SharePoint. Es kann jedoch auch eine Seite oder eine Methode sein, die nur das Autorisierungstoken erhält und dann an eine andere Seite oder Methode umleitet.However, it can be a page or method that only receives the authorization token and then redirects to another page or method. Die besondere Seite oder Methode kann das Autorisierungstoken weitergeben oder zwischenspeichern.The special page or method could pass the authorization token or cache it. (Es besitzt eine Lebensdauer von ca. 5 Minuten). Alternativ kann sie das Autorisierungstoken verwenden, um ein Zugriffstoken abzurufen, das dann zwischengespeichert wird.(It has a lifetime of about 5 minutes.) Alternatively, it could use the authorization token to obtain an access token which it caches.

Im Folgenden finden Sie ein Beispiel für den Code hinter einer solchen Seite in einer ASP.NET-Anwendung.The following is an example of the code-behind of such a page in an ASP.NET application. Beachten Sie Folgendes zu diesem Code:Note the following about this code:

  • Er verwendet die Datei TokenHelper.cs, die von den Office-Entwicklertools für Visual Studio generiert wird.It uses the TokenHelper.cs file that is generated by the Office Developer Tools for Visual Studio.

  • Der Code geht davon aus, dass es einen "Code"-Abfrageparameter gibt, der einen Autorisierungscode enthält. Das ist sicher, da die Seite nur von SharePoint aufgerufen wird, und nur dann, wenn ein Autorisierungscode weitergegeben wird.The code assumes that there is a "code" query parameter that holds an authorization code. This is safe because the page is only called by SharePoint and only when it is passing an authorization code.

  • Er verwendet das CSOM-Clientkontextobjekt, um auf SharePoint zuzugreifen, könnte dieses Objekt aber auch einfach auf dem Server zwischengespeichert und an eine andere Seite weitergeleitet haben.It uses the CSOM client context object to access SharePoint, but it could also have simply cached that object on the server and redirected to another page.

  • Die Methode GetClientContextWithAuthorizationCode verwendet den Autorisierungscode, um einen Zugriffscode zu erhalten.The GetClientContextWithAuthorizationCode method uses the authorization code to obtain an access code. Anschließend erstellt sie ein SharePoint-Clientkontextobjekt und ändert den Ereignishandler für das ExecutingWebRequest-Ereignis, damit der Handler das Zugriffstoken in alle Anfragen an SharePoint einbezieht.It then creates a SharePoint client context object and modifies the object's handler for the ExecutingWebRequest event so that the handler includes the access token in all requests to SharePoint. Das Zugriffstoken wird innerhalb des Objekts zwischengespeichert.The access token is, in effect, cached inside the object.

  • Die Methode GetClientContextWithAuthorizationCode sendet die Umleitungs-URL im rUrl-Parameter zurück an ACS, das sie jedoch als eine Form der Identifikation verwendet, falls der Autorisierungscode gestohlen wurde. ACS verwendet sie jedoch nicht, um eine erneute Umleitung durchzuführen, damit dieser Code keine Umleitungsendlosschleife an sich selbst durchführt.The GetClientContextWithAuthorizationCode method sends the redirect URL back to ACS in the rUrl parameter, but ACS uses it as a form of identification in case the authorization code has been stolen. ACS does not use it to redirect again, so this code does not loop endlessly redirecting to itself.

  • Der Code kann abgelaufene Zugriffstoken nicht verarbeiten.The code makes no provision for dealing with an expired access token. Nachdem das Clientkontextobjekt erstellt wurde, verwendet es das gleiche Zugriffstoken.After the client context object is created, it keeps using the same access token. Das Aktualisierungstoken wird nicht vom Clientkontextobjekt verwendet.It does not use the refresh token at all. Dies ist eine geeignete Strategie für Add-Ins, die nur in Sitzungen verwendet werden, die kürzer Dauern als die Lebensdauer eines Zugriffstokens.This is an appropriate strategy for add-ins that are used only in sessions that last less than the lifespan of an access token.

Ein komplexeres Beispiel zur Verwendung des Aktualisierungstoken zum Abrufen eines neuen Zugriffstokens finden Sie im nächsten Abschnitt.For a more complex example that uses the refresh token to get a new access token, see the next section.

public partial class RedirectAccept : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
        string authCode = Request.QueryString["code"];
        Uri rUri = new Uri("https://contoso.com/RedirectAccept.aspx");

        using (ClientContext context = TokenHelper.GetClientContextWithAuthorizationCode(
            "https://fabrikam.sharepoint.com/", 
            "00000003-0000-0ff1-ce00-000000000000",
            authCode,
            "1ee82b34-7c1b-471b-b27e-ff272accd564".
            rUri))
       {
           context.Load(context.Web);
           context.ExecuteQuery();

           Response.Write("<p>" + context.Web.Title + "</p>");
       }
    }
}


Zugrunde liegender Beispielcode für eine Seite, die auf SharePoint zugreiftSample code-behind for a page that accesses SharePoint

Im Folgenden sehen Sie den Code, der einer Default.aspx-Seite zugrunde liegt.The following is code-behind for a Default.aspx page. Diese Seite geht von einem Szenario aus, in dem die Default-Seite die Startseite für das Add-In und außerdem die registrierte Umleitungs-URL für das Add-In ist.This page assumes a scenario in which the Default page is the start page for the add-in and is also the registered Redirect URL for the add-in. Beachten Sie Folgendes zu diesem Code:Note the following about this code:

  • Die Page_Load-Methode überprüft zuerst, ob die Abfragezeichenfolge einen Autorisierungscode enthält.The Page_Load method first checks for an authorization code in the query string. Es ist ein Autorisierungscode vorhanden, wenn der Browser von SharePoint auf die Seite umgeleitet wurde.There is one if the browser was redirected to the page by SharePoint. Wenn ein Autorisierungscode vorhanden ist, verwendet der Code ihn, um ein neues Aktualisierungstoken abzurufen, das für die Dauer der Sitzung in einem permanenten Cache zwischengespeichert wird.If there is one, the code uses it to get a new refresh token, which it caches in a durable cache that lasts across sessions.

  • Die Methode überprüft dann, ob ein Aktualisierungstoken im Cache vorhanden ist.The method then checks for a refresh token in the cache.

    • Wenn keins vorhanden ist, ruft die Methode eins ab, indem sie SharePoint mitteilt, welche Berechtigungen sie benötigt (Schreibberechtigungen im Webbereich) und einen Autorisierungscode bei SharePoint anfordert. Der Benutzer wird aufgefordert, die Berechtigung zu gewähren. Wenn sie gewährt wird, ruft SharePoint den Autorisierungscode von ACS ab und sendet ihn in einer Umleitung als Abfrageparameter auf dieselbe Seite zurück.If there isn't one, it gets one by telling SharePoint the permissions it needs (Write permission at Web scope) and asking SharePoint for an authorization code. The user is prompted to grant the permission, and if it is granted, SharePoint gets the authorization code from ACS and sends it back as a query parameter on a redirect to this same page.

    • Liegt ein zwischengespeichertes Aktualisierungstoken vor, verwendet die Methode es, um ein Zugriffstoken direkt von ACS abzurufen.If there is a cached refresh token, the method uses it to obtain an access token directly from ACS. Wie im Beispiel am Ende des vorhergehenden Abschnitts des Artikels wird das Zugriffstoken zum Erstellen eines SharePoint-Clientkontextobjekts verwendet.Just as in the example at the end of the preceding section of this article, the access token is used to create a SharePoint client context object. Mithilfe eines zwischengespeicherten Aktualisierungstokens direkt von ACS muss beim Start der Sitzung kein zusätzlicher Netzwerkaufruf an SharePoint erfolgen, sodass Benutzer, die das Add-In innerhalb der Lebensdauer des Aktualisierungstokens im Cache erneut verwenden, schneller starten können.Using a cached refresh token to get an access token directly from ACS avoids the additional network call to SharePoint on session startup, so users rerunning the add-in within the lifespan of the refresh token cache experience faster startup.

  • Wie im Beispiel am Ende des vorhergehenden Abschnitts kann der Code abgelaufene Token nicht verarbeiten.Just as in the example at the end of the preceding section, this code makes no provision for dealing with an expired access token. Nachdem das Clientkontextobjekt erstellt wurde, verwendet es das gleiche Zugriffstoken.After the client context object is created, it keeps using the same access token. Ein Schutz vor einem abgelaufenen Zugriffstoken besteht darin, das Zugriffstoken zusätzlich zum Aktualisierungstoken zwischenzuspeichern.One way to protect against an expired access token is to cache the access token, in addition to the refresh token. Sie ändern dann den folgenden Code so, dass er die GetAccessToken-Methode nur abruft, wenn sich kein abgelaufener Zugriffstoken im Cache befindet.You would then modify the following code so that it calls the GetAccessToken method only if there isn't an unexpired access token in the cache.

    Während das Aktualisierungstoken auf dem Client zwischengespeichert werden kann, z. B. in einem Cookie, kann sich das Zugriffstoken aus Sicherheitsgründen nur in einem serverseitigen Cache befinden.However, while it is acceptable to have the refresh token cached on the client, in a cookie, for example, the access token should only be in a server-side cache for security reasons. Das Aktualisierungstoken ist verschlüsselt und kann nur von ACS entschlüsselt werden.The refresh token is encrypted and can only be unencrypted by ACS. Aber das Zugriffstoken ist lediglich codiert (mit Base-64-Codierung) und kann ganz einfach durch einen Man-in-the-Middle-Angriff decodiert werden.But the access token is merely encoded (with Base 64 encoding) and can be easily decoded by a man-in-the-middle attack.

  • Die in diesem Code referenzierte TokenCache-Klasse ist weiter unten in diesem Abschnitt definiert.The TokenCache class that is referred to in this code is defined later in this section.

Code, der einer Default.aspx-Seite zugrunde liegtCode-behind for a Default.aspx page

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.SharePoint.Samples;
using Microsoft.SharePoint.Client;

namespace DynamicAppPermissionRequest
{
    public partial class Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            Uri sharePointSiteUrl = new Uri("https://fabrikam.sharpoint.com/print/");

            if (Request.QueryString["code"] != null)
            {
                TokenCache.UpdateCacheWithCode(Request, Response, sharePointSiteUrl);
            }

            if (!TokenCache.IsTokenInCache(Request.Cookies))
            {
                Response.Redirect(TokenHelper.GetAuthorizationUrl(sharePointSiteUrl.ToString(), 
                                                                  "Web.Write"));
            }
            else
            {
                string refreshToken = TokenCache.GetCachedRefreshToken(Request.Cookies);
                string accessToken = 
                TokenHelper.GetAccessToken(
                           refreshToken, 
                           "00000003-0000-0ff1-ce00-000000000000", 
                           sharePointSiteUrl.Authority, 
                           TokenHelper.GetRealmFromTargetUrl(sharePointSiteUrl)).AccessToken;

                using (ClientContext context = 
                       TokenHelper.GetClientContextWithAccessToken(sharePointSiteUrl.ToString(), 
                                                                   accessToken))
                {
                    context.Load(context.Web);
                    context.ExecuteQuery();

                    Response.Write("<p>" + context.Web.Title + "</p>");
                }
            }
        }
    }
}

Es folgt ein Codebeispiel für ein Token-Cachemodul, das der vorherige Beispielcode abruft.The following is a code example for a token cache module that the previous sample code calls. Als Cache werden Cookies verwendet.It uses cookies as the cache. Es gibt andere Optionen zum Zwischenspeichern.There are other caching options. Ausführliche Informationen finden Sie unter Handhabung von Sicherheitstoken in vom Anbieter gehosteten Add-Ins für SharePoint mit niedriger Vertrauensebene.For more information, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

Codebeispiel für ein Token-CachemodulCode example for a token cache module

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using Microsoft.SharePoint.Samples;

namespace DynamicAppPermissionRequest
{
    public static class TokenCache
    {
        private const string REFRESH_TOKEN_COOKIE_NAME = "RefreshToken";

        public static void UpdateCacheWithCode(HttpRequest request, 
                                               HttpResponse response, 
                                               Uri targetUri)
        {
            string refreshToken = 
                TokenHelper.GetAccessToken(
                    request.QueryString["code"], 
                    "00000003-0000-0ff1-ce00-000000000000", 
                    targetUri.Authority, 
                    TokenHelper.GetRealmFromTargetUrl(targetUri), 
                    new Uri(request.Url.GetLeftPart(UriPartial.Path)))
                   .RefreshToken;
            SetRefreshTokenCookie(response.Cookies, refreshToken);
            SetRefreshTokenCookie(request.Cookies, refreshToken);
        }

        internal static string GetCachedRefreshToken(HttpCookieCollection requestCookies)
        {
            return GetRefreshTokenFromCookie(requestCookies);
        }

        internal static bool IsTokenInCache(HttpCookieCollection requestCookies)
        {
            return requestCookies[REFRESH_TOKEN_COOKIE_NAME] != null;
        }

        private static string GetRefreshTokenFromCookie(HttpCookieCollection cookies)
        {
            if (cookies[REFRESH_TOKEN_COOKIE_NAME] != null)
            {
                return cookies[REFRESH_TOKEN_COOKIE_NAME].Value;
            }
            else
            {
                return null;
            }
        }

        private static void SetRefreshTokenCookie(HttpCookieCollection cookies, 
                                                  string refreshToken)
        {
            if (cookies[REFRESH_TOKEN_COOKIE_NAME] != null)
            {
                cookies[REFRESH_TOKEN_COOKIE_NAME].Value = refreshToken;
            }
            else
            {
                HttpCookie cookie = new HttpCookie(REFRESH_TOKEN_COOKIE_NAME, 
                                                   refreshToken);
                cookie.Expires = DateTime.Now.AddDays(30);
                cookies.Add(cookie);
            }
        }
    }
}


Siehe auchSee also