Cómo usar Sharepoint (aplicación)

NOTA: para proyectos que usen Sharepoint de Adobe, continúe aquí.

Si utiliza SharePoint como fuente de contenido, AEM utiliza una aplicación registrada de Microsoft Azure para acceder al contenido. Esta aplicación tiene permisos delegados definidos que permiten al servicio acceder a SharePoint en nombre de un usuario. Este usuario debe estar registrado en el proyecto que utiliza SharePoint.

Alternativamente, los servicios también pueden autenticarse como una aplicación y usar permisos de aplicación para acceder a los sitios. Esto necesita una configuración adicional por parte de un administrador del sitio de SharePoint que pueda conceder los permisos para la aplicación.

La configuración preferida es usar permisos de aplicación, ya que esto reduce el acceso que el servicio tiene a un sitio de SharePoint específico y no requiere compartir ningún secreto de un usuario técnico. Además, reduce los problemas relacionados con la rotación de contraseñas.

A continuación se describe cómo configurar permisos de aplicación para su proyecto. Si desea configurar un usuario técnico, continúe aquí.

La configuración de SharePoint implica los siguientes pasos:

1. Crear o identificar un sitio de Sharepoint

Hable con su departamento de TI para identificar o crear un sitio de Sharepoint que se utilizará para la creación basada en documentos. Un sitio puede "alojar" varios sitios web (proyectos). Este sitio recibirá más adelante los respectivos permisos para que los servicios de publicación puedan acceder a él.

2. Cree la carpeta raíz del sitio web

Vaya a la ubicación que desee en el sitio de SharePoint creado o identificado arriba y cree una carpeta raíz que sea la raíz del sitio web. Es mejor no utilizar una raíz de lista de SharePoint directamente, de modo que tenga un espacio compartido para que los autores coloquen los documentos de garantía, por ejemplo, una carpeta de borradores o la documentación de procedimientos de creación.

Un ejemplo de estructura de archivos podría tener este aspecto, usando la carpeta website como raíz:

3. Configurar fstab.yaml

El siguiente paso es configurar el punto de montaje en fstab.yaml para que apunte a la raíz del sitio web. Normalmente tiene la forma de

https://<tenant>.SharePoint.com/sites/<sp-site>/Shared%20Documents/website

Sin embargo, esto puede variar según cómo cree el sitio y las listas de SharePoint. Para obtener la dirección URL, la forma más sencilla es copiar y pegar la primera parte de la dirección del explorador, por ejemplo:

Y luego añada el resto manualmente (tenga en cuenta que copiar el vínculo compartido a través de la interfaz de usuario agrega información innecesaria y es mejor utilizar una representación canónica de la dirección URL). Una vez redactada la dirección URL, puede probarla introduciéndola de nuevo en el explorador. Debe terminar en la vista de carpetas de la raíz del sitio web.

Después, actualice el fstab.yaml según corresponda.

Por ejemplo:

mountpoints:
  /: https://adobeenterprisesupportaem.SharePoint.com/sites/hlx-test-project/Shared%20Documents/website

Para finalizar la configuración, confirme fstab.yaml de nuevo en la rama principal.

4. Acceder al portal de registro

Información general

Para que el servicio AEM acceda al contenido creado, necesita un par de información y configuración. El servicio AEM (una función de nube) accede a la API de MS Graph en nombre de una aplicación (o usuario configurado). Para ello, debe autenticarse primero en el contexto de una aplicación. Esto es importante porque los ámbitos asignados a la aplicación definen qué permiso tiene el servicio en la API de MS Graph. Por ejemplo, debería permitirse leer y escribir documentos, pero no alterar el control de acceso.

Una aplicación se representa como una "aplicación empresarial" en el respectivo Active Directory de un inquilino. Los permisos otorgados a esa aplicación empresarial definen finalmente a qué puede acceder el servicio en los recursos de ese inquilino. Es necesario que un administrador de Active Directory apruebe ciertos permisos para que un usuario pueda utilizar la aplicación. Este llamado "consentimiento de administrador" es un mecanismo para verificar y controlar qué permisos pueden tener las aplicaciones. Esto sirve para evitar que aplicaciones dudosas engañen a los usuarios para que confíen en una aplicación que no es oficial. Tener el paso de consentimiento de administrador adicional permite que la seguridad de TI controle qué aplicaciones pueden utilizar los empleados.

1. Iniciar sesión en el portal de registro

Columnas (contenidas, imágenes a pantalla completa)

Ver aplicaciones empresariales en Azure Portal

Suponiendo que hasta el momento no hay aplicaciones Franklin Enterprise presentes en Azure (Microsoft Entra Id)

Acceso al portal de registro de Franklin

Vaya a https://admin.hlx.page/register e introduzca la dirección URL de github del proyecto

Iniciar sesión como usuario no administrador

Iniciar sesión como usuario para saber que no tiene permisos de administrador mostrará un error que requiere aprobación, es decir, la aplicación necesita el consentimiento del administrador.

Problema: la aplicación empresarial no está registrada si un usuario nunca inicia sesión.

Iniciar sesión como usuario administrador

Una solución es iniciar sesión como un usuario que tiene permisos de administrador:

(tenga en cuenta que, en este punto, la aplicación empresarial aún no está registrada en azure)

Servicio de registro Franklin visible en la interfaz de usuario

Si el administrador inicia sesión (sin marcar la casilla de verificación) y conceder consentimiento para Todos los usuarios), la aplicación Enterprise está presente.

Crear una aplicación mediante MSGraph o Powershell

También puede crear la aplicación Enterprise mediante MSGraph o Powershell.

Para que sea visible en la interfaz de usuario de Azure, también debe agregar la etiqueta WindowsAzureActiveDirectoryIntegratedApp. Esto se puede hacer directamente al crear la aplicación.

Uso del explorador de gráficos:

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
{
    "appId": "e34c45c4-0919-43e1-9436-448ad8e81552",
    "tags": [
        "WindowsAzureActiveDirectoryIntegratedApp"
    ]
}

Uso de powershell:

PS> connect-MgGraph -Scopes "Application.ReadWrite.All"
PS> New-MgServicePrincipal -AppId e34c45c4-0919-43e1-9436-448ad8e81552 -Tags WindowsAzureActiveDirectoryIntegratedApp

Columnas (contenidas, imágenes a pantalla completa)

Después de esto, debe dar su consentimiento de administrador si desea que un usuario que no sea administrador inicie sesión.

Consulte también:

• https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/create-service-principal-cross-tenant
• https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-configure?pivots=ms-graph

Revisar permisos

Tenga en cuenta que la aplicación Franklin Registration Service (e34c45c4-0919-43e1-9436-448ad8e81552) solo es necesaria durante el registro para comprobar que el usuario tiene acceso de lectura a sharepoint. Tiene los siguientes permisos delegados:

• Openid
  Permite a los usuarios iniciar sesión en la aplicación con sus cuentas profesionales o educativas y ver el perfil básico del usuario información.
• Profile
  Permite que la aplicación vea el perfil básico de los usuarios (nombre, imagen, nombre de usuario y dirección de correo electrónico)
• Files.ReadWrite.All
  Permite que la aplicación lea, cree, actualice y elimine todos los archivos a los que el usuario que ha iniciado sesión puede acceder.

Usuario conectado Portal de registro

Después de completar este paso inicial, el usuario inicia sesión en el portal de registro

Adición del servicio Franklin con permisos de aplicación

Columnas (contenidas, imágenes a pantalla completa)

Agregar aplicación de empresa

Cuando se inicia sesión en el portal de registro, el origen de contenido que utiliza el el proyecto debe conectarse a una concesión oauth para Franklin Service aplicación. Esto es necesario para que el sistema pueda acceder a los documentos de SharePoint y convertirlos a un formato interno (Markdown) y almacenarlos en el de Adobe. almacenamiento (S3/R2) para una entrega rápida.

El uso de los permisos de la aplicación sites.selected es más seguro, ya que limita el ámbito a un único sitio de sharepoint. Para conectarse, haga clic en el botón Connect Application.

Si nunca antes ha registrado una aplicación o un usuario, probablemente verá el siguiente error:

code language-none
Unable to validate access: Either scp or roles claim need to be present in the token.

Igual que arriba, la aplicación Enterprise para Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856) aún no está presente en Azure,

Para agregarlo, utilice el explorador de gráficos o powershell para agregarlo:

Uso del explorador de gráficos:

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json
{
    "appId": "83ab2922-5f11-4e4d-96f3-d1e0ff152856",
    "tags": [
        "WindowsAzureActiveDirectoryIntegratedApp"
    ]
}

Uso de powershell:

PS> connect-MgGraph -Scopes "Application.ReadWrite.All"
PS> New-MgServicePrincipal -AppId 83ab2922-5f11-4e4d-96f3-d1e0ff152856 -Tags WindowsAzureActiveDirectoryIntegratedApp

Consulte también:

Agregar funciones de aplicación mediante Powershell o el Explorador de gráficos

Como alternativa, para agregar las funciones de la aplicación, siga estos pasos:

Con powershell se puede hacer esto con:

$ObjectId = "abcdef-1234-49b6-b660-cc85b34fe516"    <<------ replace with your enterprise app id
$AAD_SP = Get-AzureADServicePrincipal -SearchString "Microsoft Graph";
$AAD_SP

$MSI = Get-AzureADServicePrincipal -ObjectId $ObjectId
if($MSI.Count -gt 1)
  {
  Write-Output "More than 1 principal found, please find your principal and copy the right object ID. Now use the syntax $MSI = Get-AzureADServicePrincipal -ObjectId <your_object_id>"
  Exit
  }

