Manage cloud origin access

Securely store and manage your cloud origin credentials. Use them as access keys to authenticate with your cloud provider during traffic routing to your origin.

Prep

To create and use access keys for authentication with your cloud provider, you need your cloud provider credentials and properties from the Property Manager API.

We currently support cloud origin authentication with Amazon Web Services (AWS) and Google Cloud Storage (GCS) in interoperability mode.

Create a key and its versions

Create an access key to store your cloud provider credentials. You'll add this key to your property configuration.

You can have 50 access keys per contract and two versions of each key at a time. Each version is considered in use when its deploymentStatus is pending activation, active, or pending deletion. If you already have two versions and need a new one, delete a version and then add a new one.

New key

When creating a new key, define its required settings in a variable as a hashtable, PSCustomObject, or JSON string. Then pass the variable in the -Body parameter of the New-CloudAccessKey command.

$myNewKey = @{
  accessKeyName = "MyAccessKey"
  contractId = "C-0N7RAC71"
  groupId = 12345
  authenticationMethod = "GOOG4_HMAC_SHA256"
  credentials = @{
    cloudAccessKeyId = "ABCDEFGHIJKL1"
    cloudSecretAccessKey = "aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z"
  }
  networkConfiguration = @{
    securityNetwork = "ENHANCED_TLS"
    additionalCdn = "CHINA_CDN"
  }
}

New-CloudAccessKey -Body $myNewKey

$myNewKey = '{
  "accessKeyName": "MyAccessKey",
  "contractId": "C-0N7RAC71",
  "groupId": 12345,
  "authenticationMethod": "GOOG4_HMAC_SHA256",
  "credentials": {
    "cloudAccessKeyId": "ABCDEFGHIJKL1",
    "cloudSecretAccessKey": "aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z"
  },
  "networkConfiguration": {
    "securityNetwork": "ENHANCED_TLS",
    "additionalCdn": "CHINA_CDN"
  }
}'

New-CloudAccessKey -Body $myNewKey

requestId retryAfter
--------- ----------
    12345          5

You can also define your access key settings in a JSON file, load the file into a variable, convert it into a PowerShell object, and pipe it to the command.

$myAccessKey = Get-Content ./myAccessKey.json | ConvertFrom-Json -Depth 100

$myAccessKey | New-CloudAccessKey

Key creation and activation can take up to 10 minutes, and during that time, you can't create an additional version.

To check your key's processing status, run the Get-CloudAccessKeyCreateRequest command by passing the request ID value from the previous command's output.

Get-CloudAccessKeyCreateRequest -RequestID 12345

requestId        : 12345
request          : @{contractId=C-0N7RAC7; groupId=12345; authenticationMethod=GOOG4_HMAC_SHA256; accessKeyName=MyAccessKey1; networkConfiguration=}
processingStatus : DONE
requestedBy      : jsmith
requestDate      : 7/11/2024 1:07:18 PM
accessKey        : @{accessKeyUid=12345; link=/cam/v1/access-keys/12345}
accessKeyVersion : @{accessKeyUid=12345; version=1; link=/cam/v1/access-keys/12345/versions/1}

New key version

Once you have a key created and activated with its first version, if needed, you can add another version. To do that, pass the access key ID and secret access key for that key in the New-CloudAccessKeyVersion command.

New-CloudAccessKeyVersion -AccessKeyUID 12345 -CloudAccessKeyID 'ZYXWVUTSRQPO2' -CloudSecretAccessKey 'ZyXwvUsrQPoNM/l9kJIH/Gf8eD765C'

requestId retryAfter
--------- ----------
    12345          5

Creating and activating a new key version takes about 10 minutes. To check your key version's processing status, run the Get-CloudAccessKeyVersionCreateRequest command by passing the request ID value from the previous command's output.

Get-CloudAccessKeyVersionCreateRequest -RequestID 12345

processingStatus requestedBy requestDate            accessKeyVersion
---------------- ----------- -----------            ----------------
DONE             jsmith      12/20/2024 10:14:58 AM @{accessKeyUid=12345; version=2; link=/cam/v1/access-keys/12345/versions/2}

Get a key and its versions

Get a key

To retrieve all existing keys available to you, run the Get-CloudAccessKey command. For a specific key, pass the access key UID in the command.

# Get all
Get-CloudAccessKey

# Get one
Get-CloudAccessKey -AccessKeyUID 12345

accessKeyUid         : 98765
groups               : {@{groupId=98765; groupName=my-group-1; contractIds=System.Object[]}}
authenticationMethod : AWS4_HMAC_SHA256
accessKeyName        : MyAccessKey2
note                 : 
createdTime          : 10/12/2024 11:30:30 AM
createdBy            : jasmith@akamai.com
networkConfiguration : @{additionalCdn=; securityNetwork=STANDARD_TLS}
latestVersion        : 2

