Conectarse a SharePoint Online con PnP PowerShell: opciones de inicio de sesión
Por Mirko Peters · · Actualizado
Conectarse a SharePoint Online con PnP PowerShell: registra tu propia aplicación de Entra y elige inicio de sesión interactivo, de dispositivo, con certificado o con identidad administrada según cada tarea.
Traducido automáticamente con IA a partir de la publicación original. Lee el original en inglés
Para conectarte hoy a SharePoint Online con PnP PowerShell, registras una aplicación propia en Microsoft Entra ID una sola vez. Después llamas a Connect-PnPOnline con la URL de tu sitio y el ID de cliente de esa aplicación, más un método de inicio de sesión: interactivo, inicio de sesión de dispositivo, certificado, identidad administrada o credenciales heredadas. Esta guía está dirigida a los administradores de SharePoint que ejecutan scripts manualmente o de forma programada. Explica qué hace cada opción, cuándo usarla y qué errores hacen fallar una conexión. También muestra cómo elegir una opción por tarea, para que un script no necesite más acceso del que requiere su trabajo.
Puntos clave
- Desde el 9 de septiembre de 2024, Connect-PnPOnline necesita un -ClientId, así que cada administrador debe registrar primero una aplicación en Microsoft Entra ID con la que el módulo pueda iniciar sesión.
- El inicio de sesión interactivo es la opción correcta para una persona frente al teclado, porque admite la autenticación multifactor y no requiere almacenar ningún secreto.
- Las tareas desatendidas deben usar inicio de sesión con certificado o una identidad administrada, no una contraseña escrita ni un secreto de cliente guardado en un script.
- El método heredado de secreto de cliente solo funciona con los cmdlets de SharePoint, así que cualquier comando que llame a Microsoft Graph fallará con él.
- Registra la aplicación solo con los permisos delegados que necesites, porque el registro predeterminado solicita derechos amplios como AllSites.FullControl.
Primeros pasos: por qué cada conexión necesita tu propia aplicación
PnP PowerShell es un módulo mantenido por la comunidad. No tiene derechos especiales propios. Cada inicio de sesión pasa por un registro de aplicación en Microsoft Entra, y esa aplicación decide lo que puede hacer el script.
La referencia de Connect-PnPOnline indica que, a partir del 9 de septiembre de 2024, debes proporcionar el parámetro -ClientId. También señala que primero debes registrar tu propia aplicación. Puedes definir la variable de entorno ENTRAID_APP_ID o ENTRAID_CLIENT_ID en lugar de escribir el ID en cada ocasión.
Esto afecta a los scripts antiguos. Si un script de 2023 llama a Connect-PnPOnline -Url ... -Interactive y nada más, ahora fallará o pedirá un ID de cliente que falta. La solución no está en la lógica del script. Necesitas una aplicación y un ID.
Hay otros dos valores que aparecen en todos los ejemplos:
-Urles la dirección del sitio con el que quieres trabajar, comohttps://contoso.sharepoint.com/sites/finance. Es obligatorio en la mayoría de los métodos.-Tenantes el nombre del inquilino, comocontoso.onmicrosoft.com. La referencia lo indica como obligatorio para los métodos de certificado y de huella digital. Es opcional para el inicio de sesión interactivo y de dispositivo.
Si un comando necesita el centro de administración de SharePoint, puedes pasar -TenantAdminUrl. Si lo omites, los cmdlets asumen el formato https://[tenantname]-admin.sharepoint.com cuando corresponde.
Paso 1: completa el registro de la aplicación en Microsoft Entra
Este paso de inicio supone que el módulo PnP.PowerShell ya está instalado en tu equipo. PnP incluye un asistente para la configuración inicial. La página de cmdlets de Register-PnPEntraIDAppForInteractiveLogin muestra la forma más corta:
Register-PnPEntraIDAppForInteractiveLogin -ApplicationName TestApp -Tenant yourtenant.onmicrosoft.com
Se abre una ventana del navegador para que inicies sesión, y el cmdlet crea la aplicación. También muestra el identificador de la aplicación, que usarás como -ClientId. Añade -DeviceLogin si no puedes abrir un navegador en el equipo. La página indica que esto cambia a un flujo de inicio de sesión con código de dispositivo, que admite la autenticación multifactor.
Fíjate bien en los permisos. Con el ejemplo básico, la aplicación solicita para su consentimiento estos permisos delegados: AllSites.FullControl, Group.ReadWrite.All, User.ReadWrite.All y TermStore.ReadWrite.All. El segundo ejemplo de la misma página lo restringe con -GraphDelegatePermissions "Group.Read.All" y -SharePointDelegatePermissions "AllSites.FullControl".
Esto es importante para aplicar el principio de mínimo privilegio. Un script de informes que solo lee no necesita permisos de escritura sobre usuarios ni grupos. Decide qué necesita cada script y solicita solo eso.
Lleva un registro de cada registro de aplicación: su nombre, su identificador de cliente, su propietario y los permisos que tiene. Revisa el registro de aplicación una vez al año y elimínalo cuando ningún script lo utilice.
Hay dos limitaciones que conviene conocer. La página de referencia no indica qué rol de Entra necesitas para registrar una aplicación, así que consulta a tu administrador de identidades antes de empezar. Además, el parámetro -SignInAudience controla qué tipos de cuenta admite la aplicación, así que comprueba que coincida con tu inquilino.
Cómo conectarte a SharePoint Online con PnP PowerShell: las cinco opciones
Los cinco ejemplos usan como referencia la documentación de Connect-PnPOnline. Sustituye los valores entre corchetes angulares.
Inicio de sesión interactivo
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -Interactive -ClientId <appId>
Es la opción predeterminada para una persona. La referencia indica que está diseñada para admitir la autenticación multifactor. Añade -ForceAuthentication para borrar la autenticación almacenada e iniciar sesión con otra cuenta. Úsalo cuando cambies entre un inquilino de pruebas y uno de producción.
Inicio de sesión con código de dispositivo
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -DeviceLogin -ClientId <appId>
Se abre un navegador y el código se copia en el portapapeles. Elige esta opción cuando la shell se ejecute en una sesión remota en la que una ventana interactiva no funciona bien.
Inicio de sesión con certificado (solo aplicación)
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ClientId <appId> -Tenant 'contoso.onmicrosoft.com' -Thumbprint <thumbprint>
Ninguna persona inicia sesión. La aplicación actúa por su cuenta, con los permisos de aplicación que le hayas concedido. Puedes pasar -CertificatePath junto con -CertificatePassword, un valor de -CertificateBase64Encoded o un -Thumbprint. El método de huella digital requiere que el certificado esté en el almacén de certificados de Windows. Es la opción estándar para scripts desatendidos en un servidor.
Identidad administrada
Connect-PnPOnline -Url "https://contoso.sharepoint.com" -ManagedIdentity
La referencia indica que esto solo funciona en entornos que admiten identidades administradas, como Azure Functions, los runbooks de Automation y Cloud Shell. No almacenas ningún secreto. Para una identidad asignada por el usuario, añade uno de los parámetros -UserAssignedManagedIdentityClientId, -UserAssignedManagedIdentityObjectId o -UserAssignedManagedIdentityAzureResourceId. Con este método, el parámetro -Url es opcional.
Credenciales y secretos de cliente
Quedan dos métodos más antiguos, y ambos llevan advertencias.
-Credentialsacepta un PSCredential, por ejemplo(Get-Credential), o el nombre de una credencial genérica del Administrador de credenciales de Windows. La referencia enumera la compatibilidad con multifactor para el inicio de sesión interactivo y con código de dispositivo, pero aquí no lo afirma. Considéralo una opción para cuentas sin solicitud de autenticación y pruébalo antes de depender de él.-ClientSecretcon-ClientIdes el método heredado de ACS. La referencia indica que, con él, "solo funcionan los cmdlets que se conectan a SharePoint Online." Los cmdlets que usan Microsoft Graph fallarán.
Evita ambos para cualquier cosa nueva. Una contraseña en un script es un riesgo, y un secreto de cliente caduca sin previo aviso.
Ejemplo: elegir una opción de inicio de sesión para cuatro tareas
Los números y los nombres que aparecen a continuación son ficticios y se usan solo como ilustración.
El equipo de administración de una empresa ficticia ejecuta cuatro tareas. Quieren una aplicación por nivel de riesgo, no una aplicación para todo.
- Comprobaciones puntuales por parte de un administrador en su portátil. Usa
-Interactivecon una aplicación que tenga permisos delegados muy acotados. El administrador inicia sesión con MFA. No se almacena nada. - Una limpieza única en un servidor de salto remoto. Usa
-DeviceLogin. El administrador completa el inicio de sesión en un teléfono o portátil y la ejecución comienza. - Un inventario nocturno en un servidor Windows. Usa un certificado con
-Thumbprint. La aplicación tiene permisos de aplicación de solo lectura. El certificado es válido durante 12 meses, y el equipo anota la fecha de renovación en un calendario compartido. - Una tarea semanal en un runbook de Automation. Usa
-ManagedIdentity. No hay ningún certificado ni secreto que rotar.
El resultado: solo las tareas 1 y 2 dependen de una persona. Las tareas 3 y 4 se ejecutan sin que nadie esté presente, y ninguna almacena una contraseña. Si el servidor de la tarea 3 es robado, el equipo revoca un solo certificado. No tienen que restablecer la contraseña de un administrador.
Independientemente de la opción que elijas, guarda la URL del sitio en una variable como $siteUrl, de modo que un mismo script de PowerShell pueda recorrer cada sitio de una lista de sitios, obtener lo que necesita de cada sitio de SharePoint y subir un informe. Prueba el script con una sola colección de sitios antes de ejecutarlo en todo tu inquilino de Microsoft 365.
Errores comunes
- Olvidar
-ClientId. La conexión falla o pide el valor. Guarda el ID en la variable de entornoENTRAID_APP_IDen los equipos donde ejecutes scripts con frecuencia. - Usar una única aplicación con todos los poderes para todo. El registro predeterminado solicita AllSites.FullControl y acceso de escritura a usuarios y grupos. Registra una segunda aplicación, de solo lectura, para los informes.
- Usar un secreto de cliente con cmdlets basados en Graph. El método heredado solo funciona con los cmdlets de SharePoint. Si un comando llama a Graph, fallará, y el mensaje de error puede resultar confuso.
- Poner una contraseña o un secreto en el archivo del script. Cualquiera con acceso de lectura al archivo tiene la credencial. Usa un almacén de certificados o una identidad administrada.
- No probar el inicio de sesión en el entorno final. Un script que funciona en tu portátil con
-Interactivepuede fallar en un servidor sin navegador. Prueba con el método que usará realmente la tarea. - Seguir conectado al inquilino equivocado. Usa
-ForceAuthenticationcuando cambies de cuenta e imprime los datos de la conexión al inicio de cada script.
Cómo puede ayudar el software
Empieza con lo que ya tienes. El módulo PnP y el SDK de PowerShell de Microsoft Graph cubren la mayoría de los scripts de administración. Azure Automation ejecuta scripts programados con una identidad administrada, y el centro de administración de SharePoint muestra sitios y configuraciones sin necesidad de código. Para los secretos, un almacén de certificados o un Key Vault es más seguro que un archivo de script.
Añade informes encima. Un script que se conecta correctamente es solo el primer paso. Los equipos también necesitan un registro claro de lo que cambió cada script y de qué identidad de aplicación se sirvió, para que el siguiente administrador pueda seguirlo. Guarda ese registro en un lugar al que todos puedan acceder, como una lista compartida o un sistema de tickets.
Siguiente paso
Registra hoy una aplicación con el conjunto más pequeño de permisos delegados que necesiten tus scripts. Después, comprueba que puedes conectarte a SharePoint Online con PnP PowerShell usando -Interactive, y anota qué opción de inicio de sesión usará cada una de tus tareas programadas.