Utilisation de SharePoint (application)

REMARQUE : pour les projets utilisant Adobe Sharepoint, veuillez continuer ici.

Si vous utilisez SharePoint comme source de contenu, AEM utilise une application Microsoft Azure enregistrée pour accéder à votre contenu. Des autorisations déléguées sont définies pour cette application afin de permettre au service d’accéder à SharePoint au nom d’un utilisateur. Cet utilisateur doit être enregistré dans le projet qui utilise SharePoint.

Les services peuvent également s’authentifier en tant qu’application et utiliser les autorisations d’application pour accéder aux sites. Cela nécessite une configuration supplémentaire par un administrateur de site SharePoint qui peut accorder les autorisations pour l’application.

La configuration recommandée consiste à utiliser les autorisations d’application, car cela permet de réduire l’accès du service à un site SharePoint spécifique et ne nécessite pas de partager les secrets d’un utilisateur technique. Cela réduit également les problèmes liés à la rotation des mots de passe.

La section suivante décrit comment configurer les autorisations d’application pour votre projet. Si vous souhaitez configurer un utilisateur technique, veuillez continuer ici.

La configuration de SharePoint implique les étapes suivantes :

1. Créer ou identifier un site SharePoint

Contactez votre service informatique pour identifier ou créer un site SharePoint qui sera utilisé pour la création basée sur des documents. Un site peut « héberger » plusieurs sites web (projets). Ce site recevra ultérieurement les autorisations correspondantes afin que les services de publication puissent y accéder.

2. Créez le dossier racine du site web

Accédez à l’emplacement souhaité sur le site SharePoint créé ou identifié ci-dessus et créez un dossier racine qui sera la racine de votre site web. Il est préférable de ne pas utiliser directement une racine de liste SharePoint, de sorte que vous disposiez d’un espace partagé pour que vos auteurs puissent placer des documents collatéraux, par exemple un dossier de brouillons, ou des documents de création.

Voici un exemple de structure de fichier, en utilisant le dossier website comme racine :

3. Configuration du fichier fstab.yaml

L’étape suivante consiste à configurer le point de montage dans le fstab.yaml pour qu’il pointe vers la racine du site web. Il se présente généralement sous la forme de

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

Cela peut varier en fonction de la création du site et des listes SharePoint. Pour obtenir l’URL, la méthode la plus simple consiste à copier-coller la première partie à partir de l’adresse du navigateur, par exemple :

Ajoutez ensuite le reste manuellement (notez que la copie du lien partagé via l’interface utilisateur ajoute des informations inutiles et qu’il est préférable d’utiliser une représentation canonique de l’URL). Une fois l’URL composée, vous pouvez la tester en la saisissant à nouveau dans le navigateur. Vous devriez vous retrouver dans l’affichage des dossiers de la racine de votre site web.

Ensuite, mettez à jour le fstab.yaml en conséquence.

Par exemple :

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

Pour finaliser la configuration, validez à nouveau le fstab.yaml dans la branche principale.

4. Accéder au portail d’enregistrement

Vue d’ensemble

Pour que le service AEM puisse accéder au contenu créé, quelques informations et une configuration sont nécessaires. Le service AEM (une fonction cloud) accède à l’API Graph MS au nom d’une application (ou d’un utilisateur configuré). Pour ce faire, il doit d’abord s’authentifier dans le contexte d’une Application. Ce point est important, car les portées fournies à l’application définissent l’autorisation dont dispose le service sur l’API Graph MS. Par exemple, il doit être autorisé à lire et à écrire des documents, mais pas à modifier le contrôle d’accès.

Une application est représentée sous la forme d’une « application d’entreprise » dans l’annuaire Active Directory correspondant d’un client. Les autorisations accordées à cette application d’entreprise définissent finalement ce à quoi le service peut accéder dans les ressources de ce client. Certaines autorisations doivent être approuvées par un administrateur Active Directory avant qu'un utilisateur puisse utiliser l'application. Ce que l’on appelle le « consentement administrateur » est un mécanisme permettant de vérifier et de contrôler les autorisations dont peuvent bénéficier les applications. Cela permet d’empêcher les applications douteuses d’amener les utilisateurs à faire confiance à une application qui n’est pas officielle. Disposer de l’étape de consentement administrateur supplémentaire permet à la sécurité informatique de contrôler les applications que les employés peuvent utiliser.

1. Connectez-vous au portail d’inscription

Colonnes (contenu, images plein écran)

Affichage des applications d’entreprise dans le portail Azure

En supposant que, jusqu’à présent, aucune application d’entreprise Franklin ne soit présente dans Azure (Microsoft Entra Id)

Accéder au portail d’enregistrement Franklin

Accédez à https://admin.hlx.page/register, puis saisissez l’URL github du projet

Se connecter en tant qu'utilisateur non administrateur

Connectez-vous en tant qu’utilisateur ne dispose pas ’autorisations d’administrateur pour afficher un . erreur indiquant qu’elle doit être approuvée, c’est-à-dire que l’application nécessite le consentement administrateur.

Problème : l’application d’entreprise n’est pas enregistrée si un utilisateur ne se connecte jamais.

Se connecter en tant qu'utilisateur administrateur

