Come utilizzare Sharepoint (applicazione)

NOTA: per i progetti che utilizzano Adobe’s Sharepoint, continua qui.

Se si utilizza SharePoint come origine di contenuto, l'AEM utilizza un'applicazione Microsoft Azure registrata per accedere al contenuto. Questa applicazione ha autorizzazioni delegate definite che consentono al servizio di accedere a SharePoint per conto di un utente. Questo utente deve essere registrato nel progetto che utilizza SharePoint.

In alternativa, i servizi possono anche eseguire l’autenticazione come applicazione e utilizzare autorizzazioni dell’applicazione per accedere ai siti. È necessaria una configurazione aggiuntiva da parte di un amministratore del sito SharePoint che può concedere le autorizzazioni per l'applicazione.

La configurazione preferita è quella di utilizzare autorizzazioni dell’applicazione, poiché questo limita l’accesso del servizio a un sito SharePoint specifico e non richiede la condivisione di segreti di un utente tecnico. Inoltre, riduce i problemi relativi alla rotazione delle password.

Di seguito viene descritto come impostare autorizzazioni dell’applicazione per il tuo progetto. Se desideri configurare un utente tecnico, continua qui.

La configurazione di SharePoint prevede i seguenti passaggi:

1. Creare o identificare un sito di Sharepoint

Rivolgersi al reparto IT per identificare o creare un sito di Sharepoint che verrà utilizzato per l'authoring basato su documenti. Un sito può ospitare più siti web (progetti). Questo sito riceverà in seguito le rispettive autorizzazioni in modo che i servizi di pubblicazione possano accedervi.

2. Creare la cartella principale del sito web

Passa alla posizione desiderata nel sito SharePoint creato o identificato in precedenza e crea una cartella principale che fungerà da directory principale del sito. È consigliabile non utilizzare direttamente una directory principale dell’elenco di SharePoint, in modo da disporre di uno spazio condiviso per consentire agli autori di inserire documenti collaterali, ad esempio una cartella delle bozze o documenti descrittivi.

Un esempio di struttura del file potrebbe essere simile al seguente, utilizzando website cartella principale:

3. Configurare fstab.yaml

Il passaggio successivo consiste nel configurare il punto di montaggio nel fstab.yaml per puntare alla directory principale del sito web. Di solito ha la forma di

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

Tuttavia, la procedura potrebbe variare a seconda della modalità di creazione del sito SharePoint e degli elenchi. Per ottenere l’URL, il modo più semplice è copiare la prima parte dall’indirizzo del browser, ad esempio:

Quindi aggiungi il resto manualmente (tieni presente che copiare il collegamento condiviso tramite l’interfaccia utente aggiunge informazioni non necessarie ed è meglio utilizzare una rappresentazione canonica dell’URL). Una volta composto l’URL, puoi testarlo immettendolo nuovamente nel browser. Dovresti trovarti nella vista a cartelle della directory principale del tuo sito web.

In seguito, aggiorna il fstab.yaml di conseguenza.

Ad esempio:

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

Per finalizzare la configurazione, esegui il commit della fstab.yaml torna al ramo principale.

4. Accedere al portale di registrazione

Panoramica

Per consentire al servizio AEM di accedere ai contenuti creati, è necessario disporre di alcune informazioni e procedere alla configurazione. Il servizio AEM (una funzione cloud) accede al API di MS Graph per conto di un'applicazione (o di un utente configurato). Per farlo, deve innanzitutto autenticarsi nel contesto di un Applicazione. Questo è importante perché gli ambiti assegnati all’applicazione definiscono l’autorizzazione di cui dispone il servizio sull’API di MS Graph. Ad esempio, dovrebbe essere consentito leggere e scrivere documenti, ma non modificare il controllo degli accessi.

Un'applicazione è rappresentata come "applicazione enterprise" nel rispettivo Active Directory di un tenant. Le autorizzazioni concesse a tale applicazione enterprise definiscono in ultima analisi ciò a cui il servizio può accedere nelle risorse di tale tenant. Per poter utilizzare l'applicazione, è necessario che un amministratore di Active Directory approvi alcune autorizzazioni. Questo cosiddetto "consenso dell’amministratore" è un meccanismo per verificare e controllare quali autorizzazioni possono avere le app. In questo modo si evita che app di dubbia affidabilità inducano gli utenti a fidarsi di un'app che non è ufficiale. Il passaggio di consenso aggiuntivo dell’amministratore consente alla sicurezza IT di controllare quali app possono essere utilizzate dai dipendenti.

1. Accesso al portale di registrazione

Colonne (contenute)

<h3>Visualizzare le applicazioni Enterprise nel portale di Azure</h3>

Supponendo che non siano presenti applicazioni aziendali Franklin in Azure (ID Entra Microsoft)

<h3>Accesso al portale di registrazione Franklin</h3>

Vai a https://admin.hlx.page/register, immetti l’url github del progetto

<h3>Accedi come utente non amministratore</h3>

