Add-In-Autorisierungsrichtlinientypen in SharePoint

  • Artikel

Bevor Sie diesen Artikel lesen, sollten Sie sich zuerst mit den Artikeln Add-In-Berechtigungen in SharePoint und OAuth-Ablauf mit Kontexttoken für SharePoint-Add-Ins vertraut machen.

Übersicht über Add-In-Autorisierungsrichtlinientypen

SharePoint bietet drei Arten von Autorisierungsrichtlinien:

  • Nur-Add-In-Richtlinie Wenn die reine Add-In-Richtlinie verwendet wird, überprüft SharePoint nur die Berechtigungen des Add-In-Prinzipals. Insbesondere sind bei Verwendung dieser Richtlinie Autorisierungsprüfungen nur erfolgreich, wenn das aktuelle Add-In über ausreichende Berechtigungen verfügen, um die fragliche Aktion auszuführen (unabhängig von den Berechtigungen des aktuellen Benutzers).

    Ein Ausgabengenehmigungs-Add-In ist ein Beispiel eines Add-Ins, das für die Verwendung dieser Richtlinie konzipiert werden kann. Durch dieses Add-In können Benutzer, die ansonsten keine Ausgaben genehmigen können, Ausgaben unter einem bestimmten Betrag genehmigen. Ein Beispiel finden Sie im szenario im nächsten Abschnitt.

    Hinweis

    Bestimmte APIs erfordern einen Benutzerkontext und können nicht mit einer Nur-Add-In-Richtlinie ausgeführt werden. Dazu gehören viele APIs für die Interaktion mit Project Server und Project Online und zum Ausführen von Suchabfragen.

  • Richtlinie nur für Benutzer. Wenn die Richtlinie nur für Benutzer verwendet wird, überprüft SharePoint nur die Berechtigungen für den Benutzer. SharePoint verwendet diese Richtlinie, wenn der Benutzer direkt auf Ressourcen zugreift, ohne ein Add-In zu verwenden, z. B. wenn ein Benutzer zum ersten Mal die Startseite einer SharePoint-Website öffnet oder über PowerShell auf SharePoint-APIs zugreift.

  • Benutzer-und-Add-In-Richtlinie Wenn die Benutzer-Add-In-Richtlinie verwendet wird, überprüft SharePoint die Berechtigungen des Benutzers und des Add-In-Prinzipals. Insbesondere ist bei Verwendung dieser Richtlinie eine Autorisierungsprüfung nur erfolgreich, wenn der aktuelle Benutzer und das Add-In über ausreichende Berechtigungen für die fragliche Aktion verfügt.

    Diese Richtlinie wird beispielsweise verwendet, wenn ein SharePoint-Add-In Zugriff auf die Ressourcen des Benutzers in SharePoint erhalten möchte. (Der Code in den Remotekomponenten der SharePoint-Add-In muss so konzipiert sein, dass Benutzer-und-Add-In-Aufrufe an SharePoint) erfolgen können.

Beispielszenario für ein Add-In, das die Nur-Add-In-Richtlinie verwendet

Angenommen, ein Vertriebsmanager bei Contoso, Adam, kauft eine Kostenvorlage-App, die die Nur-Add-In-Richtlinie verwendet. Beim Kauf des Add-Ins wird Adam aufgefordert, dem Add-In zu erlauben, Benutzerberechtigungen zu erhöhen. Adam erteilt dem Add-In die angeforderte Berechtigung. Anschließend erwirbt er genügend Lizenzen des Add-Ins für alle Contoso-Vertriebsmitarbeiter und installiert das Add-In auf der SharePoint-Website des Vertriebsteams.

Bald übermitteln die Vertriebsmitarbeiter Spesenabrechnungen mithilfe des neuen Spesenübermittlungs-Add-Ins. Vertriebsmitarbeiter können in der Regel ihre eigenen Spesenabrechnungen nicht genehmigen, aber sie können dies tun, wenn sie das Add-In verwenden, da Adam ihm die Möglichkeit gewährt hat, Berichte unter 50 US-Dollar automatisch zu genehmigen. Das Add-In weist Adam automatisch eine Aufgabe zu, um Berichte über 50 USD oder mehr zu genehmigen.

Dies kann implementiert werden, indem dem SharePoint-Add-In schreibberechtigung für eine SharePoint-Liste genehmigter Ausgaben erteilt wird. Unter den Benutzern verfügen jedoch nur Personalmanager über Schreibberechtigungen für die Liste. Der Code im Add-In ist so konzipiert, dass die Ausgaben der Liste hinzugefügt werden, indem sharePoint nur add-in aufgerufen wird, wenn die Kosten kleiner als 50 US-Dollar sind. Da die Berechtigungen des Benutzers nicht überprüft werden, werden die Übermittlungen von Benutzern unter 50 USD automatisch zur Liste genehmigter Ausgaben hinzugefügt, auch wenn der Benutzer nicht über die Schreibberechtigung für die Liste verfügt.

