Security best practice

This page provides security guidelines for integrating with the Amplience APIs. We explain the security features provided and include recommendations for protecting your data and environments.

Shared responsibility

In the Amplience security model responsibilities are shared between you and Amplience.

Your responsibilities

Protecting access to your API key and secret.

You are responsible for managing access to the credentials used with the Dynamic Content Management API. We recommend the following:

• Keep the API credentials secret and do not store the key and secret within an app.
• Follow the rest of the guidelines in the securing your API keys section.
• Inform Amplience of any unauthorised access to your credentials. Amplience can then revoke the credentials so that they can no longer be used.

Protecting access to unpublished (staged) content and assets

Staged content can be accessed using a virtual staging environment, access to which is restricted to an IP white list that you provide. To protect access to your unpublished content you should:

• Inform Amplience of the IP addresses to white list for access to unreleased content and assets.
• Ensure that only authorised staff can access content from these IPs (for example via a VPN)

More information can be found in the securing your environments section.

Verifying that a webhook request originates from Amplience

You can use webhooks to build an integration between Dynamic Content and your APIs. A webhook request will be sent to the URL that you specify when an action occurs in Dynamic Content. We recommend the following:

• Use the webhook secret (encoded in the webhook request) to verify that a webhook request originated from Amplience Dynamic Content and was not tampered with in transit
• White list the IP addresses in the webhook range to ensure that you only receive webhook requests from this range of IPs.

More information is provided in the securing integrations section.

Amplience responsibilities

Amplience responsibilities regarding the security of APIs and integrations are as follows:

• Providing access to all Amplience APIs is over HTTPS.
• Protecting access to the Dynamic Content Management APIs via a key and secret.
• Restricting access to staged content using a white list of IP addresses which you provide.
• Signing each webhook request with a hash generated from a secret and the request body.
• Ensuring that webhook requests originate from a specified IP address range which you can white list.
• Encrypting credentials used in "off the shelf" integrations.

HTTPS

With the exception of the Dynamic Media API, all of the Amplience APIs are accessed via HTTPS and encryted in transit. The Dynamic Media image API is also available over HTTP to support situations where HTTPS cannot be used.

The business user interface for Dynamic Content and Content Hub is only available via HTTPS.

API security

Amplience APIs can be categorised as follows:

• Production APIs. This includes the Content Delivery and Dynamic Media APIs. These APIs are used to consume published content that is considered internet facing and is therefore unauthenticated.

• Staging APIs. Access to unpublished content is provided using our virtual staging APIs. Staged content is protected by IP white listing.

• Back office APIs. Access to back-office operations via the Dynamic Content Management API is protected by OAuth 2.0 using the JSON Web Token (JWT) standard with RS256 (RSA Signature with SHA-256) signing.

Securing your API keys

You must keep your API credentials secret and not disclose them to an unauthorised user. We recommend following these guidelines:

• Do not include the API key and secret in your apps.
• Only use the API key and secret for server side integrations.
• Do not commit the API and secret to a source code hosting service (such as GitHub or Bitbucket).
• Create a new API key and secret for each use case/ integration.
• Use the "principle of least privilege" and request an API key with only those permissions that you need to perform the tasks required in a project.

Securing integrations

Amplience provides a number of features that make it easier to build your own integration with Dynamic Content, as well as "off the shelf" integrations. In this section we've included security guidelines for using each of these integration features.

Webhooks

Webhooks are triggered when a certain action occurs in Dynamic Content. A webhook request is sent to the URL you specify, containing a payload. Amplience has included a number of security features as part of the webhook implementation.

Request IP range

The range of IP addresses from which IP addresses is sent from Dynamic Content is as follows:

34.242.23.128/32
63.32.123.5/32
52.19.110.60/32

Note that outbound Webhook requests are routed through these utility IPs so that administrators can apply strict firewall policies. These IPs are not connected to Amplience production services and will not route inbound traffic.

You should ensure that these IP addresses are white listed by your back end systems.

Signed requests

Webhooks are signed with a shared secret using SHA-256.

When a webhook is created, a webhook secret is generated. This is used to verify that the webhook originated in Dynamic Content and that the body sent to the webhook URL has not been tampered with in transit. You should save the secret and use it for later verification.

When the webhook is invoked, a hash is generated from the secret and the request body and sent in the "X-Amplience-Webhook-Signature" included with the webhook request. You can then compare this hash with the value generated from the saved webhook secret.

Secret headers

The secret headers feature can be used to transmit a secret value, for example an API key, as part of the webhook. This wil be encrypted at rest to prevent it being retrievable from the user interface.

Extensions

Dynamic Content extensions are a way of extending the content editing form and dashboard. Extensions have a configurable set of permissions that are used to control what features the extension can access.

The user controls which permissions are set for an extension, the extension cannot modify which permissions it is granted.

Amplience search

Amplience search is powered by Algolia and as such follows the Algolia security best practices.

Out of the box integrations

The credentials you use for the Dynamic Content Salesforce Commerce Cloud (SFCC) integration will be encrypted at rest and cannot be viewed in the user interface.

Making use of the principle of least privilege, we recommend that you create separate SFCC credentials for the Dynamic Content integration with access only to the features that you need.

Securing your environments

To access staged (unpublished) content you can use a virtual staging environment (VSE). A VSE domain is used in place of the production content delivery and Dynamic Media URLs in order to retrieve unpublished content and assets.

IP restricted access to staging APIs

Access to a VSE is controlled using an IP white list which you specify. The white list is used to restrict access to the environment to the set of IP addresses specified by an administrator. Any requests originating from an IP address not on the white list will return an error.

Other ways of restricting access to staged content

The white list is the primary way of restricting access to a virtual staging environment, but there are a number of other security measures that protect your content from unauthorised access.

• Only an administrator has permission to create a virtual staging environment and grant read only access to the specified resources restricted by IP address. The administrator can edit the details of the environment, including the asset stores that can be accessed and the white list, or delete the environment, at any time.

• When a virtual environment is created, a server side token is created and used to store the security credentials that the administrator has defined for this environment. When an asset is requested using a staging URL, if the IP address making the request is on the white list, the staging service will look up the credentials on your behalf and load the asset based on the rules defined.

• Content Hub asset stores have permissions attached to them, so that only specified users can view and upload content to them.

• Only a certain range of IP addresses can be specified by default, so the administrator cannot accidentally allow access and make assets public.

• By providing access to users via a Virtual Private Network (VPN), that requires a user name and password or key based authentication, you can add a further layer of security to that provided by access control via a trusted IP address.

Keeping the production and staging environments separate

We recommend keeping your production and staging environments separate and following these guidelines:

• The virtual staging API is rate limited and must not be used in production.
• You should use a separate Dynamic Content hub for production and development/ testing.
• Use different API keys for integrating with each environment.

Securing your code

Amplience assumes that its customers will build integrations to conform to their own security standards. We also have some additional recommendations:

• To protect against code injection attacks you should sanitize values returned from APIs before using them in your application.
• Do not include any credentials in your code, instead make these credentials externally configurable.

Securing sensitive data

We recommend the following steps to protect the inadvertent leaking of sensitive data:

• Don’t include sensitive data in places that could be logged. This includes a hub name in Dynamic Content, or as part of a delivery key.
• Don't include API keys in code, content or in unencrypted webhook parameters. When using webhooks you can add credentials as secret headers that are encrypted.

Securing user accounts

Amplience provides a permissions model for access to the Dynamic Content Management API, and to the business user interface, that controls which features and resources (such as Dynamic Content hubs) a user has access to.

• We have organized user permissions into a set of roles that correspond to user roles. Using the principle of least privilege, you should only request those permissions that a user requires to perform their role.
• You can restrict access to resources such as hubs and repositories, for each user, allowing you to restrict access by brand and region, for example.

Related pages

Amplience APIs

Dynamic Content Management API

Virtual staging

Webhooks

Dynamic Media API

Content Delivery 2 API

Dynamic Content extensions

Permissions

Algolia security best practices