Accedi come utente che non Se si dispone delle autorizzazioni di amministratore, viene visualizzato un messaggio di errore per segnalare che è necessaria l’approvazione, ovvero se l’applicazione richiede il consenso dell’amministratore.

Problema: l’applicazione Enterprise non viene registrata se un utente non effettua mai l’accesso.

<h3>Accedi come utente amministratore</h3>

Una soluzione consiste nell'accedere come utente che fa disponi delle autorizzazioni di amministratore:

(a questo punto, l'applicazione Enterprise non è ancora registrata in Azure)

<h3>Servizio registrazione Franklin visibile nell’interfaccia utente</h3>

Se l’amministratore effettua l’accesso (senza selezionare la casella di controllo e concedere il consenso per tutti), l’applicazione Enterprise è presente.

Creare un'applicazione tramite MSGraph o Powershell

In alternativa, è possibile creare l'applicazione Enterprise tramite MSGraph o Powershell.

Per renderlo visibile nell’interfaccia utente di Azure, devi aggiungere anche WindowsAzureActiveDirectoryIntegratedApp tag. Questa operazione può essere eseguita direttamente durante la creazione dell’applicazione.

Utilizzo di Esplora grafico:

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

Utilizzo di PowerShell:

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

Colonne (contenute)

Dopodiché, se desideri l’accesso di un utente non amministratore, devi ancora fornire il consenso dell’amministratore.

Vedi anche:

• 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>Autorizzazioni di revisione</h3>

Tieni presente che Franklin Registration Service (e34c45c4-0919-43e1-9436-448ad8e81552) l'applicazione è necessaria solo durante la registrazione per verificare che l'utente abbia accesso in lettura a sharepoint. Presenta le seguenti caratteristiche autorizzazioni delegate:

• Openid
  Consente agli utenti di accedere all’app con il proprio account aziendale o dell’istituto di istruzione e consente all’app di visualizzare le informazioni di base del profilo utente.
• Profile
  Consente all’app di visualizzare il profilo di base degli utenti (ad esempio nome, immagine, nome utente, indirizzo e-mail)
• Files.ReadWrite.All
  Consente all'app di leggere, creare, aggiornare ed eliminare tutti i file a cui l'utente connesso può accedere.

<h3>Utente connesso al portale di registrazione</h3>

Dopo aver completato questo passaggio iniziale, l’utente ha effettuato l’accesso al portale di registrazione

Aggiunta del servizio Franklin con autorizzazioni dell’applicazione

Colonne (contenute)

<h3>Aggiungi applicazione enterprise</h3>

Una volta effettuato l’accesso al portale di registrazione, l’origine di contenuto utilizzata dal progetto deve essere connessa a una sovvenzione oauth per Franklin Service applicazione. Ciò è necessario, in modo che il sistema possa accedere ai documenti in sharepoint e convertirli in un formato interno (markdown) e archiviarli nell'archivio di Adobe (S3/R2) per una consegna rapida.

Utilizzo dell'applicazione sites.selected le autorizzazioni sono più sicure in quanto limitano l'ambito a un singolo sito sharepoint. Per connettersi, fare clic sul pulsante Connect Application pulsante.

Se non hai mai registrato un'applicazione o un utente prima, probabilmente viene visualizzato il seguente errore:

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

Come sopra, l'applicazione Enterprise per Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856) non è ancora presente in Azure,

Per aggiungerlo, utilizzare l'Explorer grafico o PowerShell:

Utilizzo di Esplora grafico:

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

Utilizzo di PowerShell:

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

Vedi anche:

Aggiunta di ruoli dell'applicazione mediante Powershell o Graph Explorer

In alternativa, puoi aggiungere i ruoli dell’app seguendo questi passaggi:

Utilizzo di powershell questa operazione può essere eseguita 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

Utilizzo di esplora grafico comporta più passaggi:

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

Questo sarà il nostro principalId

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

Questo è il resourceId. (risorsa che definisce il ruolo dell’applicazione)

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

Questo ID è il 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"
}

Colonne (contenute)

<h3>Convalida autorizzazioni</h3>

Successivamente, dovresti visualizzare l’autorizzazione all’applicazione concessa nell’interfaccia utente.

Sempre nel portale di registrazione, il dovrebbe essere cambiato in:

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.

(Nota: al momento della stesura del presente messaggio non è molto accurato, dovrebbe riportare:

La risorsa specificata nel file fstab.yaml non esiste o non si dispone delle autorizzazioni necessarie per accedervi. Assicurarsi che l'URL sia corretto, l'applicazione enterprise: "Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856)" viene concesso per accedere al sito sharepoint configurato tramite le autorizzazioni "Sites.Selected".

Aggiungere autorizzazioni al sito di SharePoint

Per aggiungere le autorizzazioni al sito di SharePoint, è necessario trovare le relative SiteId.

Questa operazione può essere eseguita utilizzando nuovamente Esplora grafico:

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

Esempio:

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

Utilizzo di Id possiamo impostare le autorizzazioni:

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

Colonne (contenute)

Successivamente, il portale di registrazione dovrebbe mostrare canRead: ok