GuideReference
Guide

Manage client certificates

Suggest Edits

Securely manage client certificates to establish a mutual authentication (mTLS) session between Akamai edge servers and your origin.

1. Prep

To create and use client certificates for an mTLS session, you need properties.

Get properties to link your client certificate to them:

  1. Export the properties to get a rule format and rule tree.

    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 import script (import.sh) included in the export to populate your Terraform state and prevent Terraform from attempting to recreate your assets.

2. Create a client certificate

Depending on the type of client certificate you want to use, you can create:

  • An Akamai-signed client certificate. Its lifecycle is entirely handled on the Akamai side.
  • A third-party signed client certificate. Its lifecycle is fully managed by your organization.

Akamai-signed client certificates

Use the akamai_mtlskeystore_client_certificate_akamai resource to create an Akamai-signed client certificate.

  1. In the resource, specify the required parameters, including:

    • Your certificate's name.
    • Your group and contract IDs.
    • Email addresses of users who get notified about any changes to or issues with the client certificate.
    • The type of security on the deployment network.
    • Your client certificate's deployment location.
    resource "akamai_mtlskeystore_client_certificate_akamai" "my-akamai-client-cert" {
  certificate_name    = "my-akamai-client-cert"
  contract_id         = "C-0N7RAC7"
  group_id            = 12345
  geography           = "CORE"
  key_algorithm       = "RSA"
  notification_emails = ["jsmith@example.com"]
  secure_network      = "STANDARD_TLS"
}

  2. Run terraform plan to check syntax and terraform apply to create your certificate.

    The certificate is automatically signed. Additionally, the first version of the certificate is created for you. The version initially has the DEPLOYMENT_PENDING status. It changes to DEPLOYED after 5–10 minutes. You can check your certificate version's deployment status with the akamai_mtlskeystore_client_certificate data source. The version has a default lifespan of three months. Once the version expires, it's automatically rotated. See the Rotate a client certificate version section for details.

    If it's the first Akamai-signed client certificate that you created on your account, mTLS Origin Keystore generates an account CA (certificate authority) certificate. It identifies the account CA and includes a public key and a digital signature based on the account CA's private key. To check the account CA certificate's details, run the akamai_mtlskeystore_account_ca_certificates data source.

    📘

    An account CA isn't created when you manage only third-party certificates on your account.

Third-party client certificates

Use the akamai_mtlskeystore_client_certificate_third_party resource to create a third-party certificate.

  1. In the resource, specify the required parameters, including:

    • Your certificate's name.
    • Your group and contract IDs.
    • Email addresses of users who get notified about any changes to or issues with the client certificate.
    • The type of security on a deployment network.
    • Your client certificate's deployment location.
    • The certificate's versions which are a map of user-defined identifiers as keys and client certificate versions as values. You can have up to five versions.
      If you provide two or more versions at once, they're sorted in ascending alphabetical order by key name (A to Z) after creating or updating the resource.
    resource "akamai_mtlskeystore_client_certificate_third_party" "my-third-party-client-cert" {
  certificate_name    = "my-third-party-client-cert"
  contract_id         = "C-0N7RAC7"
  group_id            = 12345
  geography           = "CORE"
  key_algorithm       = "RSA"
  notification_emails = ["jsmith@example.com"]
  secure_network      = "STANDARD_TLS"
  versions = {
    "my-client-cert-v1" = {},
    "my-client-cert-v2" = {}
  }
}

  2. Run terraform plan to check syntax and terraform apply to create your certificate. The client certificate's version is created with the AWAITING_SIGNED_CERTIFICATE status. You can check your certificate version's deployment status with the akamai_mtlskeystore_client_certificate data source.

  3. Send your client certificate ID in the akamai_mtlskeystore_client_certificate data source to retrieve a PEM-formatted certificate signing request (CSR) after creating or modifying your third-party client certificate. In the output block, you can either:

    • Reference the CSR for a given version identifier from the third-party client certificate resource to return that specific CSR. This applies only to non-aliased versions.

      data "akamai_mtlskeystore_client_certificate" "my-cert" {
  certificate_id = 123
}