accessKeyUid         : 12345
groups               : {@{groupId=12345; groupName=my-group-1; contractIds=System.Object[]}}
authenticationMethod : GOOG4_HMAC_SHA256
accessKeyName        : MyAccessKey1
note                 : 
createdTime          : 7/11/2024 1:07:18 PM
createdBy            : jsmith@akamai.com
networkConfiguration : @{additionalCdn=; securityNetwork=ENHANCED_TLS}
latestVersion        : 1

accessKeyUid         : 12345
groups               : {@{groupId=12345; groupName=my-group-1; contractIds=System.Object[]}}
authenticationMethod : GOOG4_HMAC_SHA256
accessKeyName        : MyAccessKey1
note                 : 
createdTime          : 7/11/2024 1:07:18 PM
createdBy            : jsmith@akamai.com
networkConfiguration : @{additionalCdn=; securityNetwork=STANDARD_TLS}
latestVersion        : 1

Get a version

To retrieve all versions for a given key, run the Get-CloudAccessKeyVersion by passing an access key UID. For a specific key version, provide the version number in the command.

# Get all
Get-CloudAccessKeyVersion -AccessKeyUID 12345

# Get one
Get-CloudAccessKeyVersion -AccessKeyUID 12345 -Version 1

accessKeyUid     : 98765
versionGuid      : z9y87x6w-54v3-21ut-srqp-98on7ml6kji
version          : 2
cloudAccessKeyId : ZYXWVUTSRQPO2
deploymentStatus : PENDING_ACTIVATION
createdBy        : jsmith
createdTime      : 15/12/2024 8:20:22 AM

accessKeyUid     : 12345
versionGuid      : 123a4567-891b-23cd-efgh-45678912345i
version          : 1
cloudAccessKeyId : ABCDEFGHIJKL1
deploymentStatus : ACTIVE
createdBy        : jsmith
createdTime      : 7/11/2024 1:07:18 PM

accessKeyUid     : 12345
versionGuid      : 123a4567-891b-23cd-efgh-45678912345i
version          : 1
cloudAccessKeyId : ABCDEFGHIJKL1
deploymentStatus : ACTIVE
createdBy        : jsmith
createdTime      : 7/11/2024 1:07:18 PM

Update a key

You can't change the key name, contract, group, network configuration, and authentication method in an existing key.

You can only provide new authentication credentials when adding access key versions. You can't edit them for existing versions.

If the key has two versions already, you can add another version only after you delete one of the versions.

Add property behaviors

Configure your property to point to the key version you want to use to sign your requests.

1. Get your property's rule tree as a JSON file. The output is a JSON file at your current location containing your rule's configurations.

   Command

   Get-PropertyRules -PropertyName 'my-property-1' -PropertyVersion 'latest' -OutputToFile
   

2. In the property's rule tree, add the appropriate behaviors and criteria for your key that fit your business needs. Use the reference to help you fill out the options for each. The reference includes these behaviors:

   • origin
   • originCharacteristics
   • contentCharacteristics
   • clientCharacteristics

   • restrictObjectCaching
   • cpCode
   • dynamicThroughtputOptimization
   • http3
   
   
   JSON

   {
     "accountId": "act_A-CCT1234",
     "contractId": "C-0N7RAC7",
     "groupId": "grp_12345",
     "ruleFormat": "v2024-05-31",
     "propertyId": "prp_12345",
     "propertyName": "my-property-1",
     "propertyVersion": 1,
     "rules": {
       "name": "default",
       "children": [],
       "behaviors": [
         {
           "name": "origin",
           "options": {
             "cacheKeyHostname": "ORIGIN_HOSTNAME",
             "compress": true,
             "enableTrueClientIp": true,
             "forwardHostHeader": "REQUEST_HOST_HEADER",
             "hostname": "example.com",
             "httpPort": 80,
             "httpsPort": 443,
             "ipVersion": "IPV4",
             "minTlsVersion": "DYNAMIC",
             "originCertificate": "",
             "originSni": true,
             "originType": "CUSTOMER",
             "ports": "",
             "tlsVersionTitle": "",
             "trueClientIpClientSetting": false,
             "trueClientIpHeader": "True-Client-IP",
             "verificationMode": "PLATFORM_SETTINGS"
           }
         },
         {
           "name": "originCharacteristics",
           "options": {
             "accessKeyEncryptedStorage": true,
             "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
             "authenticationMethodTitle": "",
             "country": "NORTH_AMERICA",
             "gcsAccessKeyVersionGuid": "123a4567-891b-23cd-efgh-45678912345i",
             "originLocationTitle": ""
           }
         },
         {
           "name": "contentCharacteristics",
           "options": {
             "catalogSize": "MEDIUM",
             "contentType": "USER_GENERATED",
             "objectSize": "LESS_THAN_1MB",
             "popularityDistribution": "LONG_TAIL"
           }
         },
         {
           "name": "clientCharacteristics",
           "options": {
             "country": "NORTH_AMERICA"
           }
         },
         {
           "name": "restrictObjectCaching",
           "options": {
             "maximumSize": ""
           }
         },
         {
           "name": "cpCode",
           "options": {
             "value": {
               "id": 12345,
               "description": "My CP code",
               "products": [
                 "Obj_Delivery"
               ],
               "createdDate": 1708523914000,
               "cpCodeLimits": null,
               "name": "My CP code"
             }
           }
         },
         {
           "name": "dynamicThroughtputOptimization",
           "options": {
             "enabled": true
           }
         },
         {
           "name": "http3",
           "options": {
             "enable": false
           }
         }
       ],
       "options": {
         "is_secure": false
       },
       "variables": []
     }
   }
   

