URL Signing Rule

Introduction

As a content publisher, you can use Qwilt URL Signing for authorization, to safeguard against unauthorized access to your content that is delivered through the Qwilt CDN.

The article describes how to add the URL Signing rule to the site configuration. Configuring the rule is only one step of the overall implementation of URL Signing. See How to Implement Qwilt URL Signing for details.

The URL Signing rule is supported for Self Service Media Delivery.

Configure the Rule

To configure a Qwilt URL Signing rule:

1. Navigate to the Select Rule dialog.

2. In the Select Rule dialog, choose URL Signing.

3. Toggle on Enable Url Signing.

   

4. Select the relevant token Insertion Method:

   • First Path Segment: This method is recommended for adaptive bitrate (ABR) content delivery. (It is also suitable for non-ABR scenarios.)

     As a content publisher, you add the token to the first path segment of the initial request (master manifest). Assuming the usage of relative paths in the manifest files, the token is inherited and sent in subsequent requests of the ABR session.

     For example: https://www.example.com/qsig=<jwt payload>.<signature>/videos/movie123/master.m3u8

   • Uri Param: This method is best suited for non-ABR content delivery.
     With this method, the token is added as a query parameter.

     For example: https://www.example.com/path/to/file/master.m3u8?qsig=<jwt payload>.<signature>

5. From the Keyset Name field, select the relevant keyset.
   The keyset is a list of shared secret keys and IDs, to be used by both the signing (content publisher) and validating (Qwilt CDN) parties.
   If needed, create a new keyset.

6. Choose Add Rule.

Key Management

Qwilt URL signing requires secret sharing between the signing party (the content publisher) and the validating party (Qwilt). To share a secret key with Qwilt CDN, create a keyset with at least one key, and add it to the site configuration.

Qwilt URL signing supports multiple keys. Each key is mapped to a Key ID (KID). The signed client request includes a Key ID in the JWT payload, set with the kid JWT Claim.

Key Lifecycle Management

Here, we describe how to perform the key management functions via the Delivery Services Management UI. Alternatively, you can use the Keys Manager API.

Create a Keyset

In the Media Delivery Site Configuration UI, create a list of shared secret keys, each mapped to a Key ID, to be used by both the signing (content publisher) and validating (Qwilt CDN) parties.

Note that every time you update a keyset, you must republish the Media Delivery site or sites that use the keyset.

To create the keyset:

1. In the URL Signing dialog, select the Manage Keysets icon.

   

2. In the Keyset Management dialog, select Add Keyset.

3. Define the Keyset Name.
   Use an easily identifiable string.
   This name will appear in the URL Signing dialog, the Keyset Name list, and the Keyset Management dialog.

4. Select Save. The new keyset appears in the list of Keysets in the Keyset Management dialog.
   Note that the Keyset is inactive until you add at least one key to it.

   

5. Select the Keyset's Add Key to Keyset (+) icon.

6. In the Add Key to Keyset dialog, define the key parameters. See Add a Key to a Keyset.

7. Select Submit. The key is added to the keyset. The keyset is now available to any user in your organization.

Note: As soon as you add the first key to the keyset, a keyset ID is automatically assigned.

In the site configuration JSON, in the QW.QwiltUrlsigning object, the keySet attribute value is the keyset ID and not the keyset name.

{
  "generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.QwiltUrlsigning",
  "generic-metadata-value": {
    "enforce": true,
    "insertion-method": "first-path-segment",
    "keySet": 30
  }
}

Retrieve the Keyset ID

Add a Key to a Keyset

You must add at least one key to a keyset for the keyset to be available for selection when configuring the URL Signing rule. A keyset can contain multiple keys. The JWT payload of the signed client request specifies the Key ID of the shared secret key to be used by Qwilt CDN to authorize the request.

To add a key to a keyset:

1. Navigate to the Keyset Manager via the URL Signing Rule dialog box.

   

2. In the Keyset Management dialog, find the keyset you want to edit.

3. Click the three dots icon to the right of the keyset name and select Add Key to Keyset. (Or, if no key is yet defined, click the + icon that appears instead of the three dots icon.)

4. In the Add Key to Keyset dialog, define these parameters:

   • Key Name: Name the key. The key name is displayed in the Keyset Management dialog.
   • Key: Paste the base64 encoded key into the Key field.
     • The secret key must be base64 encoded. Otherwise, the keyset submission fails.
     • When you Submit the keyset, the key string is SHA-512 hashed. The base64 encoded key value will no longer be visible. The hashed key value is displayed in the Keyset Management and Edit Keyset dialogs.
   • Description: Optionally, provide a key description.
   • KID: Select a Key ID. The KID value is passed in the request URL, indicating which secret should be used by Qwilt CDN to validate the request. Each key in the set must have a unique ID. Do not assign the same KID to more than one key.

5. Select Submit. The key is added to the keyset.

6. If your site is already in production, republish the site configuration. The key can be used for validation by the Qwilt CDN only after you republish the site configuration.

Update a Keyset

You can update a keyset by adding or deleting keys. If your site is already in production, you must republish the site to activate the updated keyset.

To update a keyset:

1. In the URL Signing dialog, select the Manage Keysets icon.
   

2. In the Keyset Management dialog, find the keyset you want to edit.

   • To add a key, click the three dots icon to the right of the keyset name and select Add Key to Keyset. (Or, if no key is yet defined, click the + icon.)
   • To delete a key from a keyset, click the arrow by the keyset name to display its keys, hover over the key you want to delete and then click the trashcan icon that appears.

3. If your site is already in production, republish the site configuration. The updated keyset is used for validation by the Qwilt CDN only after you republish the site configuration.

Retrieve a Key ID

When signing a client request, the KID of the shared secret key must be included in the JWT payload.

To retrieve the Key ID:

1. In the Keyset Manager dialog, find the keyset that contains the key.
2. Expand the keyset to display the keys.
3. Select Key ID to copy the Key ID.
   

Retrieve a Keyset ID

In the SVTA URL Signing component, the keyset is identified by its Keyset ID.

To retrieve the Keyset ID:

1. In the Keyset Manager dialog, find the keyset that contains the key.
2. Click the three dots icon to the right of the keyname and select the Keyset ID menu option to copy the Keyset ID.
   

SVTA Component (QW.QwiltURLsigning)

When you save the configuration version, the QW.QwiltUrlsigning SVTA component is added to the configuration JSON. This is a private feature developed by Qwilt.

{
  "generic-metadata-type": "MI.PrivateFeature.Qwilt.QW.QwiltUrlsigning",
  "generic-metadata-value": {
    "enforce": true,
    "insertion-method": "first-path-segment",
    "keySet": 30
  }
}