Configure API authentication keys in a scaled environment

Version: 10.4

Applies to	xDB Processing and Content Management.
Sitecore Installation Framework (SIF)	SIF does not configure security keys by default. During installation, however, the Reporting Service API key is automatically generated and applied.
Azure Toolkit	Security keys are configured by default when they are entered into the ARM template.

To ensure secure communication between servers in a scaled Sitecore environment, each request from a client must be authenticated on the xDB Processing server. For example, on a Content Management server that needs to communicate with a remote Processing server. In scaled environments, only authenticated parties can gain access to data on remote servers.

For each server request, the Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory class adds a custom HTTP header to the page requested. The header includes an API authentication key, which is stored in the ConnectionStrings.config file.

On each server you must enter an API authentication key that can be used during the authentication process. Keys must be identical to successfully authenticate requests. For example, the key on a Processing server must match the key stored on a Content Management server to successfully retrieve data.

API authentication between the Content Management Server and the xDB Processing Server.

The server authentication process is as follows:

A Content Management client requests data from the Processing server using the Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory class.
When the Processing server receives the request, the ApiKeyReportDataProvider class checks that the API authentication key from the HTTP header matches (case-sensitive) the one stored on the Processing server..
If the two keys match, the processing of the request can continue, data is retrieved and can be sent back to the Content Management client.
If the authentication keys do not match, the server responds with a 403 (Forbidden) status code.

Important

Use HTTPS across your entire website. In the Sitecore.Xdb.Remote.Client.config file, RequireHttps is enabled by default and should remain enabled in all production environments. HTTP is not secure enough for production servers and should only be used on local testing or development instances.

Reporting Service API key

The Reporting Service API key is automatically generated and applied by the Sitecore installation framework (SIF) during installation. When installing an XP topology, SIF uses the standard parameter/variable pattern to set ReportingService.ApiKey. If the installer provides a value via the ReportingServiceApiKey parameter, SIF applies it. If not, SIF generates a secure random 32‑character key and applies it to all relevant roles (CM, Processing, and so on). This behavior ensures that the Reporting Service API key is always populated, either from a user‑supplied configuration or via SIF‑generated defaults.

Option #1: Configure a shared API authentication key

The following section describes how to configure an API authentication key between the Content Management and the Processing servers. In this scenario, Processing and Content Management use the same authentication key.

On the Content Management server

To configure an API authentication key on the Content Management server:

On the Content Management server, navigate to the Website\App_Config folder and open the ConnectionString.config file.
In the ConnectionStrings.config file, find the reporting.apikey connection string and enter an ASCII string to use as a key (default minimum length 32 characters). The key can be any combination of numerals or text.

For example:
RequestResponse
```
<add name="reporting.apikey" connectionString="67588d50667e47e0a02cb919185f7c30"/>
```
Important

The string you choose must conform to the minimum API key length as specified in the Sitecore.Xdb.Remote.Client.config file, MinimalApiKeyLength attribute.

On the Processing server

To configure an API authentication key on the Processing server:

On the Processing server, navigate to the Website\App_Config folder and open the ConnectionStrings.config file.
Add the reporting.apikey connection string to the ConnectionStrings.config file. The key must match the Content Management server.

Option #2: Configure a separate API authentication key for Processing

The following section describes how to configure different API authentication keys between Content Management and Processing.

On the Content Management server

On the Content Management server, or any other server that is making the request for data from the Processing server:

In the Sitecore.Xdb.Remote.Client.config file, locate the following section and set the connectionStringName parameter to a new value - for example, processing.apikey:

RequestResponse

<processing>
    <remote enabled="true">
        <reportingStorageManagerProxy type="Sitecore.Analytics.Aggregation.History.Remoting.ReportingStorageManagerProxy, Sitecore.Analytics.Aggregation">
            <param desc="serviceLocation">/~/v81/processing/reportingstoragemanager/</param>
            <param desc="webTransportFactory" ref="processing/remote/httpTransportFactory" />
        </reportingStorageManagerProxy>
        <httpTransportFactory type="Sitecore.Analytics.Core.ApiKeyHttpTransportFactory, Sitecore.Analytics.Core" singleInstance="true">
            <param desc="serviceUrl"></param>
            <param desc="requireHttps" type="System.Boolean" factoryMethod="Parse" arg0="true" />
            <param desc="connectionStringName">processing.apikey</param>
            <!-- The same header name must be defined in Sitecore.Xdb.Remote.Server.config for reporting.-->
            <param desc="headerName">X-Processing-Api-Key</param>
            <param desc="minimalApiKeyLength">32</param>
        </httpTransportFactory>
    </remote>
</processing>

Add an API authentication key to the ConnectionStrings.config file:

For example:
RequestResponse
```
<add name="processing.apikey" connectionString="90588d50667e47e0a02cb919185f7c30"/>
```

On the Processing server

To configure an API authentication key on the Processing server:

In the Sitecore.Xdb.Remote.Client.config file, locate the following section and update the connectionStringName parameter as shown:

RequestResponse

<processing role:require="Processing">
    <authenticationChecker singleInstance="true" type="Sitecore.Xdb.Reporting.HttpHeaderAuthenticationChecker, Sitecore.Xdb.Reporting">
        <!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
        <param desc="headerName">X-Processing-Api-Key</param>
        <param desc="connectionStringName">processing.apikey</param>
        <param desc="logger" resolve="true" type="Sitecore.Abstractions.BaseLog, Sitecore.Kernel" />
    </authenticationChecker>
</processing>

Add a new API authentication key to the ConnectionStrings.config file:

RequestResponse

<add name="processing.apikey" connectionString="90588d50667e47e0a02cb919185f7c30"/>

Remove the reporting.apikey from the ConnectionStrings.config file if it is present.

Optional configuration

Optional Content Management server configuration

The following table shows the default parameter settings in the Sitecore.Xdb.Remote.Client.config file that you can adjust later, if necessary. You can configure different parameter settings for Processing.

Note

If you're running Sitecore on Azure, the settings are in the App_Config/Sitecore/Azure/Sitecore.Xdb.Remote.Client.CM.config file.

Parameter	Description
ServiceUrl	The service host URL to use in all requests. Update this if the host name of your processing server changes.
ConnectionStringName	The name of the connection string that contains the API authentication key.
HeaderName	The name of the header to include in the request. Use the same header name on both servers. For example, X-Processing-Api-Key.
MinimalApiKeyLength	This specifies a minimum key length for the API authentication key. If it is too short, then the request will not be sent. Longer keys are more secure.
RequireHttps	Boolean switch set to “true” by default. Always use HTTPS in a production environment. If it is set to “true” and the schema in <paramref name=”serviceHostUrl”/> is not HTTPS, an exception will be thrown.

These configuration parameters appear in the following section of the Sitecore.Xdb.Remote.Client.config file:

RequestResponse

<processing>
    <remote enabled="true">
        <reportingStorageManagerProxy type="Sitecore.Analytics.Aggregation.History.Remoting.ReportingStorageManagerProxy, Sitecore.Analytics.Aggregation">
            <param desc="serviceLocation">/~/v81/processing/reportingstoragemanager/</param>
            <param desc="webTransportFactory" ref="processing/remote/httpTransportFactory" />
        </reportingStorageManagerProxy>
        <httpTransportFactory type="Sitecore.Analytics.Core.ApiKeyHttpTransportFactory, Sitecore.Analytics.Core" singleInstance="true">
            <param desc="serviceUrl"></param>
            <param desc="requireHttps" type="System.Boolean" factoryMethod="Parse" arg0="true" />
            <param desc="connectionStringName">reporting.apikey</param>
            <!-- The same header name must be defined in Sitecore.Xdb.Remote.Server.config for reporting.-->
            <param desc="headerName">X-Processing-Api-Key</param>
            <param desc="minimalApiKeyLength">32</param>
        </httpTransportFactory>
    </remote>
</processing>

Optional Processing server configuration

Parameter	Description
ConnectionStringName	The name of the connection string that contains the correct API authentication key (this should match the key of the server making the request).
HeaderName	The name of the header to check in the incoming server request.

RequestResponse

<processing role:require="Processing">
    <authenticationChecker singleInstance="true" type="Sitecore.Xdb.Reporting.HttpHeaderAuthenticationChecker, Sitecore.Xdb.Reporting">
        <!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
        <param desc="headerName">X-Processing-Api-Key</param>
        <param desc="connectionStringName">processing.apikey</param>
        <param desc="logger" resolve="true" type="Sitecore.Abstractions.BaseLog, Sitecore.Kernel" />
    </authenticationChecker>
</processing>

Do you have some feedback for us?

If you have suggestions for improving this article,