3. Define the Origin Server behavior before the Origin Characteristics behavior to serve content from a third-party cloud-based origin.

4. Assign the key to the property using the Origin Characteristics behavior. For this behavior:

   1. If you're using Adaptive Media Delivery (AMD), Download Delivery, or Object Delivery, add the Origin Characteristics behavior to the default rule.
   2. Set the accessKeyEncryptedStorage argument to true to encrypt your credentials and store them in CAM. Otherwise, this behavior stores them unencrypted.
   3. In the awsAccessKeyVersionGuid or gcsAccessKeyVersionGuid argument, pass the key version ID.
   JSON

   {
     "name": "originCharacteristics",
     "options": {
       "accessKeyEncryptedStorage": true,
       "authenticationMethod": "GCS_HMAC_AUTHENTICATION",
       "authenticationMethodTitle": "",
       "country": "NORTH_AMERICA",
       "gcsAccessKeyVersionGuid": "123a4567-891b-23cd-efgh-45678912345i",
       "originLocationTitle": ""
     }
   }
   

   The AWS and GCS authentication methods in the Origin Characteristics behavior aren't compatible with the Chase Redirects behavior. If you're using one of these, the Chase Redirects behavior gets automatically disabled in your property.

5. Add your updated rules to your property, pointing to the appropriate file.

   Send your entire rule tree back. Rules not returned are removed from your property.

   Command

   Set-PropertyRules -PropertyName 'my-property-1' -PropertyVersion latest -InputFile './main.json' -VersionNotes 'Adding an access key'
   

   The output returns your rule tree along with any errors or warnings on upload.

If you’ve configured an access key for an ENHANCED_TLS network, the property also needs to use an Enhanced TLS edge hostname ending in edgekey.net. Otherwise, you won't be able to link the key to the property.

Activate a property

To activate the property containing your newly added access key, provide a value for the network, staging or production, and activate your property.

New-PropertyActivation -PropertyName 'my-property-1' -PropertyVersion 'latest' -Network 'Staging' -NotifyEmails 'jsmith@email.com'

activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

Delete a key version

You can delete a specific key version only if it isn’t used in any active property.

If you try to delete an access key version that is still assigned to a property, then your action gets blocked.

1. To see whether a specific key version is or isn't assigned to a property on a staging or production network, you can do this in one of these ways:

   1. Run the Get-CloudAccessKeyVersionProperties command.

      The operation doesn't return any output if the key version isn't assigned to any property.

      CommandOutput

      Get-CloudAccessKeyVersionProperties -AccessKeyUID 12345 -Version 1
      

      accessKeyUid      : 12345
      version           : 1
      propertyId        : prp_12345
      propertyName      : my-property-1
      productionVersion : 
      stagingVersion    : 4
      

   2. Or run the New-CloudAccessLookup command by passing the access key UID and key version number. This creates a property lookup ID.

      CommandOutput

      New-CloudAccessLookup -AccessKeyUID 12345 -Version 1
      

      lookupId retryAfter
      -------- ----------
      123456           10
      

      Then run the Get-CloudAccessLookup command with the lookup ID from the previous operation.

      CommandOutput

      Get-CloudAccessLookup -LookupID 123456
      

      lookupId lookupStatus properties
      -------- ------------ ----------
      123456   COMPLETE     {@{accessKeyUid=12345; version=1; propertyId=prp_12345; propertyName=my-property-1; productionVersion=; stagingVersion=4}}
      

2. If a key version is assigned to a property, unlink it from the property by updating the Origin characteristics behavior on the property's rule tree to use another version.

   There is a five-minute lookup lag before the key version gets unlinked from a property. It is so because the Property Manager API verifies if the key version isn't used in any active property.

3. Once the version is unlinked from the property, run the Remove-CloudAccessKeyVersion command.

   CommandOutput

   Remove-CloudAccessKeyVersion -AccessKeyUID 12345 -Version 1
   

   accessKeyUid     : 12345
   versionGuid      : 123a4567-891b-23cd-efgh-45678912345i
   version          : 1
   cloudAccessKeyId : ABCDEFGHIJKL1
   deploymentStatus : PENDING_DELETION
   createdBy        : jsmith
   createdTime      : 7/4/2024 8:20:22 AM
   

   Deleting a key version takes up to 5 minutes, and after that time, it's deleted from both staging and production networks.

   To check whether the version has been deleted, run the Get-CloudAccessKeyVersion command. If the version isn't present in the operation's response, it's been deleted.