Conceder acesso com o SharePoint App-Only

O SharePoint App-Only é o modelo mais antigo, mas ainda muito relevante, de configuração de principais de aplicações. Este modelo funciona tanto para o SharePoint Online como para o SharePoint no local (edição 2013/2016/2019/subscrição) e é ideal para preparar as suas aplicações para migração do SharePoint no local para o SharePoint Online. Os passos abaixo mostram como configurar um principal de aplicação com permissões de controlo total do inquilino, mas também pode conceder apenas permissões de leitura através desta abordagem.

Importante

A utilização do Azure ACS (Controle de Acesso Services) para o SharePoint Online foi descontinuada a partir de 27 de novembro de 2023. Veja o anúncio completo de extinção para saber mais. A utilização do ACS do Azure fora do contexto do SharePoint já foi descontinuada a 7 de novembro de 2018 e está agora no fim de vida.

A reforma significa que a funcionalidade não receberá novos investimentos, mas continua a ser suportada. O fim de vida significa que a funcionalidade será descontinuada e deixará de estar disponível para utilização.

Para novos inquilinos, as aplicações que utilizam um token de acesso só de aplicação ACS estão desativadas por predefinição. Recomendamos que utilize o Azure AD modelo apenas de aplicação, que é moderno e mais seguro. No entanto, pode alterar o comportamento ao executar "set-spotenant -DisableCustomAppAuthentication $false" (precisa do PowerShell do administrador do SharePoint mais recente).

Configurar um principal apenas de aplicação com permissões de inquilino

Observação

O administrador da coleção de sites não consegue registar o suplemento no Azure ACS no AppRegNew.aspx por predefinição, a menos que seja explicitamente permitido pelo administrador de inquilinos do SharePoint. Para obter mais informações, veja Set-SPOTenant.

Navegue para um site no seu inquilino (por exemplo, https://contoso.sharepoint.com) e, em seguida, chame a página appregnew.aspx (por exemplo, https://contoso.sharepoint.com/_layouts/15/appregnew.aspx). Nesta página, preencha as restantes informações, como mostrado na captura de ecrã abaixo.

Importante

Depois de premir Create , ser-lhe-á apresentado um ID de cliente e um segredo do cliente, armazene as informações obtidas (id de cliente e segredo do cliente), uma vez que irá precisar disto no próximo passo!

O próximo passo é conceder permissões ao principal recentemente criado. Uma vez que estamos a conceder permissões no âmbito do inquilino, esta concessão só pode ser feita através da página appinv.aspx no site de administração do inquilino. Pode aceder a este site através de https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx. Depois de carregar a página, adicione o ID de cliente e procure o principal criado:

Para conceder permissões, terá de fornecer o XML de permissão que descreve as permissões necessárias. Uma vez que esta aplicação precisa de poder aceder a todos os sites + também utiliza a pesquisa apenas com aplicações, precisa das permissões abaixo:

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

Quando clicar em Criar, ser-lhe-á apresentada uma caixa de diálogo de consentimento de permissão. Prima Confiar para conceder as permissões:

Importante

Proteja a combinação de ID/segredo do cliente criado, tal como seria a sua conta de administrador. Ao utilizar este ID de cliente/segredo, pode ler/atualizar todos os dados no seu ambiente do SharePoint Online!

Com o trabalho de preparação concluído, vamos continuar para o capítulo seguinte a mostrar como pode utilizar o principal de aplicação criado através do ID de cliente e da combinação de segredos.

Utilizar este principal com o PowerShell PnP

Se quiser utilizar o registo só de aplicações gerado com o PowerShell do PnP, pode fazê-lo ao ligar ao seu ambiente do SharePoint No Local ou Online com:

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.

Utilizar este principal na sua aplicação com a biblioteca do PnP Framework

Num primeiro passo, vai adicionar o pacote nuget da biblioteca do PnP Framework: https://www.nuget.org/packages/PnP.Framework. Depois de o fazer, pode utilizar a construção 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);
};

Utilizar este principal na sua aplicação sem utilizar a biblioteca do PnP Framework

Assim que o principal for criado e consentido, pode utilizar o ID e o segredo do principal para pedir acesso. A classe TokenHelper.cs utilizará o ID e o segredo do ficheiro de configuração da aplicação.

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);
            }
        }
    }
}

Uma app.config de exemplo tem o seguinte aspeto:

<?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

Pode inserir facilmente a classe TokenHelper.cs no seu projeto ao adicionar o pacote nuget AppForSharePointOnlineWebToolkit à sua solução.