Actualización de aplicaciones de SharePoint desde Azure Access Control Service a Azure Active Directory

El modelo de complemento de SharePoint permite registrar aplicaciones en Azure Access Control Service (ACS) con el fin de obtener acceso de solo aplicación a los recursos de SharePoint Online. En función de cómo configure el acceso solo a la aplicación, puede conceder distintos niveles de permiso de solo lectura a control total. En los artículos "Acceso a SharePoint mediante un contexto de aplicación, también conocido como solo aplicación" y "Concesión de acceso mediante Solo aplicación de SharePoint" , puede encontrar instrucciones paso a paso sobre cómo configurar este tipo de aplicaciones.

Importante

Azure Access Control (ACS), un servicio de Azure Active Directory (Azure AD), se retiró el 7 de noviembre de 2018. La retirada de este producto no afecta al modelo de complemento de SharePoint, que usa el nombre de host https://accounts.accesscontrol.windows.net (que no est? afectado por esta retirada). Para obtener más información, consulte Impacto de la retirada de Azure Access Control para complementos de SharePoint. En el caso de los nuevos inquilinos, las aplicaciones que usan un token de acceso de solo aplicación de ACS están deshabilitadas de forma predeterminada. Se recomienda usar el modelo de solo aplicación de Azure AD, que es moderno y más seguro.

Importante

En este artículo se hace referencia a los denominados componentes de PnP, ejemplos o herramientas que son recursos de código abierto respaldados por una comunidad activa que proporciona soporte técnico para ellos. Los canales oficiales de soporte técnico de Microsoft no ofrecen ningún contrato de nivel de servicio para herramientas de código abierto. Sin embargo, estos componentes o ejemplos usan las API y características de microsoft compatibles de forma predeterminada y que son compatibles con Microsoft.

Sin embargo, el modelo de complemento de SharePoint es un modelo antiguo y hay modelos de desarrollo más nuevos, más modernos y más versátiles disponibles como, por ejemplo, el SharePoint Framework. Además, desde un punto de vista técnico, los permisos concedidos a una aplicación de solo aplicación registrada con el modelo de complemento de SharePoint obtienen acceso a todo el inquilino y no puede elegir de forma selectiva las colecciones de sitios de destino a las que desea conceder permisos.

Como alternativa adecuada y más segura, puede basarse en el registro de una aplicación en Azure Active Directory (Azure AD) con el modelo de consentimiento específico de recursos (RSC), que se describe en el artículo "Descripción del consentimiento específico de recursos para Microsoft Graph y SharePoint Online", con el fin de dirigirse solo a colecciones de sitios específicas, en lugar de a todo el inquilino.

En este artículo, puede encontrar información detallada sobre cómo funciona el modelo de registro de aplicaciones de Azure AD y sobre cómo actualizar al modelo de Azure AD una aplicación ya existente registrada en ACS con el modelo de complemento de SharePoint.

Si lo prefiere, puede watch el siguiente vídeo, en lugar de leer todo el artículo, que todavía puede considerar como una referencia mucho más detallada.

Actualización de ACS a Azure AD

En esta sección, suponiendo que ya tiene una aplicación solo de aplicación registrada en SharePoint Online, mediante el modelo de complemento de SharePoint y ACS.

La aplicación desde la que se va a migrar

En la captura de pantalla siguiente, puede ver una configuración de ejemplo para la aplicación registrada en ACS mediante la https://[your-tenant].sharepoint.com/_layouts/15/appregnew.aspx dirección URL del inquilino de destino.

A la aplicación se le concedió FullControl derecho en el inquilino de SharePoint Online de destino a través de la siguiente directiva, que se registró a través de la https://[your-tenant]-admin.sharepoint.com/_layouts/15/appinv.aspx dirección URL de SharePoint Online Administración Central.

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

En la captura de pantalla siguiente, puede ver la configuración de la interfaz de usuario que se usa para conceder permiso de control total a la aplicación.

También suponiendo que tiene acceso a una colección de sitios de SharePoint Online de destino para leer y escribir los elementos de una biblioteca de SharePoint.