output "my-csr" {
  value = akamai_mtlskeystore_client_certificate_third_party.my-third-party-client-cert.versions["my-client-cert-v1"].csr_block.csr
}

      Changes to Outputs:
  + my-csr = <<-EOT
        -----BEGIN CERTIFICATE REQUEST-----
        nMIID <sample - removed for readability> .... nMweq
        -----END CERTIFICATE REQUEST-----
  EOT

    • Reference the whole client certificate data source to return the certificate details, including the csr_block attribute that contains the CSR.

      data "akamai_mtlskeystore_client_certificate" "my-cert" {
  certificate_id = 123
}

output "my-cert" {
  value = data.akamai_mtlskeystore_client_certificate.my-cert
}

      Changes to Outputs:
  + my-cert = {
      + certificate_id                = 123
      + certificate_name              = "my-third-party-client-cert"
      + created_by                    = "jsmith@example.com"
      + created_date                  = "2025-07-01T10:24:56Z"
      + current                       = null
      + geography                     = "CORE"
      + include_associated_properties = null
      + key_algorithm                 = "RSA"
      + notification_emails           = [
          + "jsmith@example.com",
        ]
      + previous                      = null
      + secure_network                = "ENHANCED_TLS"
      + signer                        = "THIRD_PARTY"
      + subject                       = "/C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-third-party-client-cert/"
      + versions                      = [
          + {
              + certificate_block          = {
                  + certificate   = null
                  + key_algorithm = null
                  + trust_chain   = null
                }
              + certificate_submitted_by   = null
              + certificate_submitted_date = null
              + created_by                 = "jsmith@example.com"
              + created_date               = "2025-07-01T10:25:01Z"
              + csr_block                  = {
                  + csr           = <<-EOT
                        -----BEGIN CERTIFICATE REQUEST-----
                        nMIID <sample - removed for readability> .... nMweq
                        -----END CERTIFICATE REQUEST-----
                    EOT
                  + key_algorithm = "RSA"
                }
              + delete_requested_date      = null
              + expiry_date                = ""
              + issued_date                = ""
              + issuer                     = ""
              + key_algorithm              = "RSA"
              + elliptic_curve             = ""
              + key_size_in_bytes          = "2048"
              + properties                 = null
              + scheduled_delete_date      = null
              + signature_algorithm        = ""
              + status                     = "AWAITING_SIGNED_CERTIFICATE"
              + subject                    = ""
              + validation                 = {
                  + errors   = null
                  + warnings = null
                }
              + version                    = 1
              + version_guid               = "a123bcd-45ef-67g09-hi01-j234klm5no6789"
            },
        ]
    }

  4. Send the retrieved CSR to your chosen certificate authority (CA) for signing.

    👍

    Tip

    You can use the acme_certificate resource from the acme provider or the null_resource resource with the local-exec provisioner to sign your client certificate.

  5. Upload your signed certificate for deployment with the akamai_mtlskeystore_client_certificate_upload resource. The certificate must be in PEM format. If it was returned to you in a different format, convert it to PEM format using an SSL converter.

    resource "akamai_mtlskeystore_client_certificate_upload" "my-upload-cert" {
  client_certificate_id = akamai_mtlskeystore_client_certificate_third_party.my-third-party-client-cert.certificate_id
  version_number        = akamai_mtlskeystore_client_certificate_third_party.my-third-party-client-cert.versions["my-client-cert-v1"].version
  signed_certificate    = file("example_third_party-cert.pem")
  trust_chain           = file("example_trust_chain.pem")
  wait_for_deployment   = true
}

  6. Run terraform plan to check syntax and terraform apply to upload your certificate.

To rotate versions, see the Rotate a client certificate version section for details.

3. Update a property rule tree

