如何使用 Sharepoint

NOTE: for projects using Adobe’s Sharepoint please continue here.

If you use SharePoint as your content source, AEM uses a registered Microsoft Azure application to access your content. This application has delegated permissions defined that allow the service to access SharePoint on behalf of a user. This user needs to be registered to the project that is using SharePoint.

Alternatively, the services can also authenticate as an application and use application permissions to access the sites. This needs additional setup by a SharePoint site administrator that can grant the permissions for the application.

The preferred setup is to use application permissions, as this narrows down the access the service has to a specific SharePoint site and does not require to share any secrets of a technical user. Also, it reduces the problems around password rotation.

The following describes how to set up application permissions for your project. If you want to set up a technical user, please continue here.

Setting up SharePoint involves the following steps:

  1. Create or identify a Sharepoint site that will serve as site for the document based authoring
  2. Create a folder within SharePoint that will be the website root.
  3. Configure the fstab.yaml with the respective folder
  4. Access the Registration Portal
  5. Register the Application
  6. Apply the sites.selected permission to the SharePoint site

1. Create or identify a Sharepoint site

Talk to your IT department to either identify or create a Sharepoint site that will be used for document based authoring. One site can “host” multiple websites (projects). This site will later receive the respective permissions so that the publishing services can access it.

2. Create the website root folder

Navigate to your desired location in the SharePoint site created or identified above and create a root folder that will be your website root. It is best to not use a SharePoint list root directly, so that you have a shared space for your authors to put collateral documents, for example a drafts folder, or how-to-author documentations.

An example file structure might look like this, using the website folder as the root:

3. Configure the fstab.yaml

The next step is to configure the mountpoint in the fstab.yaml to point to the website root. It usually has the form of

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

But this might vary depending on how you create the SharePoint site and lists. In order to obtain the url, the simplest way is to copy-past the first part from the browser address, eg:

And then add the rest manually (Note, that copying the sharelink via the UI adds unnecessary information and it is better to use a canonical representation of the url). Once you composed the url, you can test it by entering it again in the browser. You should end up in the folder view of your website root.

After that, update the fstab.yaml accordingly.

For example:

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

To finalize the configuration, commit the fstab.yaml back to the main branch.

4. Access the Registration Portal

Overview

In order for the AEM service to access the authored content it needs a couple of information and setup. The AEM service (a cloud function) accesses the MS Graph API on behalf of an application (or configured user). In order to do so, it needs to authenticate first in the context of an Application. This is important because the scopes given to the application define what permission the service has on the MS Graph API. For example, it should be allowed to read and write documents, but not to alter access control.

An application is represented as an “Enterprise Application” in the respective Active Directory of a tenant. The permissions given to that enterprise application ultimately define what the service can access in that tenant’s resources. Certain permissions need to be approved by an Active Directory administrator before a user can use the application. This so-called “admin consent” is a mechanism to verify and control which permissions apps can have. This is to prevent dubious apps from tricking users into trusting an app that is not official. Having the extra admin consent step allows IT security to control which apps the employees can use.

Access the Service Setup UI

To get started, open the Admin Service Setup UI and enter the GitHub URL of your project:

Then you need to “Sign In” with your personal user that has access to the website root. This is to verify that only people with sufficient credentials can manage the user registration.

The first time you login, you probably see the “Permission Requested” screen. This is to inform you about which permissions the “Franklin Registration Service” application will have:

If you are not an AD admin, you probably don’t have the “Consent on behalf of your organization” checkbox. And the login will fail. At this point an AD admin needs to consent to the application.

Note: Giving the service the delegated permissions might be a concern by most IT departments, even when application permissions are used later. Currently this step is required during registration of the application permissions and the admin consent can be removed afterwards.

The application will show up in your Azure Console / Enterprise Applications Blade:

Opening the application details, and selecting the “Permission” Blade will show that there are not admin consented permissions.

Once an AD admin opens the “Grant admin consent …” link, it will be presented with the “Permissions Requested” screen.

After that, the permissions blade will show the consented permissions:

5. Register the Application with Sites.Selected permissions

With the permission properly granted, you should be able to login properly to the Franklin Service Setup UI:

Click on “Connect Application” and you probably see an error message:

Make sure the enterprise application in Azure has the “Sites.Selected” permission granted:

In addition, the SharePoint site that contains the mounted directory needs to have “write” permissions added for the Franklin Service application. In order to do this, follow the instructions https://learn.microsoft.com/en-us/graph/api/site-post-permissions?view=graph-rest-1.0&tabs=http

Example POST:


POST https://graph.microsoft.com/v1.0/sites/03cc3587-0e4d-405e-b06c-ffb0a622b7ac/permissions

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

Note: in order to get the SharePoint siteId, login to your SharePoint site, and append _api/site/id and copy the value of the `<d:id>`xml tag.

For example:

GET https://example.sharepoint.com/sites/my-franklin-project/_api/site/id
<d:Id
  xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
  xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
  xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml"
  m:type="Edm.Guid"
>6957250f-27c6-4996-bfd7-b8592f7d3b31</d:Id>

Once everything is setup correctly, you should see the registration summary:

Troubleshooting

In some cases (depending on azure configuration) the sites.selected permission does not show up in the consent screen. Use the following powershell command to add it:

$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
recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab