GuideReference
Guide

Manage cloud origin access

Cloud Access Manager

Suggest Edits

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.

1. Prep

To create and use access keys for authentication with your cloud provider, you need your cloud provider credentials and properties.

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

Get properties to link your access key to them:

  1. Export the properties to get a rule format and rule tree you want to link an access key to. Optionally, add the --rules-as-hcl command flag to export the property rules as an akamai_property_rules_builder data source.

    akamai terraform --edgerc {location-of-your-edgerc-file} --section {section-of-edgerc-to-use} export-property --rules-as-hcl {"your-property-name"}

  2. Run the included import script to populate your Terraform state and prevent Terraform from attempting to recreate your assets.

2. Create or import a key

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 deployment_status is active, pending activation, or pending deletion. If you already have two versions and need a new one, delete a version and then add a new one.

Create new

When creating a key, you can set it up with either one set of credentials (A or B) or both sets of credentials (A and B).

Use the akamai_cloudaccess_key resource to create a new access key:

  1. Add your cloud provider access key ID and secret access key along with other security details.

  2. If using two sets of credentials:

    • Determine which access key is the primary one.

    • Set the primary_key flag to true in the appropriate credentials argument.

    • The cloud_access_key_id and cloud_secret_access_key need to be unique for each set of credentials. Otherwise, your action of creating the resource gets blocked.

     resource "akamai_cloudaccess_key" "my_access_key" {
   access_key_name       = "MyAccessKey"
   authentication_method = "AWS4_HMAC_SHA256"
   contract_id           = "C-0N7RAC7"
   credentials_a = {
     cloud_access_key_id     = "ABCDEFGHIJKL1"
     cloud_secret_access_key = "aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z"
     primary_key             = true
   }
   credentials_b = {
     cloud_access_key_id     = "ABCDEFGHIJKL2"
     cloud_secret_access_key = "AbcDefGhijKLm/n3opqrs/tW45X67yZ"
     primary_key             = false
   }
   group_id = 12345
   network_configuration = {
     security_network = "ENHANCED_TLS"
     additional_cdn   = "CHINA_CDN"
   }
 }

  3. Save your secret keys as variables and mark them as sensitive instead of hardcoding them directly in the resource. You can do this using one of these Terraform methods:

    • Set the secret keys as variables with their default values using a variables.tf file. Mark the secret keys as sensitive so that their values aren't displayed when you run terraform plan and apply. However, you can still view them from within the Terraform state.

        variable "secret_access_key_a" {
    type      = string
    sensitive = true
    default   = "aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z"
  }

  variable "secret_access_key_b" {
    type      = string
    sensitive = true
    default   = "AbcDefGhijKLm/n3opqrs/tW45X67yZ"
  }

      Then, within the akamai_cloudaccess_key resource block, pass these variables using var.<variable_name> format.

      resource "akamai_cloudaccess_key" "my_access_key" {
    access_key_name       = "MyAccessKey"
    authentication_method = "AWS4_HMAC_SHA256"
    contract_id           = "C-0N7RAC7"
    credentials_a = {
        cloud_access_key_id     = "ABCDEFGHIJKL1"
        cloud_secret_access_key = var.secret_access_key_a
        primary_key             = true
    }
    credentials_b = {
        cloud_access_key_id     = "ABCDEFGHIJKL2"
        cloud_secret_access_key = var.secret_access_key_b
        primary_key             = false
    }
    group_id = 12345
    network_configuration = {
        security_network = "ENHANCED_TLS"
        additional_cdn   = "CHINA_CDN"
    }
}

    • Create a <filename>.tfvars file in which you assign values to your variables.

      secret_access_key_a = "aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z"
secret_access_key_b = "AbcDefGhijKLm/n3opqrs/tW45X67yZ"

      Then in the terminal provide the path to this file using the -var-file CLI argument to load these values.

      terraform apply -var-file="terraform.tfvars"

      With this method, Terraform not only loads the values from the <filename>.tfvars file, but it also overwrites the default values assigned to these variables.

    • Set the Terraform environment variable using the TF_VAR_ prefix followed by the name of the declared variable.

      Defining variables this way is a fallback if variable values aren't found elsewhere.

      export TF_VAR_secret_access_key_a=aBcdeFgHiJKLM/n1oPQRS/Tw2xY345Z