Configure your property to point to the DEPLOYED client certificate version you want to use to establish an mTLS session.

  1. Add the mtls_origin_keystore behavior to your property rules' main.json file. For this behavior:

    • Set the enable attribute to true to enable the behavior.
    • In the client_certificate_version_guid attribute, assign your client certificate's version_guid to the property. This authenticates your origin with the edge server.
    • Set the auth_client_cert attribute to true to initiate the mTLS connection between the edge server and origin. If set to false, this initiates a standard TLS connection to the origin.
    data "akamai_property_rules_builder" "mtls_origin_keystore" {
  rules_v2025_02_18 {
    name     = "mTLS Edge Server to Origin"
    comments = "Ensures that the requests to your origin server come directly from the Akamai network."
    behavior {
      mtls_origin_keystore {
        enable                          = true
        client_certificate_version_guid = "a123bcd-45ef-67g09-hi01-j234klm5no6789"
        auth_client_cert                = true
      }
    }
  }
}

    {
  "behaviors": [
    {
      "name": "mtlsOriginKeystore",
      "options": {
        "enable": true,
        "clientCertificateVersionGuid": "a123bcd-45ef-67g09-hi01-j234klm5no6789",
        "authClientCert": true
      }
    }
  ]
}

    For the Akamai-signed client certificate type, the version GUID is automatically associated with the current_guid or previous_guid of the client certificate. This ensures that no updates to the rule tree are required after version rotation.

    For third-party client certificates, the version GUID is reused only for versions aliased as current or previous. For non-aliased versions, you need to manually update the rule tree to reflect the new version GUID whenever you update the client certificate version in the property. If the version isn't deployed, the property returns an error.

  2. 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 = "v2025_02_18"
  rules       = data.akamai_property_rules_builder.my-image-rules.json
  hostnames {
    cname_from             = "example.com"
    cname_to               = "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 = "v2025_02_18"
  rules       = data.akamai_property_rules_template.rules.json
  hostnames {
    cname_from             = "example.com"
    cname_to               = "example.com.edgekey.net"
    cert_provisioning_type = "DEFAULT"
  }
}

If you’ve configured a client certificate 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 client certificate to the property.

4. Activate a property

To activate the property containing your newly added client certificate, provide a value for the network, STAGING or PRODUCTION, and activate your property.

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
}

🚧

You can link your client certificate to a property that is activated on the staging network. However, to make the certificate work, the property must be activated on the production network.

Other actions

Update a client certificate

You can only update the certificate_name and notification_emails arguments in the Akamai-signed client certificate resource. For the third-party client certificate resource, apart from updating the certificate_name and notification_emails, you can also add or delete the entries in the versions argument.

If you try to update other fields, like contract_id, group_id, secure_network, or geography, your action gets blocked.

To have a client certificate with a different version, see the Rotate a client certificate version section for details.

Rotate a client certificate version

Use version rotation to keep your client certificates up-to-date and preserve their properties by extending their validity periods.

You can't rotate if a version is in the DEPLOYMENT_PENDING or DELETE_PENDING status. This applies to both the Akamai-signed and third-party signed client certificates.

Akamai-signed client certificates

For Akamai-signed client certificates, the first version is added automatically to the client certificate upon creation. The operation's response includes the current_guid attribute. This certificate type can have up to two versions. They're marked as current_guid and previous_guid, and their default lifespan is three months. Versions are automatically rotated by the server every time a given version expires.

Third-party client certificates

For third-party client certificates, the client certificate versions aren't automatically rotated. You need to do this manually. You can have up to five versions for this certificate type. Additionally, you can deploy multiple versions at the same time. This gives you flexibility when rotating your certificates, without disrupting your service.

To manually rotate versions:

  1. Define a new version in the versions argument of your akamai_mtlskeystore_client_certificate_third_party resource.
  2. Send your client certificate ID in the akamai_mtlskeystore_client_certificate data source to retrieve a CSR for your new version.
  3. Send the CSR to your chosen CA for signing.
  4. Upload your signed certificate for deployment with the akamai_mtlskeystore_client_certificate_upload resource.
  5. Update the mTLS Origin Keystore behavior on your property's rule tree by adding a newly generated version_guid to the clientCertificateVersionGuid argument.
  6. Activate your property with the new client certificate version.

If you reach the limit of five versions for your certificate and want to rotate, you need to delete a version before adding a new one.

Delete a client certificate or its versions

You can delete a specific client certificate version only if it isn't used in any property activated on the production network.

