Step-by-step deployment guide

This version of the gateway is currently compatible with Elimity Insights server versions matching 3.43.x.

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:

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. 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 snippet for a starting point:

{
  "clientId": "my-client-id",
  "clientSecret": "my-client-secret",
  "jwtValidationBaseUrl": "https://example.elimity.com",
  "jwtValidationGatewayUrl": "https://gateway.example.com",
  "jwtValidationSourceId": "42",
  "tenantId": "my-tenant-id",
  "workers": {
    "my-client-id": {
      "privateKey": '''
        -----BEGIN PRIVATE KEY-----
        my-private-key
        -----END PRIVATE KEY-----
      ''',
      "thumbprint": "my-thumbprint"
    }
  }
}

Edit the following properties in this file to configure the gateway 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
jwtValidationAudiences	option[list[string]]	Audiences for JWT validation, defaults to ["gateway"]
jwtValidationBaseUrl	string	Expected Elimity Insights base URL for JWT validation, e.g. "https://example.elimity.com"
jwtValidationGatewayUrl	string	Expected gateway URL for JWT validation, e.g. "https://gateway.example.com"
jwtValidationIssuer	option[string]	Issuer for JWT validation, defaults to "https://auth.elimity.com/"
jwtValidationRequired	option[boolean]	Flag indicating whether JWT validation is required, defaults to true
jwtValidationSourceId	string	Expected source id for JWT validation, e.g. "42"
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

JWT validation

We highly recommend requiring JWT validation to secure your gateway. Please read our official documentation about the following topics to understand how Elimity Insights authenticates to gateways via OAuth2:

• Gateway-based imports

• OAuth2 endpoint parameters for gateway authentication

Our SaaS customers can simply set the jwtValidationBaseUrl, jwtValidationGatewayUrl and jwtValidationSourceId configuration options, which provides the following security guarantees:

• Only requests coming from the configured Elimity Insights tenant are allowed

• Only requests targeting the configured gateway URL are allowed

• Only requests for importing the configured source are allowed

On-premise customers should additionally set the jwtValidationAudiences, jwtValidationIssuer and jwtValidationExpr configuration options. Alternatively you can also set jwtValidationRequired to false and perform authentication in a proxy instead.

Environment variables

In most cases the aforementioned configuration file should offer all the customization options you need; the following environment variables may be useful in more advanced deployment scenarios:

Environment variable	Description
NODE_USE_ENV_PROXY	Set to 1 if the gateway should look at environment variables for determining HTTP proxies
HTTP_PROXY, HTTPS_PROXY, NO_PROXY	Determine which proxy the gateway should use for outgoing HTTP(S) requests
NODE_EXTRA_CA_CERTS	Adds extra CA certificates to the gateway's trust store; refer to the official documentation for additional information

4. 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.