Cómo usar Sharepoint (aplicación)

NOTA: para proyectos que utilizan SharePoint de Adobe, continúe aquí.

Si usa SharePoint AEM como fuente de contenido, utiliza una aplicación registrada de Microsoft Azure para acceder a su contenido, ya que, a su vez, se utiliza una aplicación registrada de esta aplicación. Esta aplicación tiene permisos delegados se definen en que permiten que el servicio acceda 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 utilizar 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 utilizar permisos de aplicación, ya que esto reduce el acceso que el servicio tiene a un sitio 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.

Una estructura de archivos de ejemplo podría tener este aspecto, con la variable website carpeta como raíz:

3. Configurar fstab.yaml

El siguiente paso es configurar el punto de montaje en fstab.yaml para señalar 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 en consecuencia.

Por ejemplo:

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

Para finalizar la configuración, confirme el fstab.yaml de vuelta a la rama principal.

4. Acceder al portal de registro

Información general

AEM Para que el servicio de acceda al contenido creado, necesita un par de información y configuración. AEM El servicio de (una función de nube de ) accede al 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)

<h3>Ver aplicaciones empresariales en Azure Portal</h3>

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

<h3>Acceso al portal de registro de Franklin</h3>

Ir a https://admin.hlx.page/register, introduzca la url de github del proyecto

<h3>Iniciar sesión como usuario no administrador</h3>

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

Problema: la aplicación empresarial no se registra si un usuario nunca inicia sesión.

<h3>Iniciar sesión como usuario administrador</h3>

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

(tenga en cuenta que en este momento la aplicación Enterprise todavía no está registrada en azure)

<h3>Servicio de registro Franklin visible en la interfaz de usuario</h3>

Si el administrador inicia sesión (sin marcar la casilla de verificación y conceder el consentimiento para todos), 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 WindowsAzureActiveDirectoryIntegratedApp etiqueta. 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)

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

<h3>Revisar permisos</h3>

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

• Openid
  Permite a los usuarios iniciar sesión en la aplicación con sus cuentas profesionales o educativas y ver información básica sobre el perfil del usuario.
• 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.

<h3>Usuario conectado Portal de registro</h3>

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)

<h3>Agregar aplicación de empresa</h3>

Cuando se inicia sesión en el portal de registro, el origen de contenido que utiliza el proyecto debe conectarse a una concesión oauth para el 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 almacenamiento de la Adobe (S3/R2) para una entrega rápida.

Uso de la aplicación sites.selected los permisos son más seguros, ya que limitan el ámbito a un único sitio de sharepoint. Para conectarse, haga clic en Connect Application botón.

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:

Uso de PowerShell esto se puede hacer 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

Uso de explorador de gráficos implica 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",
...

Esta será nuestra 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)

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 ID es el 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)

<h3>Validar permisos</h3>

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 acceder a él. Asegúrese de que la dirección URL sea correcta. La aplicación empresarial: "Servicio Franklin (83ab2922-5f11-4e4d-96f3-d1e0ff152856)" se concede para acceder al sitio de SharePoint configurado mediante los permisos "Sitios seleccionados".

Agregar permisos al sitio de Sharepoint

Para agregar los permisos al sitio de SharePoint, debemos 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",
...
}

Uso del 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"
            }
        }
    ]
}

Columnas (contenidas)

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