Your delete action gets blocked if you either:

  • Try to delete an Akamai-signed or third-party signed resource that still has a version assigned to a property.
  • Delete the last version on the certificate resource.

Delete a client certificate version

  1. Verify that the specific client certificate version you want to delete isn't assigned to a property. Run the akamai_mtlskeystore_client_certificate data source with the include_associated_properties argument set to true.

  2. Search for the version_guid you want to delete and check the properties attribute to verify if that version is used with any property. The properties argument lists only properties activated on the production network.

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

    Note: Since the version_guid is reused for Akamai-signed certificates, there is no need to deploy a new client certificate version. The system does this automatically for you. As a result, you don't have to update the property's rule tree.

  4. Once the version is unlinked from the property, remove it from the akamai_mtlskeystore_client_certificate_akamai or akamai_mtlskeystore_client_certificate_third_party resource and run terraform apply to apply the change.

  5. Verify if the version has been deleted:

    1. Run the akamai_mtlskeystore_client_certificate data source.
    2. If the version isn't present on the operation's response, it's been deleted.

Delete a client certificate

  1. When a client certificate has no versions that are used in any property active on production, run terraform destroy to delete the entire akamai_mtlskeystore_client_certificate_akamai or akamai_mtlskeystore_client_certificate_third_party resource.

    Performing this action removes the resource only from the state file. The certificate's status then changes to PENDING_DELETION and remains so for 24 hours. After this period, the resource is permanently deleted from the server. If you attempt to recreate the resource during this 24-hour window while the deletion is in progress, you receive an error.

    🚧

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

  2. Verify if the resource has been deleted:

    1. Run the akamai_mtlskeystore_client_certificates data source.
    2. If the client certificate isn't present on the operation's response, it's been deleted.

If necessary, you can cancel the deletion of the whole client certificate by reverting to a property version that uses a given client certificate. This is only possible while the certificate is in the PENDING_DELETION state, which lasts for 24 hours. However, we don't recommend doing this, as it may cause drift in your state file.

Import a client certificate

When working with an existing client certificate, you can import it with its related versions.

  1. Get a list of client certificates with the akamai_mtlskeystore_client_certificates data source to find the client certificate ID you want.

    data "akamai_mtlskeystore_client_certificates" "my-certs" {
}

output "my-certs" {
  value = data.akamai_mtlskeystore_client_certificates.my-certs
}

    Changes to Outputs:
  + my-certs = {
      + certificates = [
          + {
              + certificate_id      = 123
              + certificate_name    = "my-client-cert-1"
              + created_by          = "jsmith@example.com"
              + created_date        = "2025-07-01T10:24:56Z"
              + geography           = "CORE"
              + key_algorithm       = "RSA"
              + notification_emails = [
                  + "jsmith@example.com",
                ]
              + secure_network      = "ENHANCED_TLS"
              + signer              = "THIRD_PARTY"
              + subject             = "/C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-client-cert-1/"
            },
          + {
              + certificate_id      = 987
              + certificate_name    = "my-client-cert-2"
              + created_by          = "jsmith@example.com"
              + created_date        = "2025-07-01T10:21:34Z"
              + geography           = "CORE"
              + key_algorithm       = "RSA"
              + notification_emails = [
                  + "jsmith@example.com",
                ]
              + secure_network      = "STANDARD_TLS"
              + signer              = "AKAMAI"
              + subject             = "/C=US/O=Akamai Technologies, Inc./OU=23456 A-CCT1234 12345/CN=my-client-cert-2/"
            },
        ]
    }

  2. Export an existing client certificate and all its versions by passing the client certificate ID in the export-mtls-keystore command. You can also optionally specify the group and contract IDs.

    akamai terraform --edgerc {location-of-your-edgerc-file} --section {section-of-edgerc-to-use} export-mtls-keystore {"your-client-certificate-id"} {"your-group-id"} {"your-contract-id"}

    Note that the version identifiers in the third-party client certificate resource are exported in the {version-creation-date}_v{version-number} format, for example, 2025-07-01T10:25:01_v1.

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

Updated 4 days ago