En el siguiente extracto de código , tomado de una aplicación de consola de .NET 6, puede ver cómo puede obtener acceso al inquilino de SharePoint Online de destino mediante la biblioteca de PnP Framework, que está disponible como un paquete NuGet código abierto.

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

El extracto de código lee el título de una biblioteca de destino y, a continuación, carga un nuevo archivo de texto en la biblioteca de destino, solo para mostrar una lógica personalizada hipotética que consume SharePoint Online solo a través de la aplicación.

Nota:

El ejemplo de código se basa en la biblioteca de PnP Framework para facilitar el acceso a SharePoint Online. Sin embargo, puede usar el modelo de objetos del lado cliente (CSOM) de SharePoint Online. El propósito de la biblioteca de PnP Framework es simplemente acelerar el proceso de desarrollo y mejorar la calidad de vida de los desarrolladores.

Registro de la nueva aplicación en Azure AD

Puesto que tiene una aplicación registrada de ACS, veamos cómo transformarla en una aplicación moderna de Azure AD.

En primer lugar, debe registrar la aplicación en Azure AD. A continuación, debe configurar la autenticación para la aplicación. Por último, debe configurar los permisos que desea conceder a la aplicación para acceder a SharePoint Online.

Por motivos de seguridad, para acceder a SharePoint Online en modo de solo aplicación a través de una aplicación registrada de Azure AD, también debe crear y configurar y el certificado X.509 para la autenticación de aplicaciones.

En las secciones siguientes, verá cómo continuar con el registro de aplicaciones de Azure AD, ya sea mediante un enfoque automático o uno manual.

Registro automático de una nueva aplicación en Azure AD con PowerShell PnP

La forma más rápida y sencilla de registrar una aplicación de Azure AD para acceder a SharePoint Online en modo de solo aplicación es confiar en PowerShell de PnP.

Nota:

PowerShell PnP es una solución de código abierto con una comunidad activa que ofrece su soporte. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

De hecho, está el cmdlet Register-PnPAzureADApp , que permite ejecutar todos los pasos de registro con una sola línea de código. En el fragmento de código siguiente, puede ver un script de PowerShell para hacerlo.

$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'

El cmdlet ejecuta los pasos siguientes:

• registra la aplicación en Azure AD
• crea un certificado X.509 para la autenticación de aplicaciones
• importa el certificado, con su clave privada, en el almacén de certificados de usuario actual.
• exporta . PFX y . Archivos CER del certificado en la carpeta especificada por el argumento OutPath
• carga la clave pública del certificado en Azure AD para configurar el certificado para la autenticación de la aplicación.
• configura un conjunto predefinido de permisos para la aplicación en Azure AD

El script anterior genera el identificador de cliente de la aplicación y la huella digital del certificado generado automáticamente.

Durante todo el proceso verá un cuadro de diálogo de solicitud para conceder a la aplicación los permisos. En el siguiente scree-shot puede ver los permisos concedidos automáticamente a la aplicación por el cmdlet .

Hay muchas opciones para configurar el comportamiento del cmdlet Register-PnPAzureADApp . Por ejemplo, podría personalizar los permisos para conceder a la aplicación mediante los argumentos GraphApplicationPermissions y SharePointApplicationPermissions .

Si no está interesado en el proceso manual, puede ir a la sección "Consumo de SharePoint Online en modo de solo aplicación a través de una aplicación registrada de Azure AD" para ver cómo consumir SharePoint Online con la aplicación de Azure AD recién registrada.

Registro manual de una nueva aplicación en Azure AD

El cmdlet de PowerShell PnP para registrar automáticamente la aplicación de Azure AD es eficaz. Sin embargo, hay escenarios en los que desea tener más control sobre el proceso. En estos escenarios, puede registrar manualmente una nueva aplicación en Azure AD. Para lograr el mismo resultado mostrado anteriormente, debe abrir un explorador para ir a https://aad.portal.azure.com/. Seleccione Azure Active Directory en la pestaña izquierda para activar la hoja de Azure AD y, a continuación, elija Registros de aplicaciones en la lista de secciones disponibles en el menú izquierdo de la hoja de Azure AD. En la captura de pantalla siguiente, puede ver la interfaz de usuario de la hoja de Azure AD en este escenario.