Une solution consiste à se connecter en tant qu’utilisateur ne dispose des autorisations d’administrateur :

(notez qu’à ce stade, l’application d’entreprise n’est toujours pas enregistrée dans . azure)

Service d’enregistrement Franklin visible dans l’interface utilisateur

Si l’administrateur se connecte (sans cocher la case et accorder le consentement pour tout le monde), l’application Enterprise est présente.

Créer une application à l'aide de MSGraph ou Powershell

Vous pouvez également créer l’application d’entreprise via MSGraph ou Powershell.

Pour le rendre visible dans l’interface utilisateur d’Azure, vous devez également ajouter la balise WindowsAzureActiveDirectoryIntegratedApp . Vous pouvez le faire directement lors de la création de l’application.

Utilisation de l’explorateur de graphiques :

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

Utilisation de PowerShell :

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

Colonnes (contenu, images plein écran)

Ensuite, vous devez toujours donner le consentement administrateur si vous souhaitez qu’un utilisateur non administrateur se connecte.

Voir également :

• 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

Vérifier les autorisations

Notez que l’application Franklin Registration Service (e34c45c4-0919-43e1-9436-448ad8e81552) est uniquement nécessaire lors de l’enregistrement pour vérifier que l’utilisateur dispose d’un accès en lecture à sharepoint. Il dispose des autorisations déléguées suivantes :

• Openid
  Permet aux utilisateurs de se connecter à l’application avec leur compte professionnel ou scolaire et permet à l’application d’afficher le profil utilisateur de base informations.
• Profile
  Permet à l’application d’afficher le profil de base de vos utilisateurs (par exemple, nom, image, nom d’utilisateur, adresse électronique)
• Files.ReadWrite.All
  Permet à l'application de lire, créer, mettre à jour et supprimer tous les fichiers auxquels l'utilisateur connecté peut accéder.

Utilisateur connecté au portail d’enregistrement

Une fois cette étape initiale terminée, l’utilisateur est connecté au portail d’enregistrement

Ajout du service Franklin avec des autorisations d’application

Colonnes (contenu, images plein écran)

Ajouter une application d’entreprise

Une fois connecté au portail d’enregistrement, la source de contenu utilisée par le le projet doit être connecté à une subvention oauth pour le Franklin Service application. Cela est nécessaire pour que le système puisse accéder aux documents dans sharepoint et les convertir dans un format interne (markdown) et les stocker dans Adobe stockage (S3/R2) pour une livraison rapide.

L’utilisation des autorisations de sites.selected d’application est plus sécurisée, car elle limite la portée vers un seul site sharepoint. Pour vous connecter, cliquez sur le bouton Connect Application.

Si vous n’avez jamais enregistré une application ou un utilisateur auparavant, vous voyez probablement le erreur suivante :

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

Comme ci-dessus, l’application d’entreprise pour le Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856) n’est pas encore présente dans Azure,

Pour l’ajouter, utilisez l’explorateur de graphiques ou powershell :

Utilisation de l’explorateur de graphiques :

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

Utilisation de PowerShell :

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

Voir également :

Ajouter des rôles d'application à l'aide de Powershell ou de l'explorateur Graph

Vous pouvez également ajouter des rôles d’application en procédant comme suit :

Avec powershell cela peut être effectué avec :

$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

L’utilisation de l’explorateur graphe implique d’autres étapes :

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

Ce sera notre principalId

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

C'est le resourceId. (ressource qui définit le rôle de l'application)

Remplacez resourceId par le principal de service de l’API Microsoft Graph obtenu à l’étape précédente.

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"
        },
...

Cet ID est le 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"
}

Colonnes (contenu, images plein écran)

Valider les autorisations

L’autorisation de l’application accordée devrait s’afficher dans l’interface utilisateur.

De retour dans le portail d’enregistrement, le aurait dû être remplacé par :

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.

(notez qu'au moment de la rédaction de cet article, ce message n'est pas très précis, il devrait se lire comme suit :

La ressource spécifiée dans le fichier fstab.yaml n’existe pas ou vous n’êtes pas autorisé à y accéder. Assurez-vous que l’URL est correcte, l’application d’entreprise : « Service Franklin (83ab2922-5f11-4e4d-96f3-d1e0ff152856 » est autorisée à accéder au site SharePoint configuré via l’adresse Autorisations « Sites.Selected ».

Ajouter des autorisations au site SharePoint

Pour ajouter les autorisations au site SharePoint, nous devons trouver son SiteId.

Pour ce faire, utilisez à nouveau l’explorateur de graphiques :

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

Exemple :

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",
...
}

À l’aide de l’Id , nous pouvons définir les autorisations :

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

Remarque : si vous obtenez une erreur « Accès refusé » lors de l’exécution du de requête ci-dessus vous devez disposer des autorisations « Administration du site » pour exécuter l’étape ci-dessus. Vous devrez peut-être également donner votre « consentement » supplémentaire à partir du panneau « Modifier les autorisations » de l’Explorateur de graphiques pour d’autres portées de « Sites ».

Colonnes (contenu, images plein écran)

Ensuite, le portail d’enregistrement doit afficher canRead: ok