Atualizar aplicativos do SharePoint do Serviço de Controle de Acesso do Azure para o Azure Active Directory

O modelo de Suplemento do SharePoint permite que você registre aplicativos no ACS (Serviço de Controle de Acesso do Azure) para obter acesso somente por aplicativo aos recursos do SharePoint Online. Dependendo de como você configurar o acesso somente ao aplicativo, você pode conceder diferentes níveis de permissão de somente leitura para controle completo. Nos artigos "Acessando o SharePoint usando um contexto de aplicativo, também conhecido como somente aplicativo" e "Concedendo acesso usando o SharePoint App-Only" você pode encontrar diretrizes passo a passo sobre como configurar esse tipo de aplicativos.

Importante

O Azure Controle de Acesso (ACS), serviço do Azure Active Directory (Azure AD), foi 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 obter mais informações, confira Impacto do Azure Controle de Acesso aposentadoria para suplementos do SharePoint. 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.

Importante

Este artigo refere-se aos chamados componentes PnP, exemplos e/ou ferramentas que são ativos de código aberto apoiados por uma comunidade ativa que fornece suporte para eles. Não há SLA para suporte de ferramentas de código aberto a partir dos canais oficiais de suporte da Microsoft. No entanto, esses componentes ou exemplos estão usando APIs e recursos com suporte da Microsoft que têm suporte da Microsoft.

No entanto, o modelo de suplemento do SharePoint é um modelo antigo e há modelos de desenvolvimento mais novos, mais modernos e versáteis disponíveis, como, por exemplo, o Estrutura do SharePoint. Além disso, do ponto de vista técnico, as permissões concedidas a um aplicativo somente aplicativo registrado com o modelo de Suplemento do SharePoint obtém acesso a todo o locatário e você não pode escolher seletivamente as coleções de sites de destino para as quais deseja conceder permissões.

Como uma alternativa adequada e mais segura, você pode contar com o registro de um aplicativo no Azure Active Directory (Azure AD) eventualmente usando o modelo RSC (Consentimento Específico do Recurso), que é abordado no artigo "Entendendo o consentimento específico do recurso para o Microsoft Graph e o SharePoint Online", a fim de direcionar apenas coleções de sites específicas, em vez de todo o locatário.

Neste artigo, você pode encontrar informações detalhadas sobre como funciona o modelo de registro de aplicativo Azure AD e sobre como atualizar para o modelo Azure AD um aplicativo já existente registrado no ACS com o modelo de Suplemento do SharePoint.

Se preferir, você pode watch o vídeo a seguir, em vez de ler o artigo inteiro, que ainda pode considerar como uma referência muito mais detalhada.

Atualizar do ACS para Azure AD

Nesta seção, fazemos a suposição de que você já tem um aplicativo somente aplicativo registrado no SharePoint Online, usando o modelo de Suplemento do SharePoint e o ACS.

O aplicativo para migrar

Na captura de tela abaixo, você pode ver uma configuração de exemplo para o aplicativo registrado no ACS usando a https://[your-tenant].sharepoint.com/_layouts/15/appregnew.aspx URL do locatário de destino.

O aplicativo recebeu o FullControl diretamente no locatário do SharePoint Online de destino por meio da política a seguir, que foi registrada por meio da https://[your-tenant]-admin.sharepoint.com/_layouts/15/appinv.aspx URL do SharePoint Online Administração Central.

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

Na captura de tela a seguir, você pode ver as configurações da interface do usuário usadas para conceder permissão de Controle Total ao aplicativo.

Também fazemos a suposição de que você está acessando um SharePoint Online Site Collection de destino para ler e gravar os itens de uma biblioteca do SharePoint.

No trecho de código a seguir - obtido de um aplicativo do Console do .NET 6 - você pode ver como obter acesso ao locatário do SharePoint Online de destino usando a Biblioteca PnP Framework, que está disponível como um pacote NuGet código aberto.

// Use the PnP Framework AuthenticationManager class to get access to SharePoint Online
var am = new AuthenticationManager();

using (var context = am.GetACSAppOnlyContext(settings.SiteUrl, settings.ClientId, settings.ClientSecret))
{
    // Read the target library title
    var targetLibrary = context.Web.Lists.GetByTitle(settings.ListTitle);
    context.Load(targetLibrary, l => l.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"The title of the library is: \"{targetLibrary.Title}\"");

    // Add a new document to the target library
    using (var fileContent = new MemoryStream())
    {
        // Create some random text content
        var randomContent = Encoding.UTF8.GetBytes($"Some random content {DateTime.Now}");
        fileContent.Write(randomContent, 0, randomContent.Length);
        fileContent.Position = 0;

        // Upload the content as a random name file
        await targetLibrary.RootFolder.UploadFileAsync($"{Guid.NewGuid().ToString("n")}.txt", fileContent, true);
    }
}

