Compartilhar via

Privilégios elevados e somente aplicativo no modelo de suplemento do SharePoint

  • Artigo

A abordagem usada para elevar privilégios no seu código é diferente no novo modelo de Suplemento do SharePoint do que era com o código de confiança total. Em um cenário típico de FTC (código de confiança total)/Solução de Farm), a API RunWithElevatedPrivileges é usada com o código de modelo de objeto do lado do servidor do SharePoint e implantada por meio de Soluções de Farm.

Em um cenário de modelo de suplemento do SharePoint, a permissão ou conta de serviço AllowAppOnlyPolicy é usada para permitir que o usuário atual execute operações que ele não está autorizado a executar.

Diretrizes gerais

Como regra geral, gostaríamos de fornecer as seguintes diretrizes gerais para aumentar os privilégios no código.

  • AllowAppOnlyPolicy não funciona com

    • Pesquisa - se o destino for o SharePoint local. O suporte do SharePoint Online para ele foi adicionado (postagem do blog)

    • Operações de CSOM do perfil de usuário, exceto que a API de atualização em massa do perfil de usuário pode ser usada somente com permissões de aplicativo

    • Atualização de entradas de serviço de taxonomia (gravação) – leitura funciona

      Observação

      Nesses cenários, você precisa usar uma conta de serviço.

  • AllowAppOnlyPolicy é semelhante à RunWithElevatedPrivileges, mas não exatamente igual.

    • AllowAppOnlyPolicy executa o código com base em permissões concedidas ao suplemento do SharePoint, não em nome de outro usuário que tenha as permissões apropriadas para executar uma operação.

Aqui está um exemplo de como retornar um token de política somente aplicativo e usá-lo para criar um objeto de contexto.

Uri siteUrl = new Uri(ConfigurationManager.AppSettings["MySiteUrl"]);
try
  {
    //Connect to the give site using App Only token
    string realm = TokenHelper.GetRealmFromTargetUrl(siteUrl);
    var token = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, siteUrl.Authority, realm).AccessToken;

    using (var ctx = TokenHelper.GetClientContextWithAccessToken(siteUrl.ToString(), token))
    {
      // Perform operations using the app only token access.
    }
  }
  catch (Exception ex)
  {
    Console.WriteLine("Error in execution: " + ex.Message);
  }

  • Ao usar o AllowAppOnlyPolicy, tenha em mente que ele só funciona em suplementos do SharePoint hospedados pelo servidor.

  • AllowAppOnlyPolicy não executa códigos em nome de um usuário e, portanto, talvez não seja apropriado para todas as situações.

  • Contas de serviço são definidas no SharePoint.

    • Em um locatário do Office 365, dependendo de quais recursos seus requisitos de código possuem, as contas de serviço podem precisar de uma licença do Office 365 atribuída a elas.

    • Você pode criar contas de serviço por suplementos do SharePoint ou usar uma única conta para todos os suplementos do SharePoint.

    • Crie nomes claros e descritivos para as contas de serviço para que você possa acompanhar facilmente as operações que forem executadas.

      Por exemplo: se o seu suplemento do SharePoint modificar itens de lista, a coluna Modificado por dos itens da lista exibirá o nome da conta de serviço associado ao suplemento do SharePoint.

  • Ao autenticar com contas de serviço, você deve recuperar o nome de usuário e a senha da conta de serviço.

    • O trecho do código abaixo ilustra o uso de um nome de usuário e senha para autenticar.

    • Tome cuidado para armazenar e recuperar o nome de usuário e senha de forma segura.

      using (ClientContext context = new ClientContext("https://tenancy.sharepoint.com"))
{

  // Use default authentication mode
  context.AuthenticationMode = ClientAuthenticationMode.Default;
  // Specify the credentials for the account that will execute the request
  context.Credentials = new SharePointOnlineCredentials("User Name", "Password");
}

Opções para elevar permissões

Você tem algumas opções para elevar permissões.

  • OAuth (AllowAppOnlyPolicy)
    • S2S (subopção)
    • ACS (subopção)
  • Conta de serviço
    • Código hospedado remotamente (exemplo: Azure WebJob)

Importante

O uso do Azure ACS (Controle de Acesso Services) para o SharePoint Online foi desativado a partir de 27 de novembro de 2023, confira o comunicado completo de aposentadoria para saber mais. O uso do ACS do Azure fora do contexto do SharePoint já foi desativado em 7 de novembro de 2018 e agora é o fim da vida útil.

A aposentadoria significa que o recurso não receberá novos investimentos, mas ainda tem suporte. O fim da vida útil significa que o recurso será descontinuado e não está mais disponível para uso.

OAuth (AllowAppOnlyPolicy)

Nesta opção, a AllowAppOnlyPolicy é definida como true no elemento AppPermissionRequests e as permissões são definidas no manifesto do suplemento do SharePoint. OAuth é usada para retornar tokens de acesso para permitir que os suplementos do SharePoint executem operações que ele tem permissões para executar.

Subopção S2S

A subopção S2S funciona somente em ambientes do SharePoint local.

Durante a autenticação por OAuth em um cenário S2S, o método TokenHelper::GetS2SAccessTokenWithWindowsIdentity é usado para retornar o token de acesso do suplemento do SharePoint. O token de acesso permite que o suplemento do SharePoint realize qualquer operação concedida no manifesto do suplemento do SharePoint.

Esta opção não executa códigos em nome de um usuário e, portanto, talvez não seja apropriada para todas as situações.

Quando isso é apropriado?

Quando você precisa elevar privilégios em um cenário S2S do SharePoint, essa é uma boa opção porque ela funciona com S2S e é muito mais fácil de implementar.

Introdução

O artigo seguinte demonstra como usar AllowAppOnlyPolicy com S2S.

Subopção ACS

A subopção ACS funciona em ambientes locais do Office 365 e do SharePoint.

Durante a autenticação por OAuth em um cenário ACS, o métodoTokenHelper::GetAppOnlyAccessTokenmethod é usado para retornar o token de acesso do suplemento do SharePoint. Em seguida, o método TokenHelper::GetClientContextWithAccessToken é invocado para retornar o contexto de cliente necessário para realizar qualquer operação que o suplemento do SharePoint tenha permissão para realizar com base nas permissões concedidas no manifesto do suplemento do SharePoint.

Esta opção não executa códigos em nome de um usuário e, portanto, talvez não seja apropriada para todas as situações.

Quando isso é apropriado?

Quando você precisa elevar privilégios em um cenário ACS do SharePoint, essa é uma boa opção porque ela funciona com ACS e é muito mais fácil de implementar. Esta opção é ideal quando você tem um ambiente do SharePoint local que tenha uma relação de confiança estabelecida com ACS. Esta é sua única opção OAuth quando você tem um ambiente do SharePoint do Office 365.

Introdução

O artigo seguinte demonstra como usar AllowAppOnlyPolicy com ACS.

Importante

O Controle de Acesso do Azure (ACS), um serviço do Azure Active Directory (Azure AD) será desativado em 7 de novembro de 2018. Essa desativação não afeta o modele do Suplemento do SharePoint que usa o nome de host https://accounts.accesscontrol.windows.net (que não é afetado por ela). Para saber mais, confira Impacto da desativação do Controle de Acesso do Azure para Suplementos do SharePoint.

Conta de serviço

Neste padrão, a classe SharePointOnlineCredentials é usada para estabelecer o contexto de um usuário que executa o código.

Quando isso é apropriado?

Quando você precisar executar código em nome de um usuário específico (conta de serviço), essa é uma boa opção porque ela executa ações do usuário (conta de serviço) e as permissões do suplemento do SharePoint.

Introdução

O artigo a seguir demonstra como a classe SharePointOnlineCredentials é usada para estabelecer o contexto de um usuário que executa o código.

Aplicável a

  • Office 365 Multilocatário (MT)
  • Office 365 dedicado (D) parcialmente
  • SharePoint 2013 local, parcialmente

Os padrões para dedicados e locais são idênticos às técnicas de modelo do suplemento do SharePoint, mas há diferenças nas possíveis tecnologias que podem ser usadas.