Types de stratégie d’autorisation des compléments dans SharePoint
Avant de lire cet article, vous devez vous familiariser avec les articles relatifs aux autorisations des compléments dans SharePoint et au flux OAuth de jeton de contexte pour les compléments SharePoint.
Vue d’ensemble des types de stratégie d’autorisation des compléments
SharePoint fournit trois types de stratégie d’autorisation :
stratégie de complément uniquement. Lorsque la stratégie de complément uniquement est utilisée, SharePoint vérifie uniquement les autorisations du principal du complément. Les vérifications d’autorisation réussissent uniquement si le complément actuel dispose des autorisations suffisantes pour effectuer l’action en question, indépendamment des autorisations de l’utilisateur actuel (le cas échéant).
Un complément d’approbation des dépenses, par exemple, peut être conçu pour utiliser cette stratégie. Il permet à des utilisateurs qui ne seraient pas en mesure d’approuver les dépenses d’approuver les dépenses inférieures à un certain montant. Un exemple est fourni dans le scénario de la section suivante.
Notes
Certaines APIs nécessitent un contexte utilisateur et ne peuvent pas être exécutées avec une politique d'add-in seulement. Il s'agit notamment de nombreuses API permettant d'interagir avec Project Server et Project Online et d'effectuer des requêtes de recherche.
Stratégie d’utilisateur uniquement. Lorsque la stratégie d’utilisateur uniquement est utilisée, SharePoint vérifie uniquement les autorisations de l’utilisateur. SharePoint utilise cette stratégie lorsque l’utilisateur accède aux ressources directement sans utiliser de complément, par exemple lorsqu’un utilisateur ouvre pour la première fois la page d’accueil d’un site SharePoint ou accède pour la première fois aux API SharePoint à partir de PowerShell.
Stratégie utilisateur+complément . Lorsque la stratégie utilisateur+complément est utilisée, SharePoint vérifie les autorisations de l’utilisateur et du principal du complément. Les vérifications d’autorisation réussissent uniquement si l’utilisateur actuel et le complément disposent des autorisations nécessaires pour effectuer l’action en question.
Par exemple, cette stratégie est utilisée lorsqu’un complément SharePoint souhaite accéder aux ressources de l’utilisateur sur SharePoint. (Le code dans les composants distants du complément SharePoint doit être conçu pour effectuer des appels utilisateur+complément à SharePoint.)
Exemple de scénario d’un complément qui utilise la stratégie de complément uniquement
Supposons qu'un responsable des ventes chez Contoso, Adam, achète un complément de soumission de notes de frais qui utilise la stratégie de complément uniquement. Lorsqu'Adam décide d'acheter le complément, il est invité à l'autoriser à élever les autorisations des utilisateurs, c'est-à-dire permettre au complément d'effectuer des appels de complément uniquement à SharePoint. Adam accorde au complément les autorisations demandées. Ensuite, il achète un nombre suffisant de licences du complément pour tous les commerciaux chez Contoso, et il installe le complément sur le site web SharePoint de l'équipe de vente.
Les commerciaux commencent rapidement à envoyer des notes de frais à l’aide du nouveau complément. Les commerciaux ne peuvent généralement pas approuver leurs propres notes de frais, mais sont autorisées à le faire avec le complément, car Adam a accordé la possibilité d’approuver automatiquement les notes inférieures à 50 €. Le complément affecte automatiquement à Adam une tâche d’approbation des notes de frais supérieures ou égales à 50 €.
Rapidement, les commerciaux soumettent les notes de frais à l'aide du nouveau complément. En général, les commerciaux ne peuvent pas approuver leurs propres notes de frais mais le complément leur permet de le faire car Adam lui a accordé cette possibilité pour les dépenses inférieures à 50 €, car il a défini le complément de sorte qu'il approuve automatiquement les notes de frais inférieures à 50 €. Pour l'approbation des notes de frais d'un montant supérieur ou égal à 50 €, le complément lui affecte automatiquement une tâche. Cela pourrait être implémenté en donnant au Complément SharePoint une autorisation d'accès en écriture à une liste SharePoint de dépenses approuvées. Toutefois, parmi les utilisateurs, seuls les responsables des ressources humaines disposent de l'autorisation d'accès en écriture à la liste. Le code du complément est conçu pour ajouter la dépense à la liste en effectuant un appel de complément uniquement à SharePoint dès que la dépenses est inférieure à 50 €. Comme les autorisations de l'utilisateur ne sont pas vérifiées, les soumissions d'utilisateur inférieures à 50 € sont automatiquement ajoutées à la liste des dépenses approuvées, même si l'utilisateur ne dispose pas d'autorisation d'accès en écriture à la liste.
Comment les compléments obtiennent l’autorisation d’utiliser la stratégie de complément uniquement
Pour pouvoir effectuer des appels de complément uniquement à SharePoint, le complément doit demander l'autorisation d'utiliser la stratégie de complément uniquement. Cette demande est faite dans le manifeste de complément. Pour ce faire, ajoutez l'attribut AllowAppOnlyPolicy à l'élément AppPermissionRequests et affectez-lui la valeur true, tel qu'indiqué dans le balisage suivant :
<AppPermissionRequests AllowAppOnlyPolicy="true">
...
</AppPermissionRequests>
Notes
Les compléments SharePoint s’appelaient auparavant « applications pour SharePoint ». Pour maintenir la compatibilité descendante, le schéma du manifeste d’application n’a pas été modifié, de sorte que la chaîne « app » apparaît dans de nombreux noms d’éléments et d’attributs.
Un utilisateur qui installe le complément est invité à approuver cette demande. Si le complément demande des autorisations limitées au locataire, seul un administrateur client peut accorder l’utilisation de la stratégie de complément uniquement, de sorte que seul un administrateur client peut installer le complément.
Si le complément ne demande pas d’autorisations à un niveau d’étendue plus élevé que la collection de sites, un administrateur de collection de sites peut également l’installer. Pour plus d’informations sur les étendues d’autorisation, reportez-vous à la rubrique Autorisations de compléments dans SharePoint.
Comment les compléments émettent des appels de complément uniquement
La différence entre un appel de complément uniquement à SharePoint et un appel d'utilisateur et de complément réside dans le type de jeton d'accès qui est inclus dans l'appel. Le code suivant montre comment faire obtenir des jetons d'accès d'utilisateur et de complément, et de complément uniquement dans du code managé. Le codage détaillé est à votre disposition dans le fichier TokenHelper.cs (ou .vb) que les Outils de développement Office pour Visual Studio ajoutent automatiquement au projet d' dans Visual Studio.
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.
...
}
Notes
Les compléments qui ne font pas d'appels OAuth authentifiés (par exemple, les compléments JavaScript uniquement qui s'exécutent dans le service web de complément) ne peuvent pas utiliser la stratégie de complément uniquement. Elles peuvent demander l'autorisation, mais elles ne sont pas en bénéficier car cela nécessite le passage d'un jeton OAuth de complément uniquement. Seuls les compléments qui ont des applications web qui s'exécutent hors de SharePoint peuvent créer et passer des jetons de complément uniquement.
En général, un utilisateur actuel doit être présent pour passer un appel. Dans le cas d'une stratégie de complément uniquement, SharePoint crée un SHAREPOINTAPP, similaire à l'utilisateur SHAREPOINTSYSTEM existant. Toutes les demandes de complément uniquement sont faites par SHAREPOINTAPP. Il n'est pas possible de s'authentifier comme SHAREPOINTAPP via une authentification utilisateur.
Instructions d’utilisation de la stratégie de complément uniquement
Étant donné que les appels de complément uniquement élever efficacement les privilèges utilisateur, vous devez être prudent dans la création de compléments qui demandent l’autorisation de les créer. Les appels doivent utiliser la stratégie de complément uniquement si :
le complément doit élever ses autorisations au-dessus de celles de l'utilisateur pour un appel spécifique, par exemple pour approuver un rapport de note de frais d'après des conditions évaluées par le complément ;
le complément n'agit au nom d'aucun utilisateur, par exemple un complément qui effectue des tâches de maintenance nocturne sur une bibliothèque de documents SharePoint.