Step-by-step deployment guide
1. Setting up the main app registration in Entra ID
The Elimity Insights gateway for SharePoint authenticates as an Entra ID enterprise application. Create a new app registration in Entra ID by following these steps:
Register a new application ('App registrations' > 'New registration').
Name: e.g.
elimity-insightsLeave other configurations untouched, simply click 'Register'
Note down the client and tenant identifiers
Assign Graph API permissions to the newly created app registration.
'API permissions' > 'Add a permission'
'Microsoft Graph' > 'Application permissions' > 'Sites.Read.All'
Grant admin consent for these permission assignments.
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:
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.Securely note down the private key.
Upload the certificate to the worker app registration in Entra ID and note down the certificate thumbprint that you see in Entra ID.
3. Generating a secret token
To make sure your gateway only serves requests from authenticated sources, we need to generate a secret token. You could do this for example with OpenSSL:
You should use this token to configure the built-in connector. The gateway itself only has to verify this token, so we just need to provide it with a hash (hex-encoded SHA256). You can again use OpenSSL for this step:
Note down the resulting hash for later use.
4. Configuring the gateway
To configure your gateway, mount an HJSON configuration file at /app/config/config.hjson with the properties listed below. Refer to the following attachment for a starting point:
Edit the following properties in this file to configure the gateway to your needs:
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
secretTokenHash
string
Secret token hash you noted down in step 3
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 gateway
Having configured the gateway we can now deploy it so the built-in connector can start importing. Since we distribute the gateway 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.
Last updated