Conceder acesso usando o SharePoint App-Only

O App-Only do SharePoint é o modelo mais antigo, mas ainda muito relevante, de configurar entidades de aplicativo. Esse modelo funciona tanto para o SharePoint Online quanto para o SharePoint local (edição 2013/2016/2019/assinatura) e é ideal para preparar seus aplicativos para migração do SharePoint local para o SharePoint Online. As etapas abaixo mostram como configurar uma entidade de aplicativo com permissões de controle total do locatário, mas você também pode conceder apenas permissões de leitura usando essa abordagem.

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.

Para novos locatários, os aplicativos que usam um token de acesso somente aplicativo ACS são desabilitados por padrão. Recomendamos usar o modelo Azure AD somente aplicativo, que é moderno e mais seguro. Mas você pode alterar o comportamento executando 'set-spotenant -DisableCustomAppAuthentication $false' (precisa do powershell de administração mais recente do SharePoint).

Configurar uma entidade de segurança somente aplicativo com permissões de locatário

Observação

O administrador da coleção de sites não pode registrar o suplemento com o Azure ACS no AppRegNew.aspx por padrão, a menos que seja permitido explicitamente pelo administrador de locatário do SharePoint. Para obter mais informações, consulte Set-SPOTenant.

Navegue até um site no locatário (por exemplohttps://contoso.sharepoint.com) e chame a página appregnew.aspx (por exemplo). https://contoso.sharepoint.com/_layouts/15/appregnew.aspx Nesta página, clique no botão Gerar para gerar uma ID do cliente e um segredo do cliente e preencha as informações restantes, como mostrado na captura de tela abaixo.

Importante

Armazene as informações recuperadas (id do cliente e segredo do cliente), pois você precisará disso na próxima etapa!

A próxima etapa é conceder permissões à entidade de segurança recém-criada. Como estamos concedendo permissões com escopo de locatário, essa concessão só pode ser feita por meio da página appinv.aspx no site de administração do locatário. Você pode acessar este site por meio de https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx. Depois que a página for carregada, adicione a ID do cliente e procure a entidade criada:

Para conceder permissões, você precisará fornecer a permissão XML que descreve as permissões necessárias. Como este aplicativo precisa ser capaz de acessar todos os sites + também usa a pesquisa somente com aplicativo, ele precisa de permissões abaixo:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>

Ao clicar em Criar, você será presenteado com uma caixa de diálogo de consentimento de permissão. Pressione Trust It para conceder as permissões:

Importante

Proteja a combinação de ID/segredo do cliente criado, assim como sua conta de administrador. Usando essa id/segredo do cliente, é possível ler/atualizar todos os dados em seu ambiente do SharePoint Online!

Com o trabalho de preparação concluído, vamos continuar até o próximo capítulo mostrando como você pode usar a entidade de aplicativo criada por meio de sua id do cliente e combinação de segredo.

Usando essa entidade com o PowerShell PnP

Se você quiser utilizar o registro somente de aplicativo gerado com o PnP PowerShell, poderá fazê-lo conectando-se ao ambiente Do SharePoint Local ou Online usando:

Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/demo -ClientId [Your Client ID] -ClientSecret "[Your Client Secret]"

Observação

O PnP PowerShell é uma solução de software livre com uma comunidade ativa de suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

Usando essa entidade em seu aplicativo usando a biblioteca PnP Framework

Em uma primeira etapa, você adiciona o pacote nuget da biblioteca PnP Framework: https://www.nuget.org/packages/PnP.Framework. Depois que isso for feito, você poderá usar o constructo de código abaixo:

string siteUrl = "https://contoso.sharepoint.com/sites/demo";
using (var cc = new AuthenticationManager().GetACSAppOnlyContext(siteUrl, "[Your Client ID]", "[Your Client Secret]"))
{
    cc.Load(cc.Web, p => p.Title);
    cc.ExecuteQuery();
    Console.WriteLine(cc.Web.Title);
};

Usar essa entidade em seu aplicativo sem usar a biblioteca PnP Framework

Depois que a entidade de segurança for criada e consentida, você poderá usar a ID e o segredo da entidade para solicitar um acesso. A classe TokenHelper.cs usará a id e o segredo do arquivo de configuração do aplicativo.

using Microsoft.SharePoint.Client;
using System;

namespace AzureACSAuth
{
    class Program
    {
        static void Main(string[] args)
        {
            string siteUrl = "https://contoso.sharepoint.com/sites/demo";

            //Get the realm for the URL
            string realm = TokenHelper.GetRealmFromTargetUrl(new Uri(siteUrl));

            //Get the access token for the URL.  
            string accessToken = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, new Uri(siteUrl).Authority, realm).AccessToken;

            //Create a client context object based on the retrieved access token
            using (ClientContext cc = TokenHelper.GetClientContextWithAccessToken(siteUrl, accessToken))
            {
                cc.Load(cc.Web, p => p.Title);
                cc.ExecuteQuery();
                Console.WriteLine(cc.Web.Title);
            }
        }
    }
}

Um exemplo app.config se parece com este:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <!-- Use AppRegNew.aspx and AppInv.aspx to register client id with secret -->
    <add key="ClientId" value="[Your Client ID]" />
    <add key="ClientSecret" value="[Your Client Secret]" />
  </appSettings>
</configuration>

Observação

Você pode inserir facilmente a classe TokenHelper.cs em seu projeto adicionando o pacote nuget AppForSharePointOnlineWebToolkit à sua solução.