O trecho de código lê o título de uma biblioteca de destino e, em seguida, carrega um novo arquivo de texto na biblioteca de destino, apenas para mostrar uma lógica personalizada hipotética que consome o SharePoint Online somente por aplicativo.

Observação

O exemplo de código depende da Biblioteca PnP Framework para facilitar o acesso ao SharePoint Online. No entanto, você pode eventualmente usar apenas o CSOM (Modelo de Objeto lateral do cliente) do SharePoint Online. A finalidade da Biblioteca de Estruturas PnP é apenas acelerar o processo de desenvolvimento e melhorar a qualidade de vida dos desenvolvedores.

Registrar o novo aplicativo no Azure AD

Como você tem um aplicativo registrado em ACS, vamos ver como transformá-lo em um aplicativo Azure AD moderno.

Em primeiro lugar, você precisa registrar o aplicativo no Azure AD. Em seguida, você precisa configurar a autenticação para o aplicativo. Por fim, você precisa configurar as permissões que deseja conceder ao aplicativo para acessar o SharePoint Online.

Por motivos de segurança, para acessar o SharePoint Online no modo somente aplicativo por meio de um aplicativo registrado Azure AD, você também precisa criar e configurar o certificado X.509 para autenticação do aplicativo.

Nas seções a seguir, você verá como proceder com o registro do aplicativo Azure AD, usando uma abordagem automática ou manual.

Registrar automaticamente um novo aplicativo no Azure AD com o PnP PowerShell

A maneira mais rápida e fácil de registrar um aplicativo Azure AD para acessar o SharePoint Online no modo somente aplicativo é confiar no PowerShell PnP.

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.

Na verdade, há o cmdlet Register-PnPAzureADApp , que permite executar todas as etapas de registro com apenas uma linha de código. No trecho de código a seguir, você pode ver um script do PowerShell para fazer isso.

$app = Register-PnPAzureADApp -ApplicationName "Here the name of your application" -Store CurrentUser -Tenant yourtenant.onmicrosoft.com -Username "your-username" -Password (Read-Host -AsSecureString -Prompt "Enter Password") -CertificatePassword (Read-Host -AsSecureString -Prompt "Enter Certificate Password") -OutPath .\

$app.'AzureAppId/ClientId'
$app.'Certificate Thumbprint'

O cmdlet executa as seguintes etapas:

• registra o aplicativo no Azure AD
• cria um certificado X.509 para autenticação de aplicativo
• importa o certificado, com sua chave privada, no repositório de certificados do Usuário Atual
• exporta o . PFX e . Arquivos CER do certificado na pasta especificada pelo argumento OutPath
• carrega a chave pública do certificado para Azure AD para configurar o certificado para autenticação de aplicativo
• configura um conjunto predefinido de permissões para o aplicativo em Azure AD

O script acima gera a ID do cliente do aplicativo e a impressão digital do certificado autogenerado.

Durante todo o processo, você verá uma caixa de diálogo prompt para conceder ao aplicativo as permissões. No scree-shot a seguir, você pode ver as permissões concedidas automaticamente ao aplicativo pelo cmdlet.

Há muitas opções para configurar o comportamento do cmdlet Register-PnPAzureADApp . Por exemplo, você pode personalizar as permissões para conceder ao aplicativo usando os argumentos GraphApplicationPermissions e SharePointApplicationPermissions .

Se você não estiver interessado no processo manual, poderá ir para a seção "Consumindo o SharePoint Online no modo somente aplicativo por meio de um aplicativo registrado Azure AD" para ver como consumir o SharePoint Online com seu aplicativo de Azure AD recém-registrado.

Registrar manualmente um novo aplicativo no Azure AD

O cmdlet do PowerShell PnP para registrar automaticamente o aplicativo Azure AD é poderoso. No entanto, há cenários em que você deseja mais controle sobre o processo. Nesses cenários, você pode registrar manualmente um novo aplicativo no Azure AD. Para obter o mesmo resultado ilustrado antes, você precisa abrir um navegador para https://aad.portal.azure.com/acessar . Selecione Azure Active Directory na guia à esquerda para ativar a folha Azure AD e escolha Registros de aplicativo na lista de seções disponíveis no menu esquerdo da folha Azure AD. Na captura de tela abaixo, você pode ver a interface do usuário da folha Azure AD nesse cenário.

