Step-by-step deployment guide

We highly recommend using our SharePoint built-in connector instead of this import agent.

1. Setting up the main app registration in Entra ID

The Elimity Insights import agent for SharePoint 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

   • 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 a procedure like 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'.

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

1. Generating a certificate pair is typically customer-specific, the following example command uses OpenSSL: openssl req -days 999 -keyout key.pem -newkey rsa -nodes -out cert.pem -subj '/CN=elimity-insights' -x509.

2. Securely note down the private key.

3. Upload the certificate to the worker app registration in Entra ID and note down the certificate thumbprint that you see in Entra ID.

3. Creating a source in Elimity Insights

Firstly create a new SharePoint source in Elimity Insights, but do not enable automatic imports. Instead, generate API credentials for this source and note down the resulting identifier and token.

4. Configuring the agent

To configure your import agent, mount an HJSON configuration file at /app/config/config.hjson with the properties listed below. Refer to the following attachment for a starting point:

config.hjson

732B

Open

Edit the following properties in this file to configure the import agent to your needs:

Property	Type	Description
clientId	string	Unique identifier of the main app registration you set up in step 1
clientSecret	string	Client secret value for the main app registration you set up in step 1
cronPattern	string	Optional CRON pattern describing when the import agent should run (refer to https://crontab.guru for example patterns); omit if you just want to run the agent once
fileExclusionPattern	string	Optional glob pattern to exclude files based on their server-relative URLs; omit if you just want to import all files
includeRegularFiles	boolean	Indicates whether to also scan regular files (not only directories)
insightsSourceId	number	Source identifier you noted down in step 3
insightsSourceToken	string	Source token you noted down in step 3
insightsUrl	string	HTTP(S) API URL of your Elimity Insights instance, e.g. "https://example.elimity.com/api"
listItemPageSize	number	Maximum number of SharePoint list items to retrieve in a single page; we recommend a value of 5000
roleAssignmentChunkSize	number	Maximum number of SharePoint list items to retrieve in a single page; we recommend a value of 100
skipFiles	boolean	Indicates whether to skip scanning regular files and directories for each site
skipPersonalSites	boolean	Indicates whether to skip scanning personal sites
skipRoleAssignments	boolean	Indicates whether you want to skip scanning role assignments for each file; make sure you granted the Sites.FullControl.All permission when enabling this option
targets	list[object]	Describes which SharePoint sites to import; use [] to target all sites in your tenant
targets[].hostname	string	Hostname of the SharePoint site you want to import, e.g. example-tenant.sharepoint.com
targets[].path	string	Absolute path of the SharePoint site you want to import, e.g. /sites/ExampleSite
tenantId	string	Unique identifier of your Entra ID tenant, which you noted down in step 1
workers	record[object]	Record mapping client identifiers for worker app registrations to credential objects
workers[].privateKey	string	Private key for the worker’s app registration you set up in step 2
workers[].thumbprint	string	Thumbprint for the worker’s app registration you set up in step 2

5. Deploying the agent

Having configured the agent and having created a source in Elimity Insights, you can now deploy the agent to regularly import data from your SharePoint tenant and upload it to Elimity Insights. Since we distribute the agent as a Docker image, our recommendation for deployment is to use a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to our documentation about gateways and import agents for additional details.

6. Following up on the import

The import agent outputs logs to indicate its progress, for a manual Windows Server deployment you can check these with docker-compose logs.