Configure security keys on servers in a scaled environment

Current version: 8.2

Applies to

xDB Reporting 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 Reporting Service server. For example, on a content management server that needs to communicate with a remote Reporting Service 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.

Note

API authentication keys are required in Sitecore 8.2 update 1 and later.

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 Reporting Service server must match the key stored on a content management server to successfully retrieve data from the Reporting Service.

The server authentication process is as follows:

  • A content management client requests data from the Reporting Service server using the Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory class.

  • When the Reporting Service server receives the request, the ApiKeyReportDataProvider checks that the API authentication key from the HTTP header matches (case-sensitive) the one stored on the Reporting Service 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.

This topic describes:

Configure an API authentication key

To configure an API authentication key:

  1. Add an API authentication key to the server instance that is making the request for data from the Reporting Service server, such as to a content management server. On the content management server, navigate to the Website\App_Config folder and open the ConnectionString.config file.

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

  3. For example:

    RequestResponse
    <add name="reporting.apikey" connectionString="67588d50667e47e0a02cb919185f7c30"/>

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

  5. Add the same key to the server that will receive the request, such as a Reporting Service server. Repeat the same process by entering the API authentication key in the ConnectionStrings.config file.

Content management server configuration

When you set up a dedicated content management server, you must also enable the Sitecore.Xdb.Remote.Client.config file. The following table shows the default parameter settings in this file that you can adjust later, if necessary:

Parameter

Description

ServiceUrl

The service host URL to use in all requests. Update this if the host name of your reporting 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-Reporting-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
<httpTransportFactory type="Sitecore.Analytics.Commons.ApiKeyHttpTransportFactory, Sitecore.Analytics" 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-Reporting-Api-Key</param>      
      <param desc="minimalApiKeyLength">32</param>    
</httpTransportFactory>

Reporting Service server configuration

On the Reporting Service server, the Sitecore.Analytics.Reporting.ApiKeyReportDataProvider is defined in the <dataProvider> configuration section of the Sitecore.Xdb.Remote.Server.config file. The Sitecore.Xdb.Remote.Server.config file contains the following default parameters:

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.

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

RequestResponse
<dataProvider type="Sitecore.Analytics.Reporting.ReportDataProvider, Sitecore.Analytics" singleInstance="true" cacheEnabled="false">
      <patch:attribute name="type">Sitecore.Analytics.Reporting.ApiKeyReportDataProvider, Sitecore.Analytics</patch:attribute>
<!-- The same header name must be defined in Sitecore.Xdb.Remote.Client.config for CM instance.-->
      <param desc="headerName">X-Reporting-Api-Key</param>
      <param desc="connectionStringName">reporting.apikey</param>
</dataProvider>

Do you have some feedback for us?

If you have suggestions for improving this article,