Selecione no botão Novo registro para iniciar o processo de registro manual do aplicativo. Na captura de tela a seguir, você pode ver o formulário para registrar um novo aplicativo.

Você precisa fornecer um nome para seu novo aplicativo. Em seguida, você precisa escolher as contas que deseja dar suporte. As opções disponíveis são:

• Somente contas neste diretório organizacional: o aplicativo tem como destino um único locatário (ou seja, um único locatário).
• Contas em qualquer diretório organizacional: o aplicativo tem como destino qualquer locatário (ou seja, multilocatário).
• Contas em qualquer diretório organizacional e contas pessoais da Microsoft: o aplicativo é multilocatário e dará suporte a qualquer conta pessoal da Microsoft (como Skype, Xbox etc.).
• Somente contas pessoais da Microsoft: o aplicativo dá suporte a qualquer conta pessoal da Microsoft (como Skype, Xbox etc.).

Para o cenário atual, você pode escolher a opção locatário único ou multilocatário. Vamos para um único locatário.

Selecione o botão Registrar e registre o aplicativo real. Agora você será solicitado com uma página com um conjunto de informações úteis sobre o aplicativo registrado. Você pode ver a página na captura de tela a seguir.

Configurando um Certificado X.509 para o aplicativo

Você pode criar manualmente um certificado X.509 para seu aplicativo, usando qualquer ferramenta de sua escolha. No entanto, a maneira mais fácil e rápida de criar um certificado X.509 para autenticação Azure AD é mais uma vez confiar no PnP PowerShell e especificamente no cmdlet New-PnPAzureCertificate. Segue um exemplo da sintaxe do PowerShell para criar um novo certificado X.509.

$cert = New-PnPAzureCertificate -CommonName "my-certificate-common-name" -OutPfx .\my-certificate.pfx -OutCert .\my-certificate.cer -ValidYears 2 -CertificatePassword (Read-Host -AsSecureString -Prompt "Enter Certificate Password")

$cert.Thumbprint

O script acima cria um novo certificado X.509 e armazena seu . PFX e . Arquivos CER nos caminhos de arquivo especificados. Em seguida, ele gera a impressão digital do certificado gerado.

Observação

Caso deseje usar o certificado gerado do computador de desenvolvimento local, você terá que importar o gerado . Arquivo PFX (que inclui a chave privada) no repositório de certificados local. O procedimento pode variar dependendo do sistema operacional do computador de desenvolvimento. Caso você tenha usado o processo automático, o certificado será importado automaticamente no repositório de certificados do Usuário Atual.

Agora, você está pronto para carregar o certificado em Azure AD. Voltar à página da Web Azure AD mostrando as informações do aplicativo e selecione no menu Certificados & segredos no lado esquerdo da página do aplicativo. Selecione a guia Certificados na página e selecione em Carregar certificado e carregar o . Arquivo CER de lá. Na captura de tela a seguir, você pode ver como é a interface do usuário do portal Azure AD ao carregar um certificado X.509.

Concedendo permissões ao aplicativo

Agora você está pronto para conceder permissões ao aplicativo. Basta selecionar no menu Permissões de API no lado esquerdo da tela e selecionar no comando Adicionar uma permissão . Na captura de tela abaixo, você pode ver como a interface do usuário se parece.

Você será solicitado por um assistente de várias etapas por meio do qual você pode escolher as permissões a serem adicionadas. Para acessar o SharePoint Online, você pode escolher Microsoft Graph ou SharePoint como a API de destino. Como neste artigo estamos falando em configurar um aplicativo para acesso somente aplicativo ao SharePoint, você deve selecionar para adicionar permissões de tipo permissões de aplicativo. Por fim, você precisa selecionar as permissões que deseja adicionar.

No momento desta gravação, as permissões de aplicativo disponíveis para o cenário atual são ilustradas na seguinte lista:

• Microsoft Graph
  • Permissões de aplicativo:
    • Sites.FullControl.All: ter controle total de todas as coleções de sites
    • Sites.Manage.All: Criar, editar e excluir itens e listas em todas as coleções de sites
    • Sites.Read.All: Ler itens em todas as coleções de sites
    • Sites.ReadWrite.All: itens de leitura e gravação em todas as coleções de sites
    • Sites.Select: acessar coleções de sites selecionadas (ela é abordada no artigo "Entender o consentimento específico do recurso para o Microsoft Graph e o SharePoint Online")
