Tipos de política de autorização dos suplementos no SharePoint
Antes de ler este artigo, familiarize-se primeiro com os artigos Permissões de suplementos no SharePoint e Fluxo de token OAuth de contexto para suplementos do SharePoint.
Visão geral dos tipos de política de autorização dos suplementos
O SharePoint fornece três tipos de políticas de autorização:
Política somente suplemento. Quando a política somente suplemento é usada, o SharePoint verifica apenas as permissões da entidade de segurança do suplemento. As verificações de autorização serão aprovadas somente se o suplemento atual tiver permissões suficientes para executar a ação em questão, independentemente das permissões do usuário atual (se houver).
Um suplemento de aprovação de despesas é um exemplo de um suplemento que pode ser projetado para usar essa política. O suplemento permite que usuários que não tinham a permissão para aprovar despesas, aprovem despesas abaixo de um determinado valor. Para ver um exemplo, confira o cenário na próxima seção.
Observação
Certas APIs exigem um contexto de usuário e não podem ser executadas com uma política somente suplemento. Isso inclui muitas APIs para interação com o Project Server e o Project Online e para a realização de consultas de pesquisa.
Política somente usuário. Quando a política somente usuário é usada, o SharePoint verifica apenas as permissões do usuário. O SharePoint usa essa política quando o usuário está acessando recursos diretamente sem usar um suplemento, como quando um usuário abre primeiro a página inicial de um site do SharePoint ou acessa APIs do SharePoint a partir do PowerShell.
Política de usuário+suplemento. Quando a política de usuário+suplemento é usada, o SharePoint verifica as permissões do usuário e da entidade do suplemento. As verificações de autorização só serão bem-sucedidas se o usuário atual e o suplemento tiverem permissões para executar a ação em questão.
Por exemplo, essa política é usada quando um suplemento do SharePoint deseja obter acesso aos recursos do usuário no SharePoint. (O código nos componentes remotos do suplemento do SharePoint precisa ser criado para fazer chamadas de usuário+suplemento para o SharePoint).
Confira um exemplo de cenário de um suplemento que usa a política somente suplemento
Vamos supor que um gerente de vendas da Contoso, Antônio, compre um suplemento de envio de despesas que use a política somente suplemento. Quando Antônio decidir comprar o suplemento, ele será solicitado a permitir que o suplemento eleve as permissões de usuário, ou seja, permita que o suplemento faça chamadas somente suplemento para o SharePoint. Antônio concede ao suplemento as permissões solicitadas. Em seguida, ele compra licenças suficientes do suplemento para todos os vendedores da Contoso e instala o suplemento no site do SharePoint da equipe de vendas.
Em breve, os vendedores estarão enviando relatórios de despesas usando o novo suplemento de envio de despesas. Como regra, os vendedores não podem aprovar seus próprios relatórios de despesas, mas isso poderá ser feito se eles usarem o suplemento já que Antônio concedeu a eles a capacidade de aprovar automaticamente relatórios com valores inferiores a US$ 50. O suplemento automaticamente atribui a Antônio uma tarefa para aprovar relatórios de US$ 50 ou com valores superiores.
Isso pode ser implementado com a permissão Gravar no Suplemento do SharePoint para uma lista do SharePoint de despesas aprovadas. No entanto, entre os usuários, apenas os gerentes de recursos humanos têm permissão para gravar na lista. O código no suplemento é projetado para adicionar a despesa à lista e fazer uma chamada somente suplemento para o SharePoint sempre que a despesa for inferior a US$ 50. Como as permissões do usuário não estão marcadas, os envios inferiores a US$ 50 são adicionados automaticamente à lista de despesas aprovadas, mesmo que o usuário não tenha permissão para gravar na lista.
Como os suplementos obtêm permissão para usar a política somente suplemento
Para poder fazer chamadas somente suplemento para o SharePoint, seu suplemento deve solicitar permissão para usar a política somente suplemento. Esta solicitação é feita no manifesto do suplemento. Para fazer isso, inclua o atributo AllowAppOnlyPolicy no elemento AppPermissionRequests e defina-o como true, conforme mostrado na marcação a seguir:
<AppPermissionRequests AllowAppOnlyPolicy="true">
...
</AppPermissionRequests>
Observação
Anteriormente, os Suplementos do SharePoint eram chamados de "aplicativos do SharePoint". Para manter a compatibilidade com versões anteriores, o esquema de manifesto do aplicativo não foi alterado, portanto, a cadeia de caracteres "app" aparece em muitos nomes de elemento e atributo.
Um usuário que instala o suplemento é solicitado a aprovar essa solicitação. Se o suplemento solicitar permissões com escopo de locatário, somente um administrador de locatários poderá conceder o uso da política somente suplemento, portanto, somente um administrador de locatários poderá instalar o suplemento.
Se o suplemento não solicitar permissões com escopo superior ao conjunto de sites, um administrador do conjunto de sites poderá instalar o suplemento. Para saber mais sobre escopos de permissões, confira Permissões de suplementos no SharePoint.
Como os suplementos fazem chamadas somente suplemento
A diferença entre uma chamada somente suplemento para o SharePoint e uma chamada de usuário+suplemento recai sobre o tipo de token de acesso incluído na chamada. O código a seguir mostra como obter tokens de acesso de usuário+suplemento e somente suplemento no código gerenciado. Há uma codificação detalhada no arquivo TokenHelper.cs (ou .vb) que as Ferramentas de Desenvolvedor do Office para Visual Studio adicionam automaticamente ao projeto no 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.
...
}
Observação
Os suplementos que não fazem chamadas autenticadas do OAuth (por exemplo, suplementos que são apenas JavaScript em execução na Web do suplemento) não podem usar a política somente suplemento. Eles podem solicitar a permissão, mas não podem aproveitá-la, pois isso exige a transmissão de um token OAuth somente suplemento. Somente suplementos com aplicativos Web em execução fora do SharePoint podem criar e transmitir tokens somente suplemento.
Em geral, é necessário que um usuário atual esteja presente para que uma chamada seja feita. No caso de uma política somente suplemento, o SharePoint cria um SHAREPOINT\APP, semelhante ao usuário do SHAREPOINT\SYSTEM existente. Todas as solicitações somente suplemento são feitas pelo SHAREPOINT\APP. Não é possível autenticar como SHAREPOINT\APP com a autenticação baseada em usuário.
Diretrizes para usar a política somente suplemento
Como as chamadas somente suplemento elevam efetivamente privilégios de usuário, você deve ser conservador na criação de suplementos que pedem permissão para fazê-las. As chamadas deverão usar a política somente suplemento apenas se:
O suplemento precisa elevar suas permissões acima do usuário para uma chamada específica; por exemplo, para aprovar um relatório de despesas de acordo com condições avaliadas pelo suplemento.
O suplemento não estiver agindo em nome de nenhum usuário; por exemplo, um suplemento que executa tarefas de manutenção à noite em uma biblioteca de documentos do SharePoint.