Configure API authentication keys in a scaled environment
Applies to |
xDB Processing and Content Management. |
Sitecore Installation Framework |
Security keys are not configured by default. |
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.
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.
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.
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 theConnectionString.config
file. -
In the
ConnectionStrings.config
file, find thereporting.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"/>
ImportantThe 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 theConnectionStrings.config
file. -
Add the
reporting.apikey
connection string to theConnectionStrings.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 theconnectionStringName
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"/>
ImportantMake sure the API authentication key values differ from one another.
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 theconnectionStringName
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 theConnectionStrings.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.
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:
<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. |
<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>