With this behavior enabled, you can specify details about the Origin Server to apply related optimizations to the property configuration.

📘

If you're using Adaptive Media Delivery (AMD), Download Delivery, or Object Delivery, this behavior is required in the Default Rule. What you set here defines how various preset best practices are applied and optimized.

Origin Location

Select the location of the origin server, based on its Origin Type:

• NetStorage. Select Unknown if you're using ​Akamai​ NetStorage as your origin.

• Your Own Origin. Select the geographic location of your origin server. If you aren't sure about your server location, select Unknown.

Authentication Method

Select the authentication method to use. The options available, and the appropriate settings, depend on the product in use:

Sorting query parameters

Alphabetical sorting of all canonical query string parameters by key name is required for successful AWS SigV4 authentication.

📘

We recommend enabling both the Encode Path and Query Parameters and Sort Query Parameters options. This ensures proper encoding is applied first, followed by sorting for successful AWS authentication.

Encoding path and query parameters

Things you need to know when using the Encode Query Parameters feature:

• The space character is encoded as %20. All other bytes, including special characters are encoded by ​Akamai​. For example, $, +, !, (', '' and *.
• The feature encodes both the path and query string parameters in the URI.
• Before encoding, decode both path and query string parameters of the URI to prevent the issues caused by repeated encoding on your side.
• Exclusions for URI encoding:
  • Unreserved characters. For example, A-Z, a-z, 0-9, -, ., _, and ~.
  • Special characters in query strings. For example, & and =.
  • Path exclusions (/ and =) from the encoding of the URI path.

📘

We recommend enabling both the Encode Path and Query Parameters and Sort Query Parameters options. This ensures proper encoding is applied first, followed by sorting for optimal compatibility and security.

Encoding equal sign

Every query string parameter must contain an equality (=) sign in the key=value format even if the value is empty. The key-value query string must contain a value or at least an equal (=) sign. Otherwise the missing equal sign is added automatically. Every equal (=) sign in the value part of the query string parameter must be encoded. The first equal (=) sign remains, and others are replaced with %3D.

Before you use a third-party cloud provider

Pay attention to these points when using GCS or AWS:

• You can check your authentication details in the file you saved when creating your access key. If you didn't download the file, or if you lost it, you may need to delete the existing access key and add a new one. See Managing HMAC keys in GCS or Managing Access Keys (console) in AWS.

• You may be eligible to streamline client authentication by using Cloud Access Manager. See Use Cloud Access Manager (recommended) for details.

• Use a property with an akamaized hostname. This lets you either retrieve objects from the origin, or for read-only bucket operations. This is because we're currently limited to storing cloud provider access keys in clear text. This doesn't carry the level of protection you might expect for the transmission of personally identifiable information (PII).

• Consider using two separate sets of cloud provider access keys. Dedicate one to GET operations and another for POST, PUT, or DELETE operations. For all GET operations, set them up to use a property via Property Manager; for POST, PUT, and DELETE operations, you should use the APIs or SDKs offered by the associated cloud provider.

• Regularly rotate the cloud provider access keys. This reduces the likelihood of unauthorized diversion of confidential information.

• Only the Authorization header is supported (AWS, only). If you're using query string parameters with this authentication, each query parameter in the incoming client request must be sorted alphabetically, and URL encoded.

Use Cloud Access Manager (recommended)

If you're using Akamai Signature Header Authentication or a third-party cloud provider for your origin server—GCS or AWS—consider using ​Akamai​'s Cloud Access Manager to streamline client authentication.

The problem

In a typical transaction, you need to include a signature in the request so your third-party cloud provider authenticates a requesting client. This signature contains an access key you get from your cloud provider. This key is made up of a unique access identifier and a secret access key. Typically, you'd need to include both of these values when setting up the Authentication Method here in the Origin Characteristics behavior. When receiving the request, the third-party cloud provider calculates the signature and compares it to the one sent in the client request. If they match, the request is considered authentic. If they don't match, the request is denied. While this standard method works, it has some drawbacks:

• You need to set up the mechanism to inject the signature into a client request.

• Requests need to proxy through your origin, which can delay the request.

• The access identifier and secret access key are openly visible to anyone that can see your property in ​Akamai Control Center​.

The solution

Cloud Access Manager is a separate application that lets you privately create and name your access keys. You just add an access key to your property using its name, so the access identifier and secret key are hidden. Cloud Access Manager uses the ​Akamai​ Intelligent Platform to route origin requests directly to your third-party cloud provider. ​Akamai​ edge servers inject access key authentication on the forward origin path for you. This can decrease cost, bandwidth requirements, and the number of hits to your origin during peak times.

🚧

Once Cloud Access Manager is enabled, the secret access key is encrypted and isn't visible to anyone, including ​Akamai​. This may affect the way ​Akamai​ works with you to troubleshoot issues.

Set up Cloud Access Manager

1. Start by getting authentication details from your cloud provider.

2. Use Cloud Access Manager to create an access key.

3. Configure settings here in the Origin Characteristics behavior to sign requests with your access key:

   • Origin Location. Select the geographical location of your origin server to optimize access to it. If you aren't sure about your server location, you can leave it as Unknown.

   • Authentication Method. Select the third-party cloud provider that you use as your origin, either Amazon Web Services or Interoperability Google Cloud Storage.

   • Encrypted Storage. With this option set to Yes, you can refer to access keys you created that are securely stored in Cloud Access Manager. If you disable this option, the Origin Characteristics behavior stores the authentication details unencrypted.

   • Access Key. Select the access key that you want to use to sign requests to a cloud origin. This field lists only active access keys that you created in Cloud Access Manager that match your property's authentication method selected in the Origin Characteristics behavior.

   • Region (Amazon Web Services, only). Enter the code of the AWS region that houses your AWS service.

   • Service Endpoint (Amazon Web Services, only). Enter the code of your AWS service. This is the segment or its part that precedes amazonaws.com or a region code in your the AWS service endpoint. For example, s3 is the service code for this service endpoint: https:// account-id.s3-control.eu-north-1.amazonaws.com. See AWS Service Endpoints and Service Endpoints and Quotas.

For complete details, see the Cloud Access Manager documentation.

Akamai Signature Header Authentication

When you use Akamai Signature Header Authentication, a pair of request headers are generated on the Akamai server and passed to your origin. The origin uses a secret key that you define in the behavior to decrypt the headers and confirm that requests are coming from your Akamai configuration.

Request headers

Using this behavior results in two extra headers being added to the forward request from Akamai to your origin. The two headers generated are:

• X-Akamai-G2O-Auth-Data. This is the “data header” that contains a list of attributes for the request, including the identifier of the secret key used to generate the X-Akamai-G2O-Auth-Sign header.
• X-Akamai-G2O-Auth-Sign. This is the “sign header” that contains a hash of the data header and the forward URL, generated using your secret key.

Using your secret key, the origin hashes the data header and the forward URL, and compares it to the sign header; if they’re the same, the request is validated.

X-Akamai-G2O-Auth-Data

The X-Akamai-G2O-Auth-Data header contains six elements, each separated by a comma and a space. For example: 5, 23.50.50.13, 64.124.137.130, 1738191250, 4545696.900708813, 1b4ead

These elements are, in order:

• Version: 5. The numeric value that represents the Encryption algorithm version option.
• Server-ip-address: 23.50.50.13. The IP address of the Akamai server. This address is identified by your origin in the REMOTE_ADDR web server variable.
• Client-ip-address: 64.124.137.130. The client IP address passed to the origin in either, or both, of the True-Client-IP or X-Forwarded-For request headers.
• Timestamp: 1738191250. A timestamp indicating when the string was generated.
• Unique-identifier: 4545696.900708813. A unique value string generated for the specific request. This value can be used by the origin to check for any replay attacks.
• Key-identifier: 1b4ead. Your access key ID value.

X-Akamai-G2O-Auth-Sign

The X-Akamai-G2O-Auth-Sign header contains a Base64-encoded Hash-based Message Authentication Code (HMAC) of two concatenated values using your secret key:

• The X-Akamai-G2O-Auth-Data header. This is the data header shown in the example above.
• The forward URL. This is the URL that the origin receives from Akamai. For example: /abc/def/ghi/?akamai=great

Here is an example of how Akamai generates the header using the example data header and forward URL above, using the SHA256-HMAC algorithm:

sign_string = base64_encode(hash_hmac("sha256", "5, 23.50.50.13, 64.124.137.130, 1738191250, 4545696.900708813, 1b4ead/abc/def/ghi?akamai=great", secret_key))

The resulting value which is passed in this header looks like this: EHRYyJqjCjxpn7Fs/NnsPSKGc4Bsjy2xOXsIcVDk5gU=

🚧

Since the X-Akamai-G2O-Auth-Sign header is encrypted, your real values aren’t visible.

Set up behavior options

Once you select the Akamai Signature Header Authentication authentication method in the Origin Characteristics behavior, there are multiple options you need to configure.

Encryption algorithm version

Choose one of the following encryption algorithm options. SHA256-HMAC is the default, and most secure, option. Unless you have a requirement to use a lower level of encryption, we recommend using this default:

• (3) MD5-HMAC
• (4) SHA1-HMAC
• (5) SHA256-HMAC

The number in parentheses indicates the value that will be passed in the Version element of the X-Akamai-G2O-Auth-Data header.

Secret key

Enter the secret key you want to use to encrypt the signed headers. Make sure your key contains only alphanumeric characters (a-z, A-Z, 0-9) and is 10-64 characters in length.

You can define your secret key two ways:

• Akamai Cloud Access Manager (CAM, recommended): Only available with encrypted key storage. Lets you securely store, manage, and automate cloud provider credentials (access keys) for cloud origin authentication. See Cloud Access Manager: Create an access key.
  To use a key stored in CAM, change the Encrypted Storage option on On, and select your key name.
• Generate a key: For example, 1b4945fa74c13181912a2c3a8a46474dadeeea7949917c10b623067b86ac0ead
  • With Property Manager: In the Origin Characteristics behavior, use the refresh icon next to the Secret Key field to generate a random 24-byte hexadecimal key.
  • With Akamai Debug Utilities: Navigate to Generated Secret Key to generate a random 64-byte hexadecimal key.

🚧

Save the key you enter here. You’ll need to use it at your origin to verify the headers that Akamai sends.

For security reasons, do not use the example values in this guide.

Access key ID

Your access key ID, also known as the nonce, is a short alphanumeric string passed to your origin in the X-Akamai-G2O-Auth-Data header. This value is used by your origin to identify which secret was used to generate the X-Akamai-G2O-Auth-Sign header sent by Akamai, so it can use the same secret to verify that header. Your access key ID can be:

• Made up of alphanumeric characters (a-z, A-Z, 0-9)
• No more than 8 characters in length
• A random string or a word

For example: Consider the access key ID 1b4ead where 1b4 and ead are the first and last three bytes of your secret key, respectively. This example ties your access key ID to your secret key, so you can easily identify it later on as the secret key used to generate the signed string.

Header verification

For your origin to verify that the request came from your configuration using your secret key, you need to replicate Akamai’s process used to create the X-Akamai-G2O-Auth-Sign header.

The origin must use the key identifier passed in the X-Akamai-G2O-Auth-Data header to determine which secret key was used to create the X-Akamai-G2O-Auth-Sign header, and the request URL needs to be concatenated with the X-Akamai-G2O-Auth-Data header value. Then create an SHA256-HMAC encryption from that string using the secret key. Base64-encode the result, and compare it with the X-Akamai-G2O-Auth-Sign header value.

Multiple instances of Origin Characteristics

You can define the Origin Characteristics behavior for different use cases within a single property to simplify the configuration process. Apart from applying the Origin Characteristics behavior to all requests in the Default Rule, you can also include it in another rule and apply different match criteria to have separate requests use different origin characteristics optimizations.

For example, you can configure a single property to connect to separate origins that use different authentication methods.