$AAD_AppRole = $AAD_SP.AppRoles | Where-Object {$_.Value -eq "Sites.Selected"}
New-AzureADServiceAppRoleAssignment -ObjectId $MSI.ObjectId  -PrincipalId $MSI.ObjectId  -ResourceId $AAD_SP.ObjectId[0]  -Id $AAD_AppRole.Id

Si se usa explorador de gráficos, se necesitarán más pasos:

  GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '83ab2922-5f11-4e4d-96f3-d1e0ff152856'
...
  "value": [
        {
            "id": "6761ada0-733b-4a02-98b2-3db970834fe0",
...

Este será nuestro principalId

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'
...
  "value": [
        {
            "id": "5159db96-7193-414e-9730-b1d1e4448443",
...

Este es el resourceId. (el recurso que define la función de la aplicación)

Sustituya resourceId por la entidad de seguridad de servicio de la API de Microsoft Graph como se obtuvo en el paso anterior.

GET https://graph.microsoft.com/v1.0/servicePrincipals/5159db96-7193-414e-9730-b1d1e4448443/appRoles
...
        {
            "allowedMemberTypes": [
                "Application"
            ],
            "description": "Allow the application to access a subset of site collections without a signed in user.  The specific site collections and the permissions granted will be configured in SharePoint Online.",
            "displayName": "Access selected site collections",
            "id": "883ea226-0bf2-4a8f-9f9d-92c9162a727d",
            "isEnabled": true,
            "origin": "Application",
            "value": "Sites.Selected"
        },
...

Este identificador es appRoleId

POST https://graph.microsoft.com/v1.0/servicePrincipals/${principalId}/appRoleAssignedTo
Content-Type: application/json

{
  "principalId": "${principalId}",
  "resourceId": "${resourceId}",
  "appRoleId": "${appRoleId}"
}

https://graph.microsoft.com/v1.0/servicePrincipals/6761ada0-733b-4a02-98b2-3db970834fe0/appRoleAssignedTo
Content-type: application/json
{
    "principalId": "6761ada0-733b-4a02-98b2-3db970834fe0",
    "resourceId": "5159db96-7193-414e-9730-b1d1e4448443",
    "appRoleId": "883ea226-0bf2-4a8f-9f9d-92c9162a727d"
}

Columnas (contenidas, imágenes a pantalla completa)

Validar permisos

Finalmente, debería ver el permiso de aplicación concedido en la interfaz de usuario.

De nuevo en el portal de registro, el debería haber cambiado a:

code language-none
The resource specified in the fstab.yaml does either not exist, or you do not have permission to access it. Please make sure that the url is correct, the enterprise application: "Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856)" is consented for the required scopes, and that the logged in user has permissions to access it.

(tenga en cuenta que, en el momento de escribir este artículo, este mensaje no es muy preciso, debería decir:

El recurso especificado en fstab.yaml no existe o no tiene permiso para obtener acceso a él. Asegúrese de que la dirección URL sea correcta, la aplicación empresarial: "Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856)" se concede para acceder al sitio de sharepoint configurado a través de Permisos "Sites.Selected".

Agregar permisos al sitio de Sharepoint

Para agregar los permisos al sitio de SharePoint, necesitamos encontrar su SiteId.

Esto se puede hacer utilizando de nuevo el explorador de gráficos:

GET https://graph.microsoft.com/v1.0/sites/{host-name}:/{server-relative-path}

Ejemplo:

GET https://graph.microsoft.com/v1.0/sites/adobeenterprisesupportaem.sharepoint.com:/sites/hlx-test-project

{
...
    "id": "adobeenterprisesupportaem.sharepoint.com,03cc3587-0e4d-405e-b06c-ffb0a622b7ac,5fbc1df5-640c-4780-8b59-809e3193c043",
...
}

Con Id podemos establecer los permisos:

POST https://graph.microsoft.com/v1.0/sites/adobeenterprisesupportaem.sharepoint.com,03cc3587-0e4d-405e-b06c-ffb0a622b7ac,5fbc1df5-640c-4780-8b59-809e3193c043/permissions
Content-type: application/json

{
    "roles": [
        "write"
    ],
    "grantedToIdentities": [
        {
            "application": {
                "id": "83ab2922-5f11-4e4d-96f3-d1e0ff152856",
                "displayName": "Franklin Service"
            }
        }
    ]
}

Nota: Si recibe un error de "Acceso denegado" al ejecutar la solicitud anterior , necesita tener permisos de "Administrador del sitio" para ejecutar el paso anterior. Además, es posible que deba dar un "consentimiento" adicional desde el panel "Modificar permisos" del Explorador de gráficos para ámbitos de "Sitios" adicionales.

Columnas (contenidas, imágenes a pantalla completa)

Después, el portal de registro debe mostrar lo siguiente canRead: ok