• SharePoint
  • Permissões de aplicativo:
    • Sites.FullControl.All: ter controle total de todas as coleções de sites
    • Sites.Manage.All: Ler e gravar itens e listas em todas as coleções de sites
    • Sites.Read.All: Ler itens em todas as coleções de sites
    • Sites.ReadWrite.All: itens de leitura e gravação em todas as coleções de sites
    • Sites.Selecionado: acessar coleções de sites selecionadas (ela é abordada no artigo "Entender o consentimento específico do recurso para o Microsoft Graph e o SharePoint Online")
    • TermStore.Read.All: Ler metadados gerenciados
    • TermStore.ReadWrite.All: Metadados gerenciados de leitura e gravação
    • User.Read.All: Ler perfis de usuário
    • User.ReadWrite.All: Perfis de usuário de leitura e gravação

Como você pode ver, há muitas opções que você pode escolher e, dependendo do seu objetivo, você pode consumir o Microsoft Graph, que deve ser sempre a escolha principal ou as APIs REST do SharePoint Online como alternativa. Você pode até mesmo usar ambos no mesmo aplicativo, dependendo do que você realmente precisa fazer.

Apenas para fazer um exemplo, vamos adicionar as seguintes permissões:

• Microsoft Graph
  • Permissões de aplicativo:
    • Sites.ReadWrite.All
• SharePoint
  • Permissões de aplicativo:
    • Sites.ReadWrite.All

Depois de adicionar permissões a um aplicativo em Azure AD, talvez seja necessário conceder explicitamente essas permissões. Na lista de permissões, você pode ver uma coluna com status de nome e se o valor for "Não concedido para [nome do seu locatário]" com um ponto de exclamação laranja, você precisará selecionar no botão Conceder consentimento de administrador para [nome do locatário] para conceder consentimento para essas permissões, como ilustrado na captura de tela a seguir.

Ao conceder o consentimento, o valor da coluna Status das permissões se torna "Concedido para [nome do seu locatário]" e haverá uma marca de marcar verde.

Consumir o SharePoint Online no modo somente aplicativo por meio de um aplicativo registrado Azure AD

Agora você está pronto para consumir o SharePoint Online por meio do aplicativo Azure AD recém-registrado.

Observação

Se você quiser consumi-lo localmente, do seu computador de desenvolvimento, terá que instalar o certificado gerado em seu repositório de certificados. Se você usou o registro automático por meio do PowerShell PnP, o certificado já será registrado. Se você usou o processo manual, precisará importar manualmente o certificado no repositório de certificados do Usuário Atual.

No trecho de código a seguir – obtido de um aplicativo do Console do .NET 6 – você pode ver como obter acesso ao locatário do SharePoint Online de destino usando a Biblioteca de Estruturas PnP.

// Use the PnP Framework AuthenticationManager class to get access to SharePoint Online
var certificate = X509CertificateUtility.LoadCertificate(StoreName.My, StoreLocation.CurrentUser, settings.CertificateThumbprint);
var am = AuthenticationManager.CreateWithCertificate(settings.ClientId, certificate, settings.TenantId);

using (var context = am.GetContext(settings.SiteUrl))
{
    // Read the target library title
    var targetLibrary = context.Web.Lists.GetByTitle(settings.ListTitle);
    context.Load(targetLibrary, l => l.Title);
    await context.ExecuteQueryAsync();

    Console.WriteLine($"The title of the library is: \"{targetLibrary.Title}\"");

    // Add a new document to the target library
    using (var fileContent = new MemoryStream())
    {
        // Create some random text content
        var randomContent = Encoding.UTF8.GetBytes($"Some random content {DateTime.Now}");
        fileContent.Write(randomContent, 0, randomContent.Length);
        fileContent.Position = 0;

        // Upload the content as a random name file
        await targetLibrary.RootFolder.UploadFileAsync($"{Guid.NewGuid().ToString("n")}.txt", fileContent, true);
    }
}

Assim como foi no exemplo anterior, o trecho de código lê o título de uma biblioteca de destino e, em seguida, carrega um novo arquivo de texto na biblioteca de destino. Como você pode ver, o código se parece quase com o exemplo anterior. No entanto, no último exemplo, você está usando um aplicativo registrado Azure AD e está se referindo a um certificado X.509 para autenticação. Além disso, você ainda está usando a Biblioteca PnP Framework e a sintaxe CSOM para acessar o SharePoint Online. Graças a essa nova abordagem, agora você tem um nível mais alto de personalização para suas permissões de aplicativo e não está mais usando o ACS.

Conteúdo recomendado

Você pode encontrar informações adicionais sobre este tópico lendo os seguintes documentos:

• Impacto da aposentadoria Controle de Acesso do Azure para suplementos do SharePoint
• "Entender o consentimento específico do recurso para o Microsoft Graph e o SharePoint Online"