M365Con 2027 – conferência online gratuita · 11–22 Jan 2027 · 120 sessions→ m365con.net

Blog · Mirko Peters

Conectar ao SharePoint Online com o PnP PowerShell: opções de entrada

By · · Updated

Conectar ao SharePoint Online com o PnP PowerShell: registre seu próprio app no Entra e escolha entre entrada interativa, por dispositivo, por certificado ou por identidade gerenciada para cada tarefa.

Automatically translated with AI from the original post. Read the English original

Para conectar ao SharePoint Online com o PnP PowerShell hoje, você registra o seu próprio app no Microsoft Entra ID uma única vez. Depois, chama o Connect-PnPOnline com a URL do seu site e o ID do cliente desse app, além de um método de entrada: interativo, login por dispositivo, certificado, identidade gerenciada ou credenciais legadas. Este guia é para administradores do SharePoint que executam scripts manualmente ou agendados. Ele explica o que faz cada opção, quando usá-la e quais erros interrompem a conexão. Também mostra como escolher uma opção por tarefa, para que um script não tenha mais acesso do que a sua função exige.

Pontos-chave

  • Desde 9 de setembro de 2024, o Connect-PnPOnline exige um -ClientId, então cada administrador precisa primeiro registrar um app no Microsoft Entra ID com o qual o módulo possa entrar.
  • A entrada interativa é a escolha certa para uma pessoa diante do teclado, porque oferece suporte à autenticação multifator e não exige um segredo armazenado.
  • Tarefas sem supervisão devem usar entrada por certificado ou identidade gerenciada, e não uma senha digitada nem um segredo de cliente armazenado em um script.
  • O método legado de segredo de cliente funciona apenas com cmdlets do SharePoint, então qualquer comando que chame o Microsoft Graph falhará com ele.
  • Registre o app somente com as permissões delegadas de que você precisa, porque o registro padrão solicita direitos amplos, como AllSites.FullControl.

Primeiros passos: por que cada conexão precisa do seu próprio app

O PnP PowerShell é um módulo mantido pela comunidade. Ele não tem direitos especiais próprios. Cada entrada passa por um registro de app no Microsoft Entra, e esse app define o que o script pode fazer.

A referência do Connect-PnPOnline informa que você deve fornecer o parâmetro -ClientId a partir de 9 de setembro de 2024. Ela também diz que você precisa registrar o seu próprio app antes. Você pode definir a variável de ambiente ENTRAID_APP_ID ou ENTRAID_CLIENT_ID em vez de digitar o ID em cada uso.

Isso mudou scripts antigos. Se um script de 2023 chama Connect-PnPOnline -Url ... -Interactive e nada mais, agora ele falhará ou pedirá um ID de cliente ausente. A correção não está na lógica do script. Você precisa de um app e de um ID.

Há outros dois valores que aparecem em todos os exemplos:

  • -Url é o endereço do site em que você quer trabalhar, como https://contoso.sharepoint.com/sites/finance. É obrigatório para a maioria dos métodos.
  • -Tenant é o nome do locatário, como contoso.onmicrosoft.com. A referência indica que ele é obrigatório para os métodos de certificado e de impressão digital. É opcional para a entrada interativa e o login por dispositivo.

Se um comando precisar do centro de administração do SharePoint, você pode informar -TenantAdminUrl. Quando você omite o parâmetro, os cmdlets assumem o formato https://[nomedolocatario]-admin.sharepoint.com onde isso se aplica.

Etapa 1: conclua o registro do app no Microsoft Entra

Esta etapa inicial pressupõe que o módulo PnP.PowerShell já esteja instalado na sua máquina. O PnP oferece um auxiliar para a primeira configuração. A página de cmdlet de Register-PnPEntraIDAppForInteractiveLogin mostra a forma mais curta:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com

Uma janela do navegador é aberta para você entrar, e o cmdlet cria o aplicativo. Ele também exibe o ID do aplicativo, que você vai usar como -ClientId. Adicione -DeviceLogin se não puder abrir um navegador na máquina. A página informa que isso muda para um fluxo de login por dispositivo, que oferece suporte à autenticação multifator.

Preste atenção às permissões. No exemplo simples, o aplicativo solicita para consentimento estas permissões delegadas: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All e TermStore.ReadWrite.All. O segundo exemplo da mesma página restringe isso com -GraphDelegatePermissions "Group.Read.All" e -SharePointDelegatePermissions "AllSites.FullControl".

Isso importa para o princípio do menor privilégio. Um script de relatório que apenas lê não precisa de permissões de gravação em usuários e grupos. Defina do que os seus scripts precisam e peça apenas isso.

Mantenha um registro de cada registro de aplicativo: nome, ID do cliente, proprietário e as permissões que ele possui. Revise o registro do aplicativo uma vez por ano e exclua-o quando nenhum script o usar mais.

Há dois limites a conhecer. A página de referência não informa qual função do Entra é necessária para registrar um aplicativo, então consulte o seu administrador de identidade antes de começar. E o parâmetro -SignInAudience controla quais tipos de conta o aplicativo aceita, então verifique se ele corresponde ao seu locatário.

Como se conectar ao SharePoint Online com o PnP PowerShell: as cinco opções

Todos os cinco exemplos usam a referência de Connect-PnPOnline como fonte. Substitua os valores entre colchetes angulares.

Entrada interativa

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>

Esta é a escolha padrão para uma pessoa. A referência diz que ela foi projetada para oferecer suporte à autenticação multifator. Adicione -ForceAuthentication para limpar a autenticação armazenada e entrar com outra conta. Use-o quando alternar entre um locatário de teste e um de produção.

Login por dispositivo

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>

Um navegador é aberto e o código é copiado para a área de transferência. Escolha essa opção quando o shell rodar em uma sessão remota em que uma janela interativa não funciona bem.

Entrada com certificado (somente aplicativo)

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>

Nenhuma pessoa faz login. O aplicativo age por conta própria, com as permissões de aplicativo que você lhe concedeu. Você pode passar -CertificatePath com -CertificatePassword, um valor de -CertificateBase64Encoded ou um -Thumbprint. O método com thumbprint exige que o certificado esteja no repositório de certificados do Windows. Esta é a escolha padrão para scripts não supervisionados em um servidor.

Identidade gerenciada

Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity

A referência diz que isso funciona apenas em ambientes que oferecem suporte a identidades gerenciadas, como Azure Functions, runbooks do Automation e Cloud Shell. Você não armazena nenhum segredo. Para uma identidade atribuída pelo usuário, adicione um dos parâmetros -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId ou -UserAssignedManagedIdentityAzureResourceId. O parâmetro -Url é opcional com este método.

Credenciais e segredos de cliente

Dois métodos mais antigos ainda existem, e ambos vêm com ressalvas.

  • -Credentials recebe um PSCredential, por exemplo (Get-Credential), ou o nome de uma credencial genérica no Gerenciador de Credenciais do Windows. A referência lista suporte a multifator para o login interativo e por dispositivo, mas não faz essa afirmação aqui. Trate-o como uma opção para contas sem prompt e teste antes de depender dele.
  • -ClientSecret com -ClientId é o método legado do ACS. A referência diz que, com ele, "apenas cmdlets que se conectam ao SharePoint Online funcionarão." Cmdlets que usam o Microsoft Graph vão falhar.

Evite os dois para qualquer coisa nova. Uma senha em um script é um risco, e um segredo de cliente expira sem aviso.

Exemplo: escolhendo uma opção de entrada para quatro tarefas

Os números e nomes abaixo são fictícios e servem apenas como ilustração.

A equipe de administração de uma empresa fictícia executa quatro tarefas. Eles querem um aplicativo por nível de risco, e não um único aplicativo para tudo.

  1. Verificações ad hoc feitas por um administrador em um notebook. Use -Interactive com um aplicativo que tenha permissões delegadas restritas. O administrador entra com MFA. Nada é armazenado.
  2. Uma limpeza pontual executada em um servidor de salto remoto. Use -DeviceLogin. O administrador conclui a entrada em um celular ou notebook e a execução começa.
  3. Um inventário noturno em um servidor Windows. Use um certificado com -Thumbprint. O aplicativo tem permissões de aplicativo somente leitura. O certificado é válido por 12 meses, e a equipe coloca a data de renovação em uma agenda compartilhada.
  4. Uma tarefa semanal em um runbook do Automation. Use -ManagedIdentity. Não há certificado nem segredo para rotacionar.

O resultado: apenas a tarefa 1 e a tarefa 2 dependem de uma pessoa. As tarefas 3 e 4 são executadas sem ninguém presente, e nenhuma delas armazena uma senha. Se o servidor da tarefa 3 for roubado, a equipe revoga um único certificado. Não precisam redefinir a senha de um administrador.

Qualquer que seja a opção escolhida, mantenha a URL do site em uma variável como $siteUrl, para que um único script do PowerShell possa percorrer cada site em uma lista de sites, obter o que precisa de cada site do SharePoint e enviar um relatório. Teste a execução do script em uma coleção de sites antes de executá-lo em todo o seu locatário do Microsoft 365.

Erros comuns

  • Esquecer o -ClientId. A conexão falha ou pede o valor. Salve o ID na variável de ambiente ENTRAID_APP_ID nas máquinas em que você executa scripts com frequência.
  • Usar um único aplicativo com poderes totais para tudo. O registro padrão solicita AllSites.FullControl e acesso de gravação a usuários e grupos. Registre um segundo aplicativo, somente leitura, para os relatórios.
  • Usar um segredo de cliente com cmdlets baseados no Graph. O método legado só funciona para cmdlets do SharePoint. Se um comando chamar o Graph, ele vai falhar, e a mensagem de erro pode ser confusa.
  • Colocar uma senha ou segredo dentro do arquivo do script. Qualquer pessoa com acesso de leitura ao arquivo tem a credencial. Use um repositório de certificados ou uma identidade gerenciada.
  • Não testar a entrada no ambiente final. Um script que funciona no seu notebook com -Interactive pode falhar em um servidor sem navegador. Teste com o método que a tarefa realmente vai usar.
  • Continuar conectado ao locatário errado. Use -ForceAuthentication ao trocar de conta e exiba os detalhes da conexão no início de cada script.

Como o software pode ajudar

Comece com o que você já tem. O módulo PnP e o SDK do Microsoft Graph PowerShell cobrem a maior parte da automação administrativa com scripts. O Azure Automation executa scripts em uma agenda com uma identidade gerenciada, e o centro de administração do SharePoint mostra sites e configurações sem código. Para segredos, um repositório de certificados ou um cofre de chaves é mais seguro do que um arquivo de script.

Acrescente relatórios. Um script que se conecta corretamente é apenas o primeiro passo. As equipes também precisam de um registro claro do que cada script alterou e de qual identidade de aplicativo ele usou, para que o próximo administrador consiga acompanhar. Mantenha esse registro em um lugar que todos possam ler, como uma lista compartilhada ou um sistema de chamados.

Próximo passo

Registre hoje um aplicativo com o menor conjunto de permissões delegadas de que seus scripts precisam. Depois, teste se você consegue se conectar ao SharePoint Online com o PnP PowerShell usando -Interactive, e anote qual opção de entrada cada uma das suas tarefas agendadas vai usar.

Seguir o podcastSpotify

Entities in this article

PnP PowerShell Microsoft Entra PowerShell SharePoint

Related articles

RSS