Como usar o Sharepoint (aplicativo)

NOTA: para projetos que usam o Sharepoint do Adobe, continue aqui.

Se você usar o SharePoint como fonte de conteúdo, o AEM usará um aplicativo registrado do Microsoft Azure para acessar o conteúdo. Este aplicativo tem permissões delegadas definidos que permitem que o serviço acesse o SharePoint em nome de um usuário. Este usuário precisa ser registrado no projeto que está usando o SharePoint.

Como alternativa, os serviços também podem se autenticar como um aplicativo e usar permissões de aplicativo para acessar os sites. Isso precisa de uma configuração adicional por um administrador de site do SharePoint que possa conceder as permissões para o aplicativo.

A configuração preferida é usar permissões de aplicativo, já que isso restringe o acesso que o serviço tem a um site específico da SharePoint e não requer o compartilhamento de segredos de um usuário técnico. Além disso, reduz os problemas relacionados à rotação de senhas.

A tabela a seguir descreve como configurar permissões de aplicativo para o seu projeto. Se quiser configurar um usuário técnico, continue aqui.

A configuração do SharePoint envolve as seguintes etapas:

1. Criar ou identificar um site do Sharepoint

Fale com o departamento de TI para identificar ou criar um site do Sharepoint que será usado para criação baseada em documentos. Um site pode "hospedar" vários sites (projetos). Este site receberá posteriormente as respectivas permissões para que os serviços de publicação possam acessá-lo.

2. Criar a pasta raiz do site

Navegue até o local desejado no site do SharePoint criado ou identificado acima e crie uma pasta raiz que será a raiz do site. É melhor não usar uma raiz de lista do SharePoint diretamente, para que você tenha um espaço compartilhado para que seus autores coloquem documentos complementares, por exemplo, uma pasta de rascunhos ou documentações de instruções.

Um exemplo de estrutura de arquivo pode ter esta aparência, usando o website como raiz:

3. Configure o fstab.yaml

A próxima etapa é configurar o ponto de montagem no fstab.yaml para apontar para a raiz do site. Geralmente tem a forma de

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

Mas isso pode variar dependendo de como você cria o site e as listas do SharePoint. Para obter o url, a maneira mais simples é copiar a primeira parte do endereço do navegador, por exemplo:

Em seguida, adicione o restante manualmente (Observe que copiar o sharelink pela interface do usuário adiciona informações desnecessárias e é melhor usar uma representação canônica do url). Depois de compor o url, você pode testá-lo inserindo-o novamente no navegador. Você deve chegar à exibição de pasta da raiz do site.

Depois disso, atualize o fstab.yaml em conformidade.

Por exemplo:

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

Para finalizar a configuração, confirme o fstab.yaml de volta à ramificação principal.

4. Acessar o Portal de Registro

Visão geral

Para que o serviço AEM acesse o conteúdo criado, ele precisa de algumas informações e configurações. O serviço AEM (uma função na nuvem) acessa a API MS Graph em nome de um aplicativo (ou usuário configurado). Para fazer isso, é necessário primeiro autenticar no contexto de um Aplicativo. Isso é importante porque os escopos fornecidos ao aplicativo definem qual permissão o serviço tem na API do MS Graph. Por exemplo, deve ser permitido ler e gravar documentos, mas não alterar o controle de acesso.

Um aplicativo é representado como um "Aplicativo corporativo" no respectivo Ative Diretory de um locatário. As permissões concedidas a esse aplicativo corporativo definem o que o serviço pode acessar nos recursos desse locatário. Determinadas permissões precisam ser aprovadas por um administrador do Ative Diretory antes que um usuário possa usar o aplicativo. Esse chamado "consentimento administrativo" é um mecanismo para verificar e controlar quais permissões os aplicativos podem ter. Isso evita que aplicativos duvidosos enganem os usuários para que eles confiem em um aplicativo que não é oficial. Ter a etapa de consentimento administrativo extra permite que a segurança de TI controle quais aplicativos os funcionários podem usar.

1. Fazer logon no Portal de Registro

Colunas (contidas)

<h3>Exibir Aplicativos Empresariais no Portal do Azure</h3>

Supondo que, até o momento, nenhum aplicativo do Franklin Enterprise esteja presente no Azure (Microsoft Entra Id)

<h3>Acessar o Portal de Registro do Franklin</h3>

Ir para https://admin.hlx.page/register, insira o url do github do projeto

<h3>Entrar como usuário não administrador</h3>