Seleccione el botón Nuevo registro para iniciar el proceso manual de registro de aplicaciones. En la captura de pantalla siguiente, puede ver el formulario para registrar una nueva aplicación.

Debe proporcionar un nombre para la nueva aplicación. A continuación, debe elegir las cuentas que desea admitir. Las opciones disponibles son:

• Solo cuentas en este directorio organizativo: la aplicación tiene como destino un único inquilino (es decir, un solo inquilino).
• Cuentas en cualquier directorio organizativo: la aplicación tiene como destino cualquier inquilino (es decir, multiinquilino).
• Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft: la aplicación es multiinquilino y admitirá cualquier cuenta microsoft personal (como Skype, Xbox, etc.).
• Solo cuentas personales de Microsoft: la aplicación admite cualquier cuenta microsoft personal (como Skype, Xbox, etc.).

Para el escenario actual, puede elegir la opción de inquilino único o multiinquilino. Vamos a por un solo inquilino.

Seleccione el botón Registrar y registre la aplicación real. Ahora se le pedirá una página con un conjunto de información útil sobre la aplicación registrada. Puede ver la página en la siguiente captura de pantalla.

Configuración de un certificado X.509 para la aplicación

Puede crear manualmente un certificado X.509 para la aplicación mediante cualquier herramienta que prefiera. Sin embargo, la manera más fácil y rápida de crear un certificado X.509 para la autenticación de Azure AD es una vez más confiar en PowerShell PnP y específicamente en el cmdlet New-PnPAzureCertificate . A continuación se muestra un ejemplo de la sintaxis de PowerShell para crear un nuevo 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

El script anterior crea un nuevo certificado X.509 y almacena su . PFX y . Archivos CER en las rutas de acceso de archivo especificadas. A continuación, genera la huella digital del certificado generado.

Nota:

En caso de que quiera usar el certificado generado desde la máquina de desarrollo local, tendrá que importar el generado. Archivo PFX (que incluye la clave privada) en el almacén de certificados local. El procedimiento puede variar en función del sistema operativo de la máquina de desarrollo. En caso de que haya usado el proceso automático, el certificado se importará automáticamente en el almacén de certificados de usuario actual.

Ahora, está listo para cargar el certificado en Azure AD. Volver a la página web de Azure AD que muestra la información de la aplicación y seleccione en el menú Certificados & secretos del lado izquierdo de la página de la aplicación. Seleccione la pestaña Certificados en la página, seleccione Cargar certificado y cargue . Archivo CER desde allí. En la captura de pantalla siguiente, puede ver el aspecto de la interfaz de usuario del portal de Azure AD al cargar un certificado X.509.

Concesión de permisos a la aplicación

Ya está listo para conceder permisos a la aplicación. Solo tiene que seleccionar en el menú Permisos de API en el lado izquierdo de la pantalla y seleccionar en el comando Agregar un permiso . En la captura de pantalla siguiente, puede ver el aspecto de la interfaz de usuario.

Se le pedirá un asistente de varios pasos a través del cual puede elegir los permisos que se van a agregar. Para acceder a SharePoint Online, puede elegir Microsoft Graph o SharePoint como API de destino. Puesto que en este artículo estamos hablando de configurar una aplicación para el acceso solo de la aplicación a SharePoint, debe seleccionar agregar permisos de tipo Permisos de aplicación. Por último, debe seleccionar los permisos que desea agregar.

En el momento de escribir este artículo, los permisos de aplicación disponibles para el escenario actual se muestran en la lista siguiente:

• Microsoft Graph
  • Permisos de aplicación:
    • Sites.FullControl.All: tener control total de todas las colecciones de sitios
    • Sites.Manage.All: Crear, editar y eliminar elementos y listas en todas las colecciones de sitios
    • Sites.Read.All: leer elementos de todas las colecciones de sitios
    • Sites.ReadWrite.All: elementos de lectura y escritura en todas las colecciones de sitios
    • Sites.Select: Acceso a colecciones de sitios seleccionadas (se trata en el artículo "Descripción del consentimiento específico de recursos para Microsoft Graph y SharePoint Online")
• SharePoint
  • Permisos de aplicación:
    • Sites.FullControl.All: tener control total de todas las colecciones de sitios
    • Sites.Manage.All: leer y escribir elementos y listas en todas las colecciones de sitios
    • Sites.Read.All: leer elementos de todas las colecciones de sitios
    • Sites.ReadWrite.All: elementos de lectura y escritura en todas las colecciones de sitios
    • Sites.Selected: Acceso a colecciones de sitios seleccionadas (se trata en el artículo "Descripción del consentimiento específico de recursos para Microsoft Graph y SharePoint Online")
    • TermStore.Read.All: Leer metadatos administrados
    • TermStore.ReadWrite.All: lectura y escritura de metadatos administrados
    • User.Read.All: Leer perfiles de usuario
    • User.ReadWrite.All: leer y escribir perfiles de usuario

Como puede ver, hay muchas opciones que puede elegir y, en función de su objetivo, puede usar Microsoft Graph, que siempre debe ser la opción principal, o las API rest de SharePoint Online como alternativa. Incluso puede usar ambos dentro de la misma aplicación, en función de lo que realmente necesite hacer.

Solo para dar un ejemplo, vamos a agregar los siguientes permisos:

• Microsoft Graph
  • Permisos de aplicación:
    • Sites.ReadWrite.All
• SharePoint
  • Permisos de aplicación:
    • Sites.ReadWrite.All

Una vez que haya agregado permisos a una aplicación en Azure AD, es posible que tenga que conceder esos permisos explícitamente. En la lista de permisos, puede ver una columna con el nombre Estado y si el valor es "No concedido para [nombre del inquilino]" con un signo de exclamación naranja, deberá seleccionar en el botón Conceder consentimiento de administrador para [nombre del inquilino] para conceder el consentimiento para esos permisos, como se muestra en la captura de pantalla siguiente.

Al conceder el consentimiento, el valor de la columna Estado de los permisos se convierte en "Concedido para [nombre del inquilino]" y habrá una marca de verificación verde.

Consumo de SharePoint Online en modo de solo aplicación a través de una aplicación registrada en Azure AD

Ya está listo para consumir SharePoint Online a través de la aplicación de Azure AD recién registrada.

Nota:

Si desea consumirlo localmente, desde la máquina de desarrollo, tendrá que instalar el certificado generado en el almacén de certificados. Si usó el registro automático a través de PowerShell PnP, el certificado ya se registrará. Si usó el proceso manual, tendrá que importar manualmente el certificado en el almacén de certificados de usuario actual.

En el siguiente extracto de código, tomado de una aplicación de consola de .NET 6, puede ver cómo puede obtener acceso al inquilino de SharePoint Online de destino mediante la biblioteca de PnP Framework.

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

Como en el ejemplo anterior, el fragmento de código lee el título de una biblioteca de destino y, a continuación, carga un nuevo archivo de texto en la biblioteca de destino. Como puede ver, el código es casi similar al ejemplo anterior. Sin embargo, en el último ejemplo se usa una aplicación registrada de Azure AD y se hace referencia a un certificado X.509 para la autenticación. Aparte de eso, sigue usando la biblioteca de PnP Framework y la sintaxis de CSOM para acceder a SharePoint Online. Gracias a este nuevo enfoque, ahora tiene un mayor nivel de personalización para los permisos de aplicación y ya no usa ACS.

Contenido recomendado

Puede encontrar información adicional sobre este tema leyendo los documentos siguientes:

• Impacto de la retirada de Azure Access Control para complementos de SharePoint
• "Descripción del consentimiento específico de recursos para Microsoft Graph y SharePoint Online"