Informationen über das Anfordern der Berechtigung zur Verwendung der Nur-Add-In-Richtlinie für Add-Ins

Um nur Add-In-Aufrufe an SharePoint durchführen zu können, muss Ihr Add-In die Berechtigung für die Verwendung der Nur-Add-In-Richtlinie anfordern. Diese Anforderung wird im Add-In-Manifest gestellt. Dazu fügen Sie das AllowAppOnlyPolicy-Attribut zum AppPermissionRequests-Element hinzu und legen es auf true fest, wie im folgenden Markup gezeigt:

    <AppPermissionRequests AllowAppOnlyPolicy="true">
        ...
    </AppPermissionRequests>

Hinweis

SharePoint Add-ins used to be called "apps for SharePoint." To maintain backward compatibility, the app manifest schema was not changed, so the string "app" appears in many element and attribute names.

Ein Benutzer, der das Add-In installiert, wird aufgefordert, diese Anforderung zu genehmigen. Wenn das Add-In mandantenbezogene Berechtigungen anfragt, kann nur ein Mandantenadministrator die Verwendung der Nur-Add-In-Richtlinie gewähren, sodass nur ein Mandantenadministrator das Add-In installieren kann.

Wenn das Add-In keine Berechtigungen anfragt, die höher als die Websitesammlung sind, kann ein Websitesammlungsadministrator das Add-In installieren. Weitere Informationen zu Berechtigungsbereichen finden Sie unter Add-In-Berechtigungen in SharePoint.

Informationen zum Durchführen von Nur-Add-In-Aufrufen mit Add-Ins

Der Unterschied zwischen einem Nur-Add-In-Aufruf an SharePoint und einem Benutzer-und-Add-In-Aufruf ist der Typ des Zugriffstokens, das im Aufruf enthalten ist. Im folgenden Code sind die Benutzer-und-Add-In- und Nur-Add-In-Zugriffstokens im verwalteten Code dargestellt. Die detaillierte Programmierung erfolgt in der Datei TokenHelper.cs (oder .vb), das die Office-Entwicklertools für Visual Studio automatisch zum -Projekt in Visual Studio hinzufügen.

    string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
    if (contextTokenString != null)
    {
        //Get context token.
        SharePointContextToken contextToken =
            TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
        Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);

        //Get user+add-in access token.
        string accessToken =
            TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;

        ClientContext clientContext =
            TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);

        //Do something. 
        ...
        
        //Get add-in-only access token.
        string addinOnlyAccessToken = 
                TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, 
                                sharepointUrl.Authority, contextToken.Realm).AccessToken;
            //Do something.
            ...
    }

Hinweis

Add-Ins, die keine OAuth-authentifizierten Aufrufe tätigen (z. B. Add-Ins, bei denen es sich nur um JavaScript handelt, die im Add-In-Web ausgeführt werden), können die Nur-Add-In-Richtlinie nicht verwenden. Sie können die Berechtigung anfordern, aber sie können sie nicht nutzen, da hierfür ein reines Add-In-OAuth-Token übergeben werden muss. Nur Add-Ins mit Webanwendungen, die außerhalb von SharePoint ausgeführt werden, können nur Add-In-Token erstellen und übergeben.

Im Allgemeinen muss ein aktueller Benutzer vorhanden sein, damit ein Aufruf möglich ist. Im Fall einer reinen Add-In-Richtlinie erstellt SharePoint eine SHAREPOINT\APP, ähnlich dem vorhandenen SHAREPOINT\SYSTEM-Benutzer. Alle Nur-Add-In-Anforderungen werden von SHAREPOINT\APP gestellt. Es gibt keine Möglichkeit, sich über die benutzerbasierte Authentifizierung als SHAREPOINT\APP zu authentifizieren.

Anweisungen für die Verwendung der Nur-Add-In-Richtlinie

Da Nur-Add-In-Aufrufe Benutzerberechtigungen effektiv erhöhen, sollten Sie beim Erstellen von Add-Ins, die die Berechtigung anfordern, diese zu erstellen, vorsichtig sein. Aufrufe sollten die Nur-Add-In-Richtlinie nur in folgenden Fällen verwenden:

  • Die App muss ihre Berechtigungen für einen bestimmten Aufruf über die Berechtigungen des Benutzers hinaus erhöhen (z. B., um einen Kostenbericht unter von der App ausgewerteten Bedingungen zu genehmigen).

  • The add-in is not acting on behalf of any user; for example, an add-in that performs nightly maintenance tasks on a SharePoint document library.

Siehe auch