Entre como um usuário que não ter permissões de administrador mostrará um erro de que precisa de aprovação, ou seja, o aplicativo precisa de consentimento de administrador.

Problema: o aplicativo corporativo não é registrado se um usuário nunca fizer logon.

<h3>Entrar como usuário administrador</h3>

Uma solução é fazer logon como um usuário que faz ter permissões de administrador:

(observe que neste ponto o Aplicativo corporativo ainda não está registrado no azure)

<h3>Serviço de Registro do Franklin visível na interface do usuário</h3>

Se o administrador fizer logon (sem marcar a caixa de seleção e conceder consentimento a todos), o aplicativo corporativo estará presente.

Criar aplicativo usando MSGraph ou Powershell

Como alternativa, você pode criar o aplicativo empresarial por meio do MSGraph ou do Powershell.

Para torná-lo visível na interface do usuário do Azure, também é necessário adicionar o WindowsAzureActiveDirectoryIntegratedApp tag. Isso pode ser feito diretamente ao criar o aplicativo.

Usando o explorador de gráficos:

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

Usando o PowerShell:

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

Colunas (contidas)

Depois disso, ainda será necessário dar consentimento administrativo se você quiser que um usuário não administrador faça logon.

Consulte também:

• 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 permissões</h3>

Observe que Franklin Registration Service (e34c45c4-0919-43e1-9436-448ad8e81552) o aplicativo só é necessário durante o registro para verificar se o usuário tem acesso de leitura ao sharepoint. Ele tem o seguinte permissões delegadas:

• Openid
  Permite que os usuários façam logon no aplicativo com suas contas corporativas ou escolares e permite que o aplicativo veja informações básicas sobre o perfil do usuário.
• Profile
  Permite que o aplicativo veja o perfil básico dos usuários (por exemplo, nome, imagem, nome de usuário, endereço de email)
• Files.ReadWrite.All
  Permite que o aplicativo leia, crie, atualize e exclua todos os arquivos que o usuário conectado pode acessar.

<h3>Usuário conectado ao Portal de registro</h3>

Após concluir esta etapa inicial, o usuário é conectado no portal de registro

Adicionando o serviço Franklin com permissões de aplicativo

Colunas (contidas)

<h3>Adicionar aplicativo empresarial</h3>

Quando conectado no portal de registro, a fonte de conteúdo usada pelo projeto precisa ser conectada a uma concessão oauth para o Franklin Service aplicação. Isso é necessário para que o sistema possa acessar os documentos no sharepoint e convertê-los em um formato interno (markdown) e armazená-los no armazenamento do Adobe (S3/R2) para entrega rápida.

Usando aplicativo sites.selected permissões é mais seguro, pois limita o escopo a um único site do sharepoint. Para se conectar, clique no link Connect Application botão.

Se você nunca registrou um aplicativo ou um usuário antes, provavelmente verá o seguinte erro:

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

O mesmo que acima, o aplicativo corporativo para o Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856) ainda não está presente no Azure,

Para adicioná-lo, use o gerenciador de gráficos ou o powershell para adicioná-lo:

Usando o explorador de gráficos:

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

Usando o PowerShell:

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

Consulte também:

Adicionar Funções de Aplicativo usando o Powershell ou o Graph Explorer

Como alternativa, a adição das funções de aplicativo pode ser feita com as seguintes etapas:

Usar powershell isso pode ser feito com:

$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

Usar explorador de gráficos envolve mais etapas:

  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á o nosso 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 é o resourceId. (o recurso que define a função do aplicativo)

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

Essa ID é a 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"
}

Colunas (contidas)

<h3>Validar permissões</h3>

Você deve ver a permissão de aplicativo concedida na interface do usuário.

De volta ao portal de registro, o deve ter sido alterado para:

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.

(observe que, no momento em que essa mensagem foi escrita, ela não era muito precisa, deveria conter a seguinte redação:

O recurso especificado em fstab.yaml não existe ou você não tem permissão para acessá-lo. Verifique se a URL está correta. O aplicativo corporativo: "Franklin Service (83ab2922-5f11-4e4d-96f3-d1e0ff152856)" é concedido para acessar o site do SharePoint configurado por meio das permissões "Sites.Seleted".

Adicionar permissões ao Site do Sharepoint

Para adicionar as permissões ao site do SharePoint, precisamos encontrar suas SiteId.

Isso pode ser feito usando novamente o explorador de gráficos:

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

Exemplo:

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

Usar o Id podemos definir as permissões:

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

Colunas (contidas)

Depois disso, o portal de registro deve mostrar canRead: ok