export TF_VAR_secret_access_key_b=AbcDefGhijKLm/n3opqrs/tW45X67yZ

  4. Run terraform plan to check syntax and terraform apply to create and activate a key version. Activation can take up to 15 minutes, and during that time, you can't create an additional version.

    • After creating and activating a key version, the cloud_access_key_id and cloud_secret_access_key are visible in the state file and are unencrypted.
    • If the first version is already created, but the creation of the second version fails, then the akamai_cloudaccess_key resource is marked with the tainted status in the Terraform state file. To fix this, try to recreate the key by applying your original configuration. As a result, Terraform first removes any leftover configuration and then recreates the resource.

  5. Once the key activation is complete, the key's version_guid is passed to the primary_guid based on the primary_key flag. Use the primary_guid to assign the primary key version to the property on both staging and production networks.

    The primary_guid attribute is empty if you don't set the primary_key flag to true on any of the key versions.

You can set a primary access key to connect all your services. To rotate your key or when the key has been compromised, you can temporarily use an additional key version (version_guid) in your services. To retrieve the key's version_guid, run the akamai_cloudaccess_key_versions data source.

Import a key

  1. Get a list of your access keys to find the key UID you want.

     data "akamai_cloudaccess_keys" "my_access_keys" {
 }

 output "my_access_keys" {
   value = data.akamai_cloudaccess_keys.my_access_keys
 }

    Changes to Outputs:
  + my_access_keys = {
      + access_keys = [
          + {
              + access_key_name       = "MyAccessKey1"
              + access_key_uid        = 12345
              + authentication_method = "AWS4_HMAC_SHA256"
              + created_by            = "jsmith@example.com"
              + created_time          = "2024-04-13T16:34:47.231623Z"
              + groups                = [
                  + {
                      + contract_ids = [
                          + "C-0N7RAC7",
                        ]
                      + group_id      = 123456
                      + group_name    = "my-group-name-1"
                    },
                  + {
                      + contract_ids = [
                          + "C-0N7RAC7",
                        ]
                      + group_id      = 987654
                      + group_name    = "my-group-name-2"
                    },
                ]
              + latest_version        = 1
              + network_configuration = {
                  + additional_cdn   = "RUSSIA_CDN"
                  + security_network = "STANDARD_TLS"
                }
            },
          + {
              + access_key_name       = "MyAccessKey2"
              + access_key_uid        = 987654
              + authentication_method = "GOOG4_HMAC_SHA256"
              + created_by            = "jsmith@email.com"
              + created_time          = "2024-05-04T13:29:21.650042Z"
              + groups                = [
                  + {
                      + contract_ids = [
                          + "C-0N7RAC7",
                        ]
                      + group_id      = 123456
                      + group_name    = "my-group-name-1"
                    },
                  + {
                      + contract_ids = [
                          + "C-0N7RAC7",
                        ]
                      + group_id      = 987654
                      + group_name    = "my-group-name-2"
                    },
                ]
              + latest_version        = 1
              + network_configuration = {
                  + additional_cdn   = "CHINA_CDN"
                  + security_network = "ENCHANCED_TLS"
                }
            },
        ]
    }

  2. To export an existing key and all its versions, use the access key UID you want as a value for the export-cloudaccess argument of the akamai CLI command.

    When using the --group_id and --contract_id command flags, don't add the grp_ and ctr_ prefixes to these flags' values. Otherwise, you get an error.

    akamai terraform --edgerc {location-of-your-edgerc-file} --section {section-of-edgerc-to-use} export-cloudaccess --group_id {"your-group-id"} --contract_id {"your-contract-id"} {"your-access-key-uid"}

  3. Run the included import script to populate your Terraform state and prevent Terraform from attempting to recreate your assets.

    By default, Terraform imports an older key version to credentials_a and the most recent version to credentials_b.

  4. When running the script, you'll be prompted to manually provide the values for your secret keys. This is because these values can't be retrieved from the server. To avoid that prompt, first define your secret keys. See step 3 of the Create new section for details on several ways you can use to add your secret keys to variables.

  5. If using both sets of credentials, set the primary_key flag to true for a key version you want to assign as primary on a property.

Update a key

You can update only the access_key_name argument directly in the created akamai_cloudaccess_key resource.

If you try to update other fields in the resource, such as authentication_method, contract_id, group_id, or network_configuration, then your action gets blocked.

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

To have a key with a different set of credentials, see the Rotate key section for details.

3. Add property behaviors

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

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


    data "akamai_property_rules_builder" "my-property-rule-default" {
  rules_v2023_05_30 {
    name      = "default"
    is_secure = false
    behavior {
      origin {
        cache_key_hostname            = "ORIGIN_HOSTNAME"
        compress                      = true
        enable_true_client_ip         = true
        forward_host_header           = "REQUEST_HOST_HEADER"
        hostname                      = "1abcd2e34-www.example.com"
        http_port                     = 80
        https_port                    = 443
        ip_version                    = "IPV4"
        origin_certificate            = ""
        origin_sni                    = true
        origin_type                   = "CUSTOMER"
        ports                         = ""
        true_client_ip_client_setting = false
        true_client_ip_header         = "True-Client-IP"
        verification_mode             = "PLATFORM_SETTINGS"
      }
    }
    behavior {
      origin_characteristics {
        access_key_encrypted_storage = true
        authentication_method        = "AWS"
        authentication_method_title  = ""
        aws_access_key_version_guid  = akamai_cloudaccess_key.my_access_key.primary_guid
        aws_host                     = ""
        aws_region                   = "Asia"
        aws_service                  = "s3"
        country                      = "UNKNOWN"
      }
    }
    behavior {
      content_characteristics {
        catalog_size            = "UNKNOWN"
        content_type            = "UNKNOWN"
        object_size             = "UNKNOWN"
        popularity_distribution = "UNKNOWN"
      }
    }
    behavior {
      client_characteristics {
        country = "UNKNOWN"
      }
    }
    behavior {
      restrict_object_caching {
        maximum_size = ""
      }
    }
    behavior {
      cp_code {
        value {
          created_date = 1708523914000
          description  = "My CP code"
          id           = 1234567
          name         = "MyCPCode"
          products     = ["Obj_Delivery", ]
        }
      }
    }
    behavior {
      dynamic_throughtput_optimization {
        enabled = true
      }
    }
    behavior {
      http2 {
        enable = false
      }
    }
  }
}

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

  3. 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. If you store your rules in the akamai_property_rules_builder data source, then, in the aws_access_key_version_guid or gcs_access_key_version_guid argument, declaratively pass:

      • The primary_guid for the primary key version.

      • Or the version_guid for a different version than the primary one.

        behavior {
    origin_characteristics {
      access_key_encrypted_storage = true
      authentication_method        = "AWS"
      authentication_method_title  = ""
      aws_access_key_version_guid  = akamai_cloudaccess_key.my_access_key.primary_guid
      aws_host                     = ""
      aws_region                   = "Asia"
      aws_service                  = "s3"
      country                      = "UNKNOWN"
    }
}

        behavior {
    origin_characteristics {
      access_key_encrypted_storage = true
      authentication_method        = "AWS"
      authentication_method_title  = ""
      aws_access_key_version_guid  = akamai_cloudaccess_key.my_access_key.credentials_b.version_guid
      aws_host                     = ""
      aws_region                   = "Asia"
      aws_service                  = "s3"
      country                      = "UNKNOWN"
    }
}

    4. If you store your rules in a JSON file:

      • First create a variable in your akamai_property_rules_template data source to store the key's primary_guid or version_guid.

          data "akamai_property_rules_template" "rules" {
    template_file = abspath("${path.module}/property-snippets/main.json")
    variables {
        name  = "primary_guid"
        value = akamai_cloudaccess_key.my_access_key.primary_guid
        type  = "string"
    }
    variables {
        name  = "version_guid"
        value = akamai_cloudaccess_key.my_access_key.credentials_b.version_guid
        type  = "string"
    }
  }

      • Then pass the defined variable to the awsAccessKeyVersionGuid or gcsAccessKeyVersionGuid argument in your JSON file.

          {
    "name": "originCharacteristics",
    "options": {
        "accessKeyEncryptedStorage": true,
        "authenticationMethod": "AWS",
        "authenticationMethodTitle": "",
        "awsAccessKeyVersionGuid": "${env.primary_guid}",
        "awsHost": "",
        "awsRegion": "Asia",
        "awsService": "s3",
        "country": "UNKNOWN"
    }
  },

🚧

Incompatibility with Chase Characteristics

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.

  1. Add your updated rules to your property:

    1. If you store your rules in the akamai_property_rules_builder data source, point to that data source in your property.

      resource "akamai_property" "my_property" {
  name        = "MyProperty"
  product_id  = "prd_Object_Delivery"
  contract_id = "C-0N7RAC7"
  group_id    = "12345"
  rule_format = "v2023-05-30"
  rules       = data.akamai_property_rules_builder.my-property-rule-default.json
  depends_on  = akamai_property_include_activation.id
  hostnames {
    cname_from             = "my_property_example.com"
    cname_to               = "my_property_example.com.edgekey.net"
    cert_provisioning_type = "DEFAULT"
  }
}

    2. If you store your rules in JSON format, point to the rules in the akamai_property_rules_template data source and reference it in your property.

      data "akamai_property_rules_template" "rules" {
  template_file = abspath("${path.module}/property-snippets/main.json")
}

resource "akamai_property" "my_property" {
  name        = "MyProperty"
  product_id  = "prd_Object_Delivery"
  contract_id = "C-0N7RAC7"
  group_id    = "12345"
  rule_format = "v2023-05-30"
  rules       = data.akamai_property_rules_template.rules.json
  depends_on  = akamai_property_include_activation.id
  hostnames {
    cname_from             = "my_property_example.com"
    cname_to               = "my_property_example.com.edgekey.net"
    cert_provisioning_type = "DEFAULT"
  }
}

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.

4. Activate a property

Activate your property on a network.

resource "akamai_property_activation" "my_staging_activation" {
  property_id                    = "prp_12345"
  contact                        = ["jsmith@example.com"]
  version                        = akamai_property.my_property.latest_version
  network                        = "STAGING"
  note                           = "Activating my property on staging"
  auto_acknowledge_rule_warnings = false
}

Rotate a key

Use key rotation to update an access key version's ID and secret without changing other details. You can update a key name and rotate, create, or delete an access key version simultaneously.

However, when you try to rotate a key and at the same time update a contract, group, authentication method, or network configuration, then your action gets blocked.

  1. Rotate your key using one of these methods:

    MethodSteps
    Swap primary_key value
    1. On the existing akamai_cloudaccess_key resource with two key versions, change the primary_key flag to true on one of the credentials arguments (A or B), without deleting any version.
    Change credential set
    1. On the existing akamai_cloudaccess_key resource with one key version, delete that version, for example, credentials_a from a key.
    2. Create a new set of credentials_a and set its primary_key flag to true.
    Rotate from old version to new
    1. On the existing akamai_cloudaccess_key resource with two key versions, delete a version, for example, credentials_b from a key.
    2. Create a new version of credentials_b.
    3. If you don't want to use an older version (credentials_a) in any property as primary anymore, first unlink it from that property and set its primary_key flag to false.
    4. On the newly created key version (credentials_b), set the primary_key flag to true to use it as primary with any property.

  2. Once you rotate your key with one of these methods and want to use it in your property, update the Origin Characteristics behavior on your property rule tree by adding the newly generated primary_guid to the awsAccessKeyVersionGuid or gcsAccessKeyVersionGuid argument.

  3. Activate your property with the new key version.

Delete a key or its versions

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

If you try to delete an akamai_cloudaccess_key resource that still has one of the versions assigned to a property, then your action gets blocked.

Delete a key version

  1. Verify if a specific key version isn't assigned to a property. To do that, run the akamai_cloudaccess_key_properties data source and search for the access_key_uid and access_key_version of the key you want to delete.

  2. If a 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, remove it from the akamai_cloudaccess_key resource and run terraform apply to apply the change.

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

  4. Verify if the version has been deleted:

    1. Run the akamai_cloudaccess_key_versions data source.

    2. If the version isn't present on the operation's response, it's been deleted.

Delete a key

When a key has no versions that are used in any active property:

  1. Run terraform destroy to delete the entire akamai_cloudaccess_key resource.

    🚧

    If your property and property activation are in the same configuration file or directory as the access key, the terraform destroy command may lead to downtime.

  2. Verify if the resource has been deleted:

    a. Run the akamai_cloudaccess_keys data source.

    b. If the key isn't present on the operation's response, it's been deleted.

Updated 9 days ago