The Sharepoint connector for Elimity Insights fetches users, groups, and sites for a Sharepoint tenant so you can keep in control of your environment.

Follow the instructions below to set up the connector for your environment.

How it works

• Elimity Insights periodically fetches users, groups, roles, files and sites for a Sharepoint tenant.
• Write Elimity Insights queries to review and monitor updates to the data, or leverage existing queries.
• Configure these stored queries to take action when the Elimity Insights data changes.

Integration requirements

Setting up a Sharepoint source in Elimity Insights requires:

• an Entra ID admin account to create a dedicated enterprise application, and
• a user in Elimity Insights with the role Connector Admin or higher.

Integration instructions

The following sections will explain the different steps you'll need to take to set up the Sharepoint connector for Elimity Insights. It's important to note that SharePoint does not support granting fine-grained permissions to external integrating applications. More specifically, the Elimity Insights built-in connector for SharePoint requires at least full read access to the sites you want to scan; a more limited permission unfortunately just doesn't exist. Therefore we ask our customers to set up an additional layer of protection for their SharePoint credentials: each deployment of the Elimity Insights built-in connector for SharePoint should communicate with an on-prem instance of the Elimity Insights gateway for SharePoint. Only the on-prem gateway instance has direct access to the coarse-grained SharePoint tokens. Refer to the following diagram for a visual overview:

The remainder of this section will guide you through setting up app registrations in Entra ID, deploying a gateway and configuring the built-in connector.

1. Setting up the main app registration in Entra ID

The Sharepoint connector for Elimity Insights authenticates as an Entra ID enterprise application. Create a new app registration in Entra ID by following these steps:

1. Register a new application ('App registrations' > 'New registration')
   • Name: e.g. 'elimity-insights-sharepoint'
   • Leave other configurations untouched, simply click 'Register'
   • Note down the client and tenant identifiers
2. Assign Graph API permissions to the newly created app registration
   • 'API permissions' > 'Add a permission'
   • 'Microsoft Graph' > 'Application permissions' > 'Sites.Read.All'
3. Grant admin consent for these permission assignments
4. Generate a client secret for the app registration ('Certificates & secrets' > 'Client secrets' > 'New client secret') and securely note down the secret value

2. Setting up the worker app registrations in Entra ID

Detailed scanning of SharePoint sites takes quite a bit of time. Customers must provide at least one 'worker' app registration, but we recommend multiple workers for large SharePoint tenants.

To set up 'worker' app registrations, follow the a procedure similar to the one described in step 1 to create one or more new app registrations, but instead of the Graph permissions assign the following SharePoint permissions:

• If you don't want to import file permissions, then grant 'SharePoint' > 'Application permissions' > 'Sites.Read.All'.
• If you want to import file permissions, then grant 'SharePoint' > 'Application permissions' > 'Sites.FullControl.All' instead of 'Microsoft Graph' > 'Application permissions' > 'Sites.Read.All'

Additionally, instead of generating a client secret, generate and upload a certificate for each app registration:

• Generating a certificate pair is typically customer-specific, the example command below uses OpenSSL:

  openssl req -days 999 -keyout key.pem -newkey rsa -nodes -out cert.pem -subj "/CN=elimity-insights" -x509 

• Securely note down the private key
• Note down the certificate thumbprint that you see in Entra ID

3. Deploying a gateway

Firstly we suggest reading our knowledge base article about installing gateways for some general information. Visit https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/sharepoint-gateway to get a list of available image tags for this specific gateway.

Since this image is a simple HTTP server, our recommendation for deployment is to use your cloud provider’s dedicated container hosting platform (e.g. Google Cloud Run, Azure Container Apps, …). If that's not an option, you can also manually deploy the image on e.g. Windows Server. Again, refer to the dedicated knowledge base article about installing gateways for additional details.

To configure your gateway, mount an HJSON configuration file at `/app/config/config.hjson` with the properties listed below. You can find an example in the attachments at the bottom of this page.

• `clientId`: unique identifier of the main app registration you set up in step 1
• `clientSecret`: client secret value for the main app registration you set up in step 1
• `secretTokenHash`: hex-encoded SHA256 hash of a secret token you generate securely to ensure only your Elimity Insights tenant can use this gateway
  • for example, you can use `openssl rand -base64 32` to generate a 256-bit token
  • securely note down the token itself to configure the built-in connector
  • hash the token, for example by running `echo -n '<my-token>' | sha256sum` on Linux, or `[Text.Encoding]::UTF8.GetBytes('token') | openssl dgst -sha256` in PowerShell.
• `tenantId`: unique identifier of your Entra ID tenant, which you noted down in step 1
• `workers`: object mapping client identifiers for worker app registrations to credential objects with the following properties:
  • `privateKey`: private key for the worker’s app registration you set up in step 2
  • `thumbprint`: thumbprint for the worker’s app registration you set up in step 2

4. Creating a source in Elimity Insights

In Elimity Insights you can now create a new Sharepoint source providing the following configuration:

• Gateway URL: HTTP(S) URL of your Elimity Insights Sharepoint gateway
• Gateway secret token: secret token you generated in step 3
• Target: HJSON array of objects describing which sites you want to import; use an empty array to target all sites in your tenant; each object has the following properties:
  
  • `hostname`: hostname of the SharePoint site you want to import, e.g. `example-tenant.sharepoint.com`
  • `path`: absolute path of the SharePoint site you want to import, e.g. `/sites/ExampleSite`
• Skip files: enable this option if you want to skip scanning regular files and folders for each site
• Skip role assignments: enable this option if you want to skip scanning role assignments for each file
  • If you leave this option disabled, make sure you granted `Sites.FullControl.All` in step 2
  • If you enable this option, granting `Sites.Read.All` in step 2 should suffice
• Skip personal sites: enable this option if you don’t want to scan personal sites
• Include regular files: enable this option if you also want to scan regular files (not only folders)
• List item page size: maximum number of SharePoint list items to retrieve in a single page
• Role assignment chunk size: maximum number of SharePoint role assignments to retrieve in a single batch

Changelog

v3.40.0

• The connector now also uses multiple workers for the initial site scanning step.