O módulo antigo foi descontinuado, as flags de conexão mudaram e agora é obrigatório registrar um App no Entra ID. Neste artigo vou te guiar por tudo isso do zero.
O problema: por que o módulo antigo parou de funcionar?
Se você usava o PnP PowerShell há algum tempo, provavelmente instalou o módulo com o nome SharePointPnPPowerShellOnline — o "módulo antigo". Ele funcionava com flags de autenticação como -PnPManagementShell ou -UseWebLogin, que eram convenientes e não exigiam nenhuma configuração prévia no Azure.
O problema é que tudo isso mudou. A Microsoft encerrou o suporte a essas flags e, a partir de 9 de setembro de 2024, registrar seu próprio aplicativo no Entra ID passou a ser obrigatório para usar o PnP PowerShell. Isso significa que:
-PnPManagementShellnão funciona mais-UseWebLoginfoi removido-Interactivesó funciona com um App Registration próprio no Entra ID
Ter o módulo antigo (SharePointPnPPowerShellOnline) e o novo (PnP.PowerShell) instalados ao mesmo tempo causa conflitos de comandos. É essencial desinstalar o antigo antes de instalar o novo.
1 Pré-requisitos e permissões necessárias
Antes de começar, certifique-se de que você possui:
- Administrador do SharePointna tenant (acesso ao SharePoint Admin Center)
- Permissão para criar App Registrationsno Microsoft Entra ID. O papel deApplication Developeré suficiente para criar o app, mas pode ser necessário oGlobal Administratorpara conceder o consentimento.
- PowerShell 7 ou superiorinstalado — o PnP PowerShell moderno não funciona corretamente no Windows PowerShell 5.1 legado.
A forma mais rápida no Windows é via WinGet: winget install --id Microsoft.PowerShell --source winget. Consulte a documentação oficial da Microsoft para outros métodos.
2 Desinstalar o módulo antigo
Abra o PowerShell como Administrador e verifique se o módulo legado está instalado:
Se o módulo aparecer na lista, prossiga com a desinstalação. Caso o retorno esteja vazio, pule para o Passo 3.
Desinstalar todas as versões
Após a desinstalação, confirme que não sobrou nada:
3 Instalar o novo módulo PnP.PowerShell
Com o módulo antigo removido, instale o novo. O nome correto é PnP.PowerShell (com ponto, não hífen):
Se solicitado a confiar no repositório PSGallery, confirme com S ou Y. Para confirmar que a instalação funcionou:
4 Registrar o App no Microsoft Entra ID
Esta é a etapa mais importante da mudança. Para usar o PnP PowerShell com login interativo, você precisa ter um App Registration próprio no Microsoft Entra ID. Existem duas formas: automaticamente via cmdlet (mais fácil) ou manualmente pelo portal (mais controle).
Opção A — Criação automática via cmdlet (recomendada)
Substitua o valor de -Tenant pelo domínio onmicrosoft.com da sua tenant:
Uma janela de autenticação será aberta. Entre com uma conta com permissão para criar App Registrations. Ao final, o cmdlet exibirá o Client ID do app criado — anote esse valor!
O Client ID exibido ao final é o que você usará em todos os comandos de conexão daqui em diante. Salve-o em um lugar seguro.
Opção B — Criação manual pelo portal do Entra ID
Acesse o portal do Microsoft Entra ID com uma conta com permissão para criar app registrations.
No menu lateral, navegue até Entra ID → App registrations.
Clique em New registration no topo da página.
No campo Name, digite
PnP.PowerShell. Deixe os demais campos com os valores padrão e clique em Register.
Anote o valor de Application (client) ID — você vai precisar dele em todos os comandos de conexão.
Em Manage, clique em Authentication.
Clique em Add a platform.
No painel lateral, selecione Mobile and desktop applications.
Deixe as caixas de seleção desmarcadas. No campo Custom redirect URIs, insira o valor abaixo (atenção: é
http, nãohttps) e clique em Configure:
Deve ser http://localhost com HTTP, não HTTPS. Usar HTTPS aqui causará falha na autenticação.
Em Manage, acesse API permissions.
Remova as permissões padrão do Microsoft Graph: clique nos três pontos ao lado de Microsoft Graph (1) e selecione Remove all permissions. Confirme a remoção.
Clique em Add a permission.
Em Microsoft APIs / Commonly used Microsoft APIs, role até encontrar SharePoint e clique.
Selecione Delegated permissions.
Expanda a seção Sites, marque Sites.FullControl.All e clique em Add permissions.
Permissões delegadas funcionam como intermediário entre as permissões que o usuário já possui no SharePoint e o que o app permite executar. Elas não concedem acesso além do que o usuário já tem.
Clique em Grant admin consent for [nome da organização]. Esta ação requer uma conta com o papel de Global Administrator.
Se o botão Grant admin consent estiver cinza, você não tem as permissões necessárias. Solicite que alguém com o papel de Global Administrator realize essa etapa.
Ao final, a seção de permissões deverá ter uma aparência similar a esta:
5 Conectar ao SharePoint com o novo app
Com o App Registration criado, use o -ClientId do app registrado para se conectar:
Ao executar, o PowerShell abrirá uma janela de login no navegador. Entre com as credenciais do administrador da tenant.
Conectar diretamente a um site específico
6 Criar o App Catalog no site SharePoint
Com a sessão estabelecida, habilite o App Catalog no site de coleção desejado:
Se o comando executar sem retornar nenhuma mensagem, é um bom sinal — o App Catalog foi habilitado com sucesso.
Verificar se o App Catalog foi criado
O site que você configurou deverá aparecer na lista retornada.
Resumo dos comandos — fluxo completo
- Verificar módulo antigo:
Get-Module -Name SharePointPnPPowerShellOnline -ListAvailable - Desinstalar módulo antigo:
Uninstall-Module -Name SharePointPnPPowerShellOnline -AllVersions -Force - Instalar novo módulo:
Install-Module PnP.PowerShell -Scope CurrentUser - Registrar app no Entra ID:
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP.PowerShell" -Tenant "suatenant.onmicrosoft.com" - Conectar ao SharePoint:
Connect-PnPOnline -Url "..." -ClientId "..." -Tenant "..." -Interactive -ForceAuthentication - Criar App Catalog:
Add-PnPSiteCollectionAppCatalog -Site "https://suatenant.sharepoint.com/sites/nomedosite"
Conclusão
A mudança obrigatória de registrar um App no Entra ID pode parecer burocrática na primeira vez, mas traz benefícios reais de segurança: cada automação passa a ter uma identidade rastreável no Azure, com permissões explícitas e auditáveis.
Uma vez com o App Registration configurado, o fluxo diário fica simples — basta usar Connect-PnPOnline com o -ClientId do seu app, e você tem acesso completo ao SharePoint via PnP PowerShell com todas as vantagens do módulo moderno.
Documentação completa: pnp.github.io/powershell/articles/registerapplication.html
Comentários