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 complément uniquement Lorsque la stratégie de complément uniquement est utilisée, SharePoint vérifie uniquement les autorisations du principal de complément. Les vérifications d’autorisation réussissent uniquement si le complément en cours dispose des autorisations nécessaires pour effectuer l’action en question, indépendamment des autorisations de l’utilisateur actuel (s’il y en a un).
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.
Remarque
Certaines API nécessitent un contexte utilisateur et ne peuvent pas être exécutées avec une stratégie de complément uniquement. 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 d’utilisateur+complément est utilisée, SharePoint vérifie les autorisations de l’utilisateur et du principal de complément. Les contrôles d’autorisation réussissent uniquement si l’utilisateur et le complément disposent d’autorisations pour effectuer l’action en question.
Par exemple, cette stratégie est utilisée lorsqu’un complément SharePoint a besoin d’accéder aux ressources de l’utilisateur sur SharePoint. (Le code des composants à distants du complément SharePoint doit être conçu pour effectuer des appels utilisateur+complément vers SharePoint.)
Exemple de scénario d’un complément qui utilise la stratégie de complément uniquement
Imaginons qu’Adam, responsable des ventes chez Contoso, achète un complément de note de frais qui utilise la stratégie complément uniquement. Lorsque Adam opte pour acheter le complément, il est invité à autoriser celui-ci à élever les autorisations utilisateur. Autrement dit à autoriser le complément à effectuer des appels de type complément uniquement à destination de SharePoint. Adam accorde au complément les autorisations demandées. Il achète ensuite des licences du complément en nombre suffisant pour l’ensemble du personnel commercial de Contoso, puis installe le complément sur le site web SharePoint de l’équipe des ventes.
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 €.
Cette fonction peut être implémentée en accordant au complément SharePoint une autorisation en écriture sur une liste SharePoint des dépenses approuvées. Toutefois, parmi les utilisateurs, seuls les responsables des ressources humaines bénéficient d’une autorisation en écriture sur la liste. Le code du complément est conçu pour ajouter la note de frais à la liste en effectuant un appel de type complément uniquement vers SharePoint à chaque fois que la dépense est inférieure à 50 €. Étant donné que les autorisations de l’utilisateur ne sont pas vérifiées, les soumissions de n’importe quel utilisateur inférieures à 50 € sont ajoutées automatiquement à la liste des dépenses approuvées, même si l’utilisateur ne dispose d’autorisations en écriture sur 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>
Remarque
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 dans l’étendue client, seul un administrateur de client peut accorder l’utilisation de la stratégie de complément uniquement, et sera donc le seul à pouvoir 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.
...
}
Remarque
Les compléments qui n’effectuent pas d’appels authentifiés par OAuth (par exemple, les compléments en JavaScript seulement, exécutés sur le site web de complément) ne peuvent pas utiliser la stratégie de complément uniquement. Ils peuvent demander l’autorisation, mais ne sont pas en mesure d’en bénéficier car cela nécessiterait la transmission d’un jeton OAuth de type complément uniquement. Seuls les compléments dont les applications web sont exécutées en dehors de SharePoint peuvent créer et transmettre des jetons de complément uniquement.
En règle générale, un utilisateur doit obligatoirement être présent pour qu’un appel soit effectué. Dans le cas d’une stratégie de complément uniquement, SharePoint crée un SHAREPOINT\APP semblable à l’utilisateur SHAREPOINT\SYSTEM existant. Toutes les demandes de type complément uniquement sont effectuées par SHAREPOINT\APP. Il est impossible de s’authentifier en tant que SHAREPOINT\APP au moyen d’une authentification basée sur l’utilisateur.
Instructions d’utilisation de la stratégie de complément uniquement
Étant donné que les appels de complément uniquement élèvent effectivement les privilèges d’utilisateur, faites preuve de prudence lorsque vous créez des compléments qui demandent l’autorisation d’en effectuer. Les appels ne doivent utiliser la stratégie de complément que 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.