# Secure MediaPackage content with CDN authorization
CDN authorizationAdded CDN static auth headers info

Added the topic that describes how to set up CDN authorization if your CDN doesn't support AWS SigV4.

AWS Elemental MediaPackage CDN authorization helps you protect your streaming content from unauthorized access and direct origin requests. When you configure CDN authorization, MediaPackage only fulfills playback requests that include valid authorization headers from your content delivery network, preventing users from bypassing your CDN to access content directly.

If you use Amazon CloudFront for your CDN, you can configure access to MediaPackage resources with [AWS Signature Version 4 (SigV4) authentication](sig-v4-authenticating-requests.md). 

If your CDN doesn't support SigV4, use the following instructions to set up authorization headers between your CDN and MediaPackage.

## How it works


You configure your CDN to include a *custom HTTP header* in content requests to MediaPackage. 

The custom HTTP header must use the exact name **X-MediaPackageV2-CDNIdentifier** with a value that is 8-256 characters long. We strongly recommend using the [UUID version 4](https://www.ietf.org/rfc/rfc4122.txt) format for the value, which produces a 36-character string that is both unique and unpredictable.

**Example header**  
The following example shows the required header format.  

```
X-MediaPackageV2-CDNIdentifier: 9ceebbe7-9607-4552-8764-876e47032660
```

You store the header value as a *secret* in AWS Secrets Manager. When your CDN sends a playback request, MediaPackage verifies the custom HTTP header value. MediaPackage compares this value with the stored secret. An AWS Identity and Access Management permissions policy and role grant MediaPackage permission to read the secret.

If the values match, MediaPackage serves the content along with an HTTP `200 OK` status code. If the values don't match, or if the authorization request fails, MediaPackage doesn't serve the content and returns an HTTP `403 Unauthorized` status code.

The following image shows successful CDN authorization using Amazon CloudFront.

![\[This diagram illustrates the CDN authorization workflow: 1. A playback device requests content from Amazon CloudFront 2. CloudFront includes the X-MediaPackageV2-CDNIdentifier header in its request to MediaPackage 3. MediaPackage retrieves the secret value from AWS Secrets Manager (requires IAM permissions) 4. MediaPackage compares the header value with the stored secret 5. When values match, MediaPackage returns HTTP 200 OK with video content 6. CloudFront delivers the content to the playback device When values don't match, MediaPackage returns HTTP 403 Unauthorized.\]](http://docs.aws.amazon.com/mediapackage/latest/userguide/images/cdn_auth.png)


Complete the following procedures to configure CDN authorization with MediaPackage.

**Topics**
+ [

## How it works
](#working-with-cdn-auth)
+ [

# Configure MediaPackage CDN authorization setup
](cdn-auth-setup.md)
+ [

# Rotate MediaPackage CDN authorization secrets
](cdn-auth-rotate.md)
+ [

# Troubleshoot MediaPackage CDN authorization errors
](cdn-auth-troubleshooting.md)
+ [

# Optimize MediaPackage CDN authorization security
](cdn-auth-best-practices.md)

# Configure MediaPackage CDN authorization setup
Setup CDN authorization

Configure AWS Elemental MediaPackage CDN authorization to secure your streaming content by setting up custom HTTP headers, storing secrets, and configuring IAM permissions. This procedure ensures that only authorized CDN requests can access your MediaPackage endpoints.

**To set up CDN authorization**

1. **Configure a CDN custom origin HTTP header.** In your CDN, configure a custom origin HTTP header that contains the header **X-MediaPackageV2-CDNIdentifier** and a value. For the value, we recommend that you use the [UUID version 4](https://www.ietf.org/rfc/rfc4122.txt) format, which produces a 36-character string. If you aren't using the UUID version 4 format, the value must be 8-256 characters long.
**Important**  
The value you choose should be a static value. There isn't native integration between your CDN and AWS Secrets Manager, so the value should be static both in your CDN and in AWS Secrets Manager. If you change this value after you configure your CDN and your secret, you have to manually rotate the value. For more information, see [Rotate MediaPackage CDN authorization secrets](cdn-auth-rotate.md).

   **Example header and value**

   ```
   X-MediaPackageV2-CDNIdentifier: 9ceebbe7-9607-4552-8764-876e47032660
   ```

   These steps will vary depending on your CDN. For distribution setup with custom headers in Amazon CloudFront, see the [Distribution settings reference](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html) in the Amazon CloudFront developer guide.

1. **Store the value as a secret in AWS Secrets Manager.** Store the custom header value as a *secret* in AWS Secrets Manager. The secret must use the same AWS account and Region settings as your MediaPackage resources. MediaPackage doesn't support sharing secrets across accounts or Regions. However, you can use the same secret across multiple endpoints in the same Region and on the same account.
**Important**  
The secret must be created in the same AWS Region as your MediaPackage endpoint. Cross-Region secret access is not supported.

   1. Sign in to the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).

   1. Choose **Store a new secret**. For **Secret type**, choose **Other type of secrets**.

   1. For **Key/value pairs**, enter the key and value information.
      + In the box on the left (key), enter **MediaPackageV2CDNIdentifier**.
      + In the box on the right (value), enter the value that you configured for your custom origin HTTP header. For example, `9ceebbe7-9607-4552-8764-876e47032660`.

   1. For **Encryption key**, you can use the AWS KMS key that Secrets Manager creates by default.

   1. Choose **Next**.

   1. For **Secret name**, we recommend that you prefix it with **MediaPackageV2/** so that you know it's a secret used for MediaPackage. For example, **MediaPackageV2/cdn\$1auth\$1us-west-2**.

   1. Choose **Next**.

   1. For **Configure automatic rotation**, keep the default **Disable automatic rotation** setting.

      If you need to rotate the key later, see [Rotate MediaPackage CDN authorization secrets](cdn-auth-rotate.md).

   1. Choose **Next**, and then choose **Store**.

      This takes you to the list of your secrets.

   1. Select your secret name to view the **Secret ARN**. The ARN has a value similar to `arn:aws:secretsmanager:us-west-2:123456789012:secret:MediaPackageV2/cdn_auth_test-xxxxxx`. You use the ARN for the secret when you configure CDN authorization for MediaPackage in step 4.

1. **Create an IAM role for MediaPackage access to Secrets Manager.** Create an IAM role to give MediaPackage access to Secrets Manager and AWS Key Management Service (AWS KMS). When MediaPackage receives a playback request from the CDN that includes a secret value in the custom headers, MediaPackage retrieves the stored secret value from AWS KMS and verifies that the secret values match. Follow the steps in [Allowing MediaPackage to access other AWS services](setting-up-create-trust-rel.md) to set up the policy and role.

   You use the ARN for the IAM role that you created when you enable CDN authorization in MediaPackage in the next step. 

1. **Enable CDN authorization in MediaPackage.** You can enable CDN authorization for your channel endpoints from the MediaPackage console, AWS CLI, or MediaPackage API. 
**Tip**  
Use the same secret across multiple endpoints in the same Region and on the same account. Reduce costs by creating a new secret only when necessary for your workflow.

   1. Open the MediaPackage console at [https://console.aws.amazon.com/mediapackage/](https://console.aws.amazon.com/mediapackage/).

   1. Under **Live v2**, create or edit a channel group and channel. For help, see [Creating a channel group in AWS Elemental MediaPackage](channel-group-create.md).

   1. On the channel, create or edit an endpoint.

   1. In **Endpoint policy**, select **Attach a custom policy** and add a policy for the endpoint.   
**Example policy with CDN auth condition**  

------
#### [ JSON ]

****  

      ```
      {
        "Version":"2012-10-17",		 	 	 
        "Statement": [
          {
            "Sid": "AllowGetObjectAccessForAuthorizedRequest",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "mediapackagev2:GetObject",
            "Resource": "arn:aws:mediapackagev2:us-east-1:111122223333:channelGroup/channelGroupName/channel/channelName/originEndpoint/originEndpointName",
            "Condition": {
              "Bool": {
                "mediapackagev2:RequestHasMatchingCdnAuthHeader": "true"
              }
            }
          }
        ]
      }
      ```

------

   1. In **CDN authorization configuration**, complete the fields:
      + In **Secrets role ARN**, enter the ARN for the IAM role that you created in step 3.
      + In **CDN identifier secret ARN**, enter the ARN for the secret in Secrets Manager that your CDN uses for authorization to access your endpoint.

   1. Complete the remaining fields as needed and save the endpoint.

   You have now completed the setup for CDN authorization. Requests to this endpoint must contain the same authorization code that you saved in Secrets Manager.

**To enable CDN authorization via the MediaPackage API**  
For information about enabling CDN authorization with the MediaPackage API, see [AWS Elemental MediaPackage V2 Live API Reference](https://docs.aws.amazon.com/mediapackage/latest/APIReference/Welcome.html).

# Rotate MediaPackage CDN authorization secrets
Rotate CDN secrets

When you need to update your AWS Elemental MediaPackage CDN authorization credentials, you must rotate the stored secret value in AWS Secrets Manager to maintain synchronization with your CDN's custom HTTP header. This process ensures continuous content delivery while updating security credentials.

**To rotate the value**

1. Update the stored secret value in Secrets Manager as described in [Modifying a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_update-secret.html) in the *AWS Secrets Manager User Guide*.

   To ensure continued playback for active streams, MediaPackage authorizes requests that use either the current value in Secrets Manager or one version back.

1. Wait 5 minutes for MediaPackage to recognize that the value has changed in Secrets Manager.

1. In your CDN, update the value in `X-MediaPackageV2-CDNIdentifier` to the new secret value.

1. Wait for your CDN to update fully with the new value before you send any requests through it to MediaPackage.

**Emergency rotation details**  
In emergency situations where you need to immediately invalidate a secret, do one of the following:
+ Update the endpoint configuration to remove the compromised secret ARN and replace it with a new secret ARN.
+ Alternatively, rotate the secret twice in quick succession. After 5 minutes, MediaPackage will no longer accept the old secret values since the incoming header value would not match either the current or previous secret.

**Note**  
MediaPackage caches secret values for 5 minutes. During this period, both the old and new secret values may be valid for authorization.

# Troubleshoot MediaPackage CDN authorization errors
Troubleshoot CDN authorization

When AWS Elemental MediaPackage CDN authorization fails, you may encounter various error codes and authorization issues. This section helps you identify and resolve common problems with CDN authorization configuration, secret management, and IAM permissions.


**Common Error Scenarios and Resolutions**  

| Scenario | Error Type | Resolution | 
| --- | --- | --- | 
| Secret validation failure | 4XX error | Verify that your secret is stored with the correct key name MediaPackageV2CDNIdentifier and the value is between 8-256 characters. | 
| IAM role access denied | 4XX error | Check that the IAM role has the correct permissions and trust relationship as described in [Configure MediaPackage CDN authorization setup](cdn-auth-setup.md). | 
| Secret not found | 4XX error | Verify that the secret ARN is correct and the secret exists in the same Region as your MediaPackage endpoint. | 
| Header value mismatch | 403 Unauthorized | Ensure that the value in the X-MediaPackageV2-CDNIdentifier header matches the value stored in Secrets Manager. | 

# Optimize MediaPackage CDN authorization security
CDN authorization best practices

Implementing AWS Elemental MediaPackage CDN authorization effectively requires following security best practices for secret management, monitoring, and operational procedures. These recommendations help you maintain secure, cost-effective, and reliable content delivery.
+ **Use UUID format for secret values** - We recommend using UUID version 4 format for your secret values, which produces a 36-character string that is both unique and unpredictable.
+ **Reuse secrets across endpoints** - When appropriate for your security requirements, use the same secret across multiple endpoints in the same Region and account to reduce management overhead and costs.
+ **Implement regular rotation** - Rotate your secrets periodically as part of your security best practices.
+ **Monitor authorization failures** - Set up alarms for unusual patterns of authorization failures, which could indicate attempted unauthorized access.
+ **Test rotation procedures** - Regularly test your secret rotation procedures to ensure smooth transitions during actual rotations.