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 akamai_mtlskeystore_client_certificate_akamai resource is waiting for deployment, which can take up to 5–10 minutes. Once it's processed, it indicates that the deployment has completed successfully. You can also verify 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
}

        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
}

       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.

    If you want to reuse the certificate's version GUID, ensure you always link to the current alias version to keep your certificate up to date. The current version will always point to the latest version where the certificate was uploaded.

  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-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" "my-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.my-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.

When you deploy a given version, it's included as a separate alias version record with a different version_guid. This record is additionally marked with the current or previous attribute in the akamai_mtlskeystore_client_certificate data source.

There can be up to two alias versions with the current and previous attributes at the same time. The most recently deployed or pending deployment version is labeled as current, and the previously deployed current version (if any) is marked as previous.

Here are a few things to consider about alias versions in third-party client certificates:

  • If you remove the current version when current and previous alias versions exist, the previous version becomes the new current.
  • The alias version_guid allows you to reuse it in your property without updating the rule tree after version rotation.

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

Delete a client certificate version

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

Deleting a specific certificate version is possible only for third-party client certificates.

For Akamai-signed client certificates, deleting a version isn’t allowed. The server automatically rotates versions or you can delete the entire certificate.

To delete a 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.

    Notes:

    • For Akamai-signed certificates, the version is automatically rotated and deployed. As a result, when linking a property to an alias version_guid of that certificate, no update to the property's rule tree is needed.
    • For third-party certificates, you need to manually deploy a new version, but linking the property to an alias version_guid doesn't require any changes to the property's rule tree.

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

    Deleting a version can leave gaps in the version sequence. For example, if you delete the latest or highest version number, the next version you create will skip that number.

  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

When deleting the client certificate resource, all its versions are also removed. Once the last version is successfully deleted, the entire certificate is removed from the server. However, in some cases, this final version deletion may occur instantly or be delayed. During the delay, the certificate enters a PENDING_DELETE state and may take up to 24 hours to fully take effect before being removed.

To delete the entire 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 DELETE_PENDING 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 you included your email in the notification_emails argument upon client certificate creation, you should receive a notification confirming the version deletion.

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 DELETE_PENDING 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
}

    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 about 1 month ago