Loading...
Area: Episerver DXC Service
Applies to versions: Not applicable

Deployment API authentication

Authentication

The Deployment API for Episerver Digital Experience Service authenticates each user request using a pair of client key and a client secret.

Note: The credentials (client key and secret) are applicable to one specific DXC-S environment of a project. Every environment into which you want to deploy code needs a unique set of credentials. Authenticating the user with the credentials for each environment provides flexibility and granular control over deployments. So, as a partner developer, remember to request API credentials for all the environments that you want access to

API credential generation self-service

Episerver DXC Service Management Portal introduces a self-service option to generate deployment API credentials for anyone that has access rights to deploy code/content between DXC-S environments. You have the flexibility to manage API credentials by themselves without using Episerver Managed Services. 

The API tab in the DXC Service Management Portal generates new API credentials or retrieves an existing one for a selected environment. To manage your API credentials, follow these steps:

  1. Open the API tab. A list of all deployable environments appears.

    imageny71c.png

  2. Select an environment from the list and click Generate API credentials.

    imagehu7du.png

  3. Click OK in the confirmation message; a new API credential is generated.

    image9rzze.png

    Note: When generating new credentials, any old/existing credential for the selected environment will be removed with immediate effect. This means the users of the old API credential need to be informed with the newly generated API credential.

  4. You can see the newly generated credentials (API Key & Secret pair) (and copy them by clicking the imagez0mq.png copy button). However, the generated credential's API secret value is only visible until the next page refresh for security reasons.

    imageqenk.png

  5. After you refresh the page, the API Secret value is masked and cannot be copied. If the API credentials were not copied in the previous step, you need to generate new credentials.

    imagez3kop.png

How it works

HMAC computation

Before issuing a request, the client must compute a hash-based message authentication code (HMAC) that is unique to that request. The HMAC is computed as follows:

  1. A message is assembled by concatenating the following parameters:
    • App Key. This is a unique identifier provided to the client upon registration to use the platform.
    • HTTP request method. GET, POST, DELETE, and so on, as uppercase.
    • HTTP request target. Original request target.
    • Timestamp. Time at which the request was created, UTC in milliseconds from Unix epoch.
    • Nonce. A random, unique identifier, generated by the client.
    • MD5 hash of the HTTP request body.
  2. The message is hashed using a SHA256 based HMAC algorithm to produce a signature. The hashing mechanism uses the application's secret as a cryptographic key.

    Note: The secret is never communicated across the Internet.

  3. The bytes representing the signature are converted to a base64 encoded string.

Authorization header

Each request must include an "Authorization" HTTP header, which includes the computed HMAC and other supporting parameters. The value of the header must be in the following format.

Note: This format can be customized.

epi-hmac <app-key>:<timestamp>:<nonce>:<hmac>

The parameters comprising this header include:

  • App Key. This is a unique identifier provided to the client upon registration to use the platform.
  • Timestamp . Time at which the request was created; UTC in milliseconds from Unix epoch.
  • Nonce. A random, unique identifier, generated by the client.
  • HMAC. The signature computed in the previous step.

Note: The app key, timestamp, and nonce must exactly match the values applied in the computation of the HMAC.

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 18, 2019