From 12228425a79f56c8489749624e5acb5f43c77d3a Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Fri, 22 May 2026 10:36:26 -0600 Subject: [PATCH 1/5] docs(lets-encrypt): add Azure managed identity DNS-01 guidance --- .../targets/lets-encrypt.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/Secrets Management/targets/lets-encrypt.md b/docs/Secrets Management/targets/lets-encrypt.md index a3e5b4ae8..ea93a1e5e 100644 --- a/docs/Secrets Management/targets/lets-encrypt.md +++ b/docs/Secrets Management/targets/lets-encrypt.md @@ -149,6 +149,41 @@ Required permissions by provider: * This role includes `Microsoft.Network/dnsZones/*` (manage DNS zones and record sets). * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) +### Azure DNS with Managed Identity (Gateway Cloud Identity) + +If the Gateway runs on Azure, an Azure target can use the Gateway cloud identity instead of a client secret. This is useful when certificate flows need DNS-01 validation in Azure DNS and teams want to avoid storing long-lived Azure credentials. + +1. Create an Azure target that uses the Gateway cloud identity: + +```shell +akeyless target create azure \ +--name \ +--use-gw-cloud-identity \ +--subscription-id \ +--resource-group-name +``` + +1. Create the Let's Encrypt target with DNS challenge and the Azure DNS target reference: + +```shell +akeyless target create lets-encrypt \ +--name \ +--email \ +--acme-challenge dns \ +--dns-target-creds \ +--resource-group +``` + +### Troubleshooting Azure DNS challenge flows + +If certificate issuance fails during DNS challenge validation, validate the following: + +* The Gateway is running on an Azure resource with managed identity enabled. +* The managed identity used by the Gateway has **DNS Zone Contributor** on the relevant DNS zone. +* The `resource-group` value in the Let's Encrypt target matches the resource group that contains the DNS zone. +* The domain requested in the certificate is hosted in the Azure DNS zone managed by the target. +* The Gateway can reach Azure DNS APIs over the network. + > ℹ️ **Note (Least Privilege):** > > Scope permissions to only the DNS zones and record operations required for certificate validation. From 7559cf31d0ca155c8b355d2c59295d4d34ddee32 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Fri, 22 May 2026 10:43:10 -0600 Subject: [PATCH 2/5] docs(lets-encrypt): expand cloud identity examples and improve guide --- .../targets/lets-encrypt.md | 73 ++++++++++++++----- 1 file changed, 55 insertions(+), 18 deletions(-) diff --git a/docs/Secrets Management/targets/lets-encrypt.md b/docs/Secrets Management/targets/lets-encrypt.md index ea93a1e5e..96bb0d2aa 100644 --- a/docs/Secrets Management/targets/lets-encrypt.md +++ b/docs/Secrets Management/targets/lets-encrypt.md @@ -27,6 +27,13 @@ To prove domain ownership, the Akeyless integration supports the following valid * **HTTP validation**: Ownership is proven by hosting a challenge file at `http:///.well-known/acme-challenge/` and returning the expected value during validation. +## Before You Begin + +* Ensure an [Akeyless Gateway](https://docs.akeyless.io/docs/gateway-overview) is deployed and reachable. +* For DNS challenge flows, create the DNS provider target before creating the Let's Encrypt target. +* Confirm that the DNS target has permissions to manage TXT records in the relevant zone. +* Use the ACME `staging` environment for initial validation before switching to `production`. + ## Create a Let's Encrypt Target with the CLI To create a Let's Encrypt target with the CLI, use one of the following examples based on the challenge method and DNS provider: @@ -112,7 +119,7 @@ Where: * **Challenge Type**: Either **HTTP** or **DNS**. -* **DNS Provider**: Either **AWS**, **GCP**, **Azure**, or **Cloudflare** (relevant only if **Challenge Type** is **DNS**). +* **DNS Provider**: Either **AWS**, **GCP**, or **Azure** (relevant only if **Challenge Type** is **DNS**). * **Target**: Select a target that contains the DNS provider credentials (relevant only if **Challenge Type** is **DNS**). @@ -122,10 +129,12 @@ Where: * **GCP Project**: GCP Cloud DNS project ID. Optional when **DNS Provider** is **GCP**. -* **DNS Zone**: Cloudflare DNS zone name. Relevant only when **DNS Provider** is **Cloudflare**. - * **Timeout**: Challenge validation timeout in seconds. Default is 300 seconds (5 minutes). +> ℹ️ **Note:** +> +> Cloudflare DNS configuration for Let's Encrypt is available through the CLI flow. + 1. Click Finish. ## DNS Provider Permissions for DNS-01 @@ -149,23 +158,34 @@ Required permissions by provider: * This role includes `Microsoft.Network/dnsZones/*` (manage DNS zones and record sets). * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) -### Azure DNS with Managed Identity (Gateway Cloud Identity) +### Gateway Cloud Identity Examples for DNS-01 -If the Gateway runs on Azure, an Azure target can use the Gateway cloud identity instead of a client secret. This is useful when certificate flows need DNS-01 validation in Azure DNS and teams want to avoid storing long-lived Azure credentials. +The following examples show how to use Gateway cloud identity with DNS challenge flows for AWS, Azure, and GCP. -1. Create an Azure target that uses the Gateway cloud identity: +```shell AWS +# Create the DNS provider target with Gateway cloud identity +akeyless target create aws \ +--name \ +--use-gw-cloud-identity \ +--region -```shell +# Create the Let's Encrypt target that references the DNS target +akeyless target create lets-encrypt \ +--name \ +--email \ +--acme-challenge dns \ +--dns-target-creds \ +--hosted-zone +``` +```shell Azure +# Create the DNS provider target with Gateway cloud identity akeyless target create azure \ --name \ ---use-gw-cloud-identity \ +--connection-type cloud-identity \ --subscription-id \ --resource-group-name -``` - -1. Create the Let's Encrypt target with DNS challenge and the Azure DNS target reference: -```shell +# Create the Let's Encrypt target that references the DNS target akeyless target create lets-encrypt \ --name \ --email \ @@ -173,16 +193,33 @@ akeyless target create lets-encrypt \ --dns-target-creds \ --resource-group ``` +```shell GCP +# Create the DNS provider target with Gateway cloud identity +akeyless target create gcp \ +--name \ +--use-gw-cloud-identity + +# Create the Let's Encrypt target that references the DNS target +akeyless target create lets-encrypt \ +--name \ +--email \ +--acme-challenge dns \ +--dns-target-creds \ +--gcp-project +``` -### Troubleshooting Azure DNS challenge flows +### Troubleshoot DNS challenge flows If certificate issuance fails during DNS challenge validation, validate the following: -* The Gateway is running on an Azure resource with managed identity enabled. -* The managed identity used by the Gateway has **DNS Zone Contributor** on the relevant DNS zone. -* The `resource-group` value in the Let's Encrypt target matches the resource group that contains the DNS zone. -* The domain requested in the certificate is hosted in the Azure DNS zone managed by the target. -* The Gateway can reach Azure DNS APIs over the network. +* The `dns-target-creds` target exists and is configured for the expected provider. +* The DNS challenge field for the selected provider is set correctly: + * AWS: `hosted-zone` + * Azure: `resource-group` + * GCP: `gcp-project` (when project ID cannot be derived automatically) +* The domain requested in the certificate is hosted in the DNS zone managed by the provider target. +* The Gateway has network access to the provider DNS APIs. +* The identity used by the provider target has permissions to create and update TXT records for ACME validation. > ℹ️ **Note (Least Privilege):** > From ec7385637fbc02c0f6bb74bde5005dba6232bd16 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Fri, 22 May 2026 10:44:37 -0600 Subject: [PATCH 3/5] docs(lets-encrypt): improve page information architecture --- .../targets/lets-encrypt.md | 96 +++++++++---------- 1 file changed, 46 insertions(+), 50 deletions(-) diff --git a/docs/Secrets Management/targets/lets-encrypt.md b/docs/Secrets Management/targets/lets-encrypt.md index 96bb0d2aa..0fbf5de08 100644 --- a/docs/Secrets Management/targets/lets-encrypt.md +++ b/docs/Secrets Management/targets/lets-encrypt.md @@ -34,9 +34,22 @@ To prove domain ownership, the Akeyless integration supports the following valid * Confirm that the DNS target has permissions to manage TXT records in the relevant zone. * Use the ACME `staging` environment for initial validation before switching to `production`. -## Create a Let's Encrypt Target with the CLI +## Choose a Validation Method -To create a Let's Encrypt target with the CLI, use one of the following examples based on the challenge method and DNS provider: +Choose one of the supported challenge types based on the DNS and web access model in your environment: + +* **DNS challenge (`dns`)**: Recommended when DNS automation is available. This method requires a DNS provider target and provider-specific DNS parameters. +* **HTTP challenge (`http`)**: Recommended when a challenge file can be served from `/.well-known/acme-challenge/` on the requested domain. + +Use the sections below to configure the target and complete certificate issuance for your selected method. + +## Configure the Let's Encrypt Target + +### Use the CLI + +Use the following examples based on challenge type and DNS provider. + +#### DNS challenge examples ```shell DNS with AWS akeyless target create lets-encrypt \ @@ -70,14 +83,17 @@ akeyless target create lets-encrypt \ --dns-target-creds \ --dns-zone ``` -```shell HTTP + +#### HTTP challenge example + +```shell akeyless target create lets-encrypt \ --name \ --email \ --acme-challenge http ``` -Where: +#### Key CLI flags * `name`: A unique name for the target. The name can include a path to a virtual folder by using slash `/` separators. If the folder does not exist, Akeyless creates it with the target. @@ -103,7 +119,7 @@ Where: [View the complete list of parameters for this command.](https://docs.akeyless.io/docs/cli-ref-targets#lets-encrypt) -## Create a Let's Encrypt Target in the Console +### Use the Console 1. Log in to the Akeyless Console, and go to **Targets**, then **New**, then **Certificate Automation (Let's Encrypt)**. @@ -137,30 +153,13 @@ Where: 1. Click Finish. -## DNS Provider Permissions for DNS-01 +## Configure DNS Provider Authentication (Optional) -When using `dns` challenge validation, the cloud target referenced by `dns-target-creds` must have permission to create and update ACME TXT records in the relevant DNS zone. +For DNS challenge flows, a provider target can use Gateway cloud identity instead of static credentials. -Required permissions by provider: +### Gateway Cloud Identity Examples -* **AWS Route 53** - * **Required for DNS-01 record changes**: `route53:ChangeResourceRecordSets` on the target hosted zone. - * **Common read permissions** (if zone lookup or record inspection is needed): `route53:GetHostedZone`, `route53:ListHostedZonesByName`, and `route53:ListResourceRecordSets`. - * Reference: [Actions, resources, and condition keys for Amazon Route 53](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonroute53.html) and [Permissions required to use the Route 53 API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html) - -* **GCP Cloud DNS** - * **Required for DNS-01 record changes**: `dns.changes.create` and the relevant record set permission (`dns.resourceRecordSets.create`, `dns.resourceRecordSets.update`, and/or `dns.resourceRecordSets.delete`). - * **Common read permissions**: `dns.managedZones.get`, `dns.managedZones.list`, `dns.resourceRecordSets.get`, and `dns.resourceRecordSets.list`. - * Reference: [Access control with IAM](https://docs.cloud.google.com/dns/docs/access-control) - -* **Azure DNS** - * **Recommended built-in role**: **DNS Zone Contributor** at the DNS zone scope. - * This role includes `Microsoft.Network/dnsZones/*` (manage DNS zones and record sets). - * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) - -### Gateway Cloud Identity Examples for DNS-01 - -The following examples show how to use Gateway cloud identity with DNS challenge flows for AWS, Azure, and GCP. +The following examples show how to create DNS provider targets with Gateway cloud identity for AWS, Azure, and GCP. ```shell AWS # Create the DNS provider target with Gateway cloud identity @@ -168,14 +167,6 @@ akeyless target create aws \ --name \ --use-gw-cloud-identity \ --region - -# Create the Let's Encrypt target that references the DNS target -akeyless target create lets-encrypt \ ---name \ ---email \ ---acme-challenge dns \ ---dns-target-creds \ ---hosted-zone ``` ```shell Azure # Create the DNS provider target with Gateway cloud identity @@ -184,30 +175,35 @@ akeyless target create azure \ --connection-type cloud-identity \ --subscription-id \ --resource-group-name - -# Create the Let's Encrypt target that references the DNS target -akeyless target create lets-encrypt \ ---name \ ---email \ ---acme-challenge dns \ ---dns-target-creds \ ---resource-group ``` ```shell GCP # Create the DNS provider target with Gateway cloud identity akeyless target create gcp \ --name \ --use-gw-cloud-identity - -# Create the Let's Encrypt target that references the DNS target -akeyless target create lets-encrypt \ ---name \ ---email \ ---acme-challenge dns \ ---dns-target-creds \ ---gcp-project ``` +## DNS Provider Permissions for DNS-01 + +When using `dns` challenge validation, the cloud target referenced by `dns-target-creds` must have permission to create and update ACME TXT records in the relevant DNS zone. + +Required permissions by provider: + +* **AWS Route 53** + * **Required for DNS-01 record changes**: `route53:ChangeResourceRecordSets` on the target hosted zone. + * **Common read permissions** (if zone lookup or record inspection is needed): `route53:GetHostedZone`, `route53:ListHostedZonesByName`, and `route53:ListResourceRecordSets`. + * Reference: [Actions, resources, and condition keys for Amazon Route 53](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonroute53.html) and [Permissions required to use the Route 53 API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html) + +* **GCP Cloud DNS** + * **Required for DNS-01 record changes**: `dns.changes.create` and the relevant record set permission (`dns.resourceRecordSets.create`, `dns.resourceRecordSets.update`, and/or `dns.resourceRecordSets.delete`). + * **Common read permissions**: `dns.managedZones.get`, `dns.managedZones.list`, `dns.resourceRecordSets.get`, and `dns.resourceRecordSets.list`. + * Reference: [Access control with IAM](https://docs.cloud.google.com/dns/docs/access-control) + +* **Azure DNS** + * **Recommended built-in role**: **DNS Zone Contributor** at the DNS zone scope. + * This role includes `Microsoft.Network/dnsZones/*` (manage DNS zones and record sets). + * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) + ### Troubleshoot DNS challenge flows If certificate issuance fails during DNS challenge validation, validate the following: From b46106806d8d13fa0e5439cd6faf2e289900ffc4 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Fri, 22 May 2026 10:48:03 -0600 Subject: [PATCH 4/5] docs(targets): improve IA for DigiCert and Google CA pages --- .../targets/digicert-target.md | 154 ++++++++++++------ .../targets/google-ca-target.md | 97 +++++++++-- 2 files changed, 188 insertions(+), 63 deletions(-) diff --git a/docs/Secrets Management/targets/digicert-target.md b/docs/Secrets Management/targets/digicert-target.md index 72f1843d1..3d6df0a74 100644 --- a/docs/Secrets Management/targets/digicert-target.md +++ b/docs/Secrets Management/targets/digicert-target.md @@ -5,19 +5,30 @@ hidden: false metadata: robots: index --- -The [Digicert](https://www.digicert.com/) Target enables the use of **Digicert** as a Public Certificate Authority (CA) with an Akeyless [PKI Issuer](https://docs.akeyless.io/docs/ssh-and-pkitls-certificates). +The [DigiCert](https://www.digicert.com/) Target enables the use of **DigiCert** as a public Certificate Authority (CA) with an Akeyless [PKI Issuer](https://docs.akeyless.io/docs/ssh-and-pkitls-certificates). -With a public CA, Akeyless cannot access the private key that signs certificates. Akeyless validates certificate issuance requests by connecting to **Digicert** through the [Akeyless Gateway](https://docs.akeyless.io/docs/gateway-overview). +With a public CA, Akeyless cannot access the private key that signs certificates. Akeyless validates certificate issuance requests by connecting to **DigiCert** through the [Akeyless Gateway](https://docs.akeyless.io/docs/gateway-overview). -The **DigiCert** integration uses an [ACME Client (v2)](https://datatracker.ietf.org/doc/html/rfc8555). +The DigiCert integration uses an [ACME Client (v2)](https://datatracker.ietf.org/doc/html/rfc8555). -To prove domain ownership, the Akeyless integration supports DNS validation: +## Before You Begin -* **DNS validation**: Ownership is proven by adding a DNS TXT record. This requires the domain to be managed in a supported DNS provider's hosted zone (for example, Amazon Route 53, GCP Cloud DNS, or Azure DNS). +* Ensure an [Akeyless Gateway](https://docs.akeyless.io/docs/gateway-overview) is deployed and reachable. +* Create a DNS provider target before creating the DigiCert target. +* Confirm that the DNS target has permissions to manage TXT records in the relevant zone. +* Collect DigiCert external account binding (EAB) values: `eab-key-id` and `eab-hmac-key`. -## Create a Digicert Target with the CLI +## Validation Method -To create a Digicert target with the CLI, use one of the following examples based on the challenge method and DNS provider: +DigiCert public CA integration in Akeyless uses DNS challenge (`dns`) for domain ownership validation. + +## Configure the DigiCert Target + +### Use the CLI + +Use one of the following DNS challenge examples by provider. + +#### DNS challenge examples ```shell DNS with AWS akeyless target create digicert \ @@ -25,7 +36,7 @@ akeyless target create digicert \ --digicert-url \ --email \ --eab-key-id \ ---eab-hmac-key \ +--eab-hmac-key \ --acme-challenge dns \ --dns-target-creds \ --hosted-zone @@ -36,7 +47,7 @@ akeyless target create digicert \ --digicert-url \ --email \ --eab-key-id \ ---eab-hmac-key \ +--eab-hmac-key \ --acme-challenge dns \ --dns-target-creds \ --gcp-project @@ -47,7 +58,7 @@ akeyless target create digicert \ --digicert-url \ --email \ --eab-key-id \ ---eab-hmac-key \ +--eab-hmac-key \ --acme-challenge dns \ --dns-target-creds \ --resource-group @@ -64,62 +75,103 @@ akeyless target create digicert \ --dns-zone ``` -Where: +#### Key CLI flags * `name`: A unique name for the target. The name can include a path to a virtual folder by using slash `/` separators. If the folder does not exist, Akeyless creates it with the target. - -* `digicert-url`: Use this when you want to select the ACME environment explicitly. Supported values are `production` (default) and `staging`. - +* `digicert-url`: DigiCert ACME environment selector. Supported values are `us-production`, `eu-production`, `us-demo`, and `eu-demo`. * `email`: Email address used for ACME account registration. +* `eab-key-id`: External account binding key ID from DigiCert. +* `eab-hmac-key`: External account binding HMAC key from DigiCert. +* `acme-challenge`: Challenge type. Use `dns`. +* `dns-target-creds`: Name of the DNS provider target. Supported target types are AWS, Azure, GCP, and Cloudflare. +* `dns-zone`: Use this when `--dns-target-creds` points to a Cloudflare target. +* `hosted-zone`: Use this when `--dns-target-creds` points to an AWS target. +* `resource-group`: Use this when `--dns-target-creds` points to an Azure target. +* `gcp-project`: Use this when `--dns-target-creds` points to a GCP target and the project ID cannot be derived automatically. +* `timeout`: Challenge validation timeout. Default is `5m`. Supported range is `1m` to `1h`. +* `key`: Protection key used to encrypt target secret values. + +[View the complete list of target command parameters.](https://docs.akeyless.io/docs/cli-ref-targets) + +### Use the Console + +1. Log in to the Akeyless Console, and go to **Targets**, then **New**, then **Certificate Automation (DigiCert)**. +2. Define the **Name** and **Location**. +3. Select a **Protection key** with a Customer Fragment to enable Zero-Knowledge, and click **Next**. [Read more about Zero-Knowledge Encryption](https://docs.akeyless.io/docs/gateway-zero-knowledge). +4. Define the remaining parameters: + +* **Environment**: **US Production**, **EU Production**, **US Demo**, or **EU Demo**. +* **Email**: Email address used to register the ACME account. +* **EAB Key ID** and **EAB HMAC Key**: DigiCert external account binding values. +* **DNS Provider**: **AWS**, **GCP**, or **Azure**. +* **Target**: DNS provider target that holds credentials. +* **Hosted Zone**: Route 53 hosted zone identifier (AWS). +* **Resource Group**: Azure DNS resource group name (Azure). +* **GCP Project**: Optional GCP Cloud DNS project ID (GCP). +* **Timeout**: Challenge validation timeout in seconds. -* `eab-key-id`: External Account Binding Key ID from DigiCert Services. - -* `eab-hmac-key`: External Account Binding HMAC Key from DigiCert Services. - -* `acme-challenge`: Use this when you need DNS validation or want to set the challenge type explicitly. Supported values are `http` (default) and `dns`. - -* `dns-target-creds`: Use this when `--acme-challenge=dns`. This is required for DNS validation. Supported target types are AWS, Azure, GCP, and Cloudflare. - -* `dns-zone`: Use this when `--acme-challenge=dns` and `--dns-target-creds` points to a Cloudflare target. - -* `hosted-zone`: Use this when `--acme-challenge=dns` and `--dns-target-creds` points to an AWS target. This identifies the Route 53 hosted zone. - -* `resource-group`: Use this when `--acme-challenge=dns` and `--dns-target-creds` points to an Azure target. - -* `gcp-project`: Use this when `--acme-challenge=dns` and `--dns-target-creds` points to a GCP target and the project ID cannot be derived automatically. - -* `timeout`: Use this when challenge validation needs a custom wait time. Default is `5m`. Supported range is `1m` to `1h`. - -* `key`: Use this when you want to encrypt target secret values with a specific protection key instead of the account default key. - -[View the complete list of parameters for this command.](https://docs.akeyless.io/docs/cli-ref-targets#lets-encrypt) - -## Create a Digicert Target in the Console +> ℹ️ **Note:** +> +> Cloudflare DNS configuration for DigiCert is available through the CLI flow. -1. Log in to the Akeyless Console, and go to **Targets**, then **New**, then **Certificate Automation (Digicert)**. +1. Click **Finish**. -2. Define the Name of the target, and specify the Location as a path to the virtual folder where you want to create the new target, using slash `/` separators. If the folder does not exist, it will be created together with the target. +## Configure DNS Provider Authentication (Optional) -3. Select a **Protection key** with a Customer Fragment to enable Zero-Knowledge and click **Next**. [Read more about Zero-Knowledge Encryption](https://docs.akeyless.io/docs/gateway-zero-knowledge). +For DNS challenge flows, a provider target can use Gateway cloud identity instead of static credentials. -4. Define the remaining parameters as follows: +### Gateway Cloud Identity Examples -* **Environment**: The ACME environment, **US Production** / **EU Production** / **US Demo** or **EU Demo** +```shell AWS +akeyless target create aws \ +--name \ +--use-gw-cloud-identity \ +--region +``` +```shell Azure +akeyless target create azure \ +--name \ +--connection-type cloud-identity \ +--subscription-id \ +--resource-group-name +``` +```shell GCP +akeyless target create gcp \ +--name \ +--use-gw-cloud-identity +``` -* **Email**: Email address used to register the ACME account. +## DNS Provider Permissions for DNS-01 -* **DNS Provider**: Either **AWS**, **GCP**, **Azure**, or **Cloudflare** (relevant only if **Challenge Type** is **DNS**). +When using `dns` challenge validation, the target referenced by `dns-target-creds` must have permission to create and update ACME TXT records in the relevant DNS zone. -* **Target**: Select a target that contains the DNS provider credentials (relevant only if **Challenge Type** is **DNS**). +* **AWS Route 53** + * **Required for DNS-01 record changes**: `route53:ChangeResourceRecordSets` on the target hosted zone. + * **Common read permissions**: `route53:GetHostedZone`, `route53:ListHostedZonesByName`, and `route53:ListResourceRecordSets`. + * Reference: [Actions, resources, and condition keys for Amazon Route 53](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonroute53.html) and [Permissions required to use the Route 53 API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html) - * **Hosted Zone**: [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) hosted zone identifier. (Relevant only if **Challenge Type** is **DNS** and **DNS Provider** is **AWS**). +* **GCP Cloud DNS** + * **Required for DNS-01 record changes**: `dns.changes.create` and relevant record set permissions. + * **Common read permissions**: `dns.managedZones.get`, `dns.managedZones.list`, `dns.resourceRecordSets.get`, and `dns.resourceRecordSets.list`. + * Reference: [Access control with IAM](https://docs.cloud.google.com/dns/docs/access-control) - * **Resource Group**: Azure resource group name. (Relevant only if **Challenge Type** is **DNS** and **DNS Provider** is **Azure**). +* **Azure DNS** + * **Recommended built-in role**: **DNS Zone Contributor** at the DNS zone scope. + * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) - * **GCP Project**: GCP Cloud DNS project ID. Optional when **DNS Provider** is **GCP**. +## Troubleshoot DNS Challenge Flows -* **DNS Zone**: Cloudflare DNS zone name. Relevant only when **DNS Provider** is **Cloudflare**. +If certificate issuance fails during DNS challenge validation, validate the following: -* **Timeout**: Challenge validation timeout in seconds. Default is 300 seconds (5 minutes). +* The `dns-target-creds` target exists and is configured for the expected provider. +* The provider-specific parameter is set correctly: + * AWS: `hosted-zone` + * Azure: `resource-group` + * GCP: `gcp-project` (when project ID cannot be derived automatically) + * Cloudflare: `dns-zone` +* The requested domain is hosted in the DNS zone managed by the provider target. +* The Gateway has network access to provider DNS APIs. -1. Click Finish. +> ℹ️ **Note (Least Privilege):** +> +> Scope permissions to only the DNS zones and record operations required for certificate validation. diff --git a/docs/Secrets Management/targets/google-ca-target.md b/docs/Secrets Management/targets/google-ca-target.md index 17ab72329..d4cede591 100644 --- a/docs/Secrets Management/targets/google-ca-target.md +++ b/docs/Secrets Management/targets/google-ca-target.md @@ -11,13 +11,24 @@ With a public CA, Akeyless cannot access the private key that signs certificates The **Google CA** integration uses an [ACME Client (v2)](https://datatracker.ietf.org/doc/html/rfc8555). -To prove domain ownership, the Akeyless integration supports DNS validation: +## Before You Begin -* **DNS validation**: Ownership is proven by adding a DNS TXT record. This requires the domain to be managed in a supported DNS provider's hosted zone (for example, Amazon Route 53, GCP Cloud DNS, or Azure DNS). +* Ensure an [Akeyless Gateway](https://docs.akeyless.io/docs/gateway-overview) is deployed and reachable. +* Create a DNS provider target before creating the Google CA target. +* Confirm that the DNS target has permissions to manage TXT records in the relevant zone. +* Collect Google CA external account binding (EAB) values: `eab-key-id` and `eab-hmac-key`. -## Create a Google CA Target with the CLI +## Validation Method -To create a Google CA target with the CLI, use one of the following examples based on the challenge method and DNS provider: +Google CA public CA integration in Akeyless uses DNS challenge (`dns`) for domain ownership validation. + +## Configure the Google CA Target + +### Use the CLI + +Use one of the following DNS challenge examples by provider. + +#### DNS challenge examples ```shell DNS with AWS akeyless target create google-trust \ @@ -64,7 +75,7 @@ akeyless target create google-trust \ --dns-zone ``` -Where: +#### Key CLI flags * `name`: A unique name for the target. The name can include a path to a virtual folder by using slash `/` separators. If the folder does not exist, Akeyless creates it with the target. @@ -76,7 +87,7 @@ Where: * `google-trust-url`: Use this when you want to select the ACME environment explicitly. Supported values are `production` (default) and `staging`. -* `acme-challenge`: Use this when you need DNS validation or want to set the challenge type explicitly. +* `acme-challenge`: Challenge type. Use `dns`. * `dns-target-creds`: Use this when `--acme-challenge=dns`. This is required for DNS validation. Supported target types are AWS, Azure, GCP, and Cloudflare. @@ -88,13 +99,13 @@ Where: * `gcp-project`: Use this when `--acme-challenge=dns` and `--dns-target-creds` points to a GCP target and the project ID cannot be derived automatically. -* `timeout`: Use this when challenge validation needs a custom wait time. Default is `5m`. Supported range is `1m` to `1h`. +* `timeout`: Challenge validation timeout. Default is `5m`. Supported range is `1m` to `1h`. * `key`: Use this when you want to encrypt target secret values with a specific protection key instead of the account default key. -[View the complete list of parameters for this command.](https://docs.akeyless.io/docs/cli-ref-targets#lets-encrypt) +[View the complete list of target command parameters.](https://docs.akeyless.io/docs/cli-ref-targets) -## Create a Google CA Target in the Console +### Use the Console 1. Log in to the Akeyless Console, and go to **Targets**, then **New**, then **Certificate Automation (Google CA)**. @@ -112,7 +123,7 @@ Where: * **EAB HMAC Key**: External Account Binding HMAC Key from Google CA Services. -* **DNS Provider**: Either **AWS**, **GCP**, **Azure**, or **Cloudflare** (relevant only if **Challenge Type** is **DNS**). +* **DNS Provider**: Either **AWS**, **GCP**, or **Azure** (relevant only if **Challenge Type** is **DNS**). * **Target**: Select a target that contains the DNS provider credentials (relevant only if **Challenge Type** is **DNS**). @@ -122,8 +133,70 @@ Where: * **GCP Project**: GCP Cloud DNS project ID. Optional when **DNS Provider** is **GCP**. -* **DNS Zone**: Cloudflare DNS zone name. Relevant only when **DNS Provider** is **Cloudflare**. - * **Timeout**: Challenge validation timeout in seconds. Default is 300 seconds (5 minutes). +> ℹ️ **Note:** +> +> Cloudflare DNS configuration for Google CA is available through the CLI flow. + 1. Click Finish. + +## Configure DNS Provider Authentication (Optional) + +For DNS challenge flows, a provider target can use Gateway cloud identity instead of static credentials. + +### Gateway Cloud Identity Examples + +```shell AWS +akeyless target create aws \ +--name \ +--use-gw-cloud-identity \ +--region +``` +```shell Azure +akeyless target create azure \ +--name \ +--connection-type cloud-identity \ +--subscription-id \ +--resource-group-name +``` +```shell GCP +akeyless target create gcp \ +--name \ +--use-gw-cloud-identity +``` + +## DNS Provider Permissions for DNS-01 + +When using `dns` challenge validation, the target referenced by `dns-target-creds` must have permission to create and update ACME TXT records in the relevant DNS zone. + +* **AWS Route 53** + * **Required for DNS-01 record changes**: `route53:ChangeResourceRecordSets` on the target hosted zone. + * **Common read permissions**: `route53:GetHostedZone`, `route53:ListHostedZonesByName`, and `route53:ListResourceRecordSets`. + * Reference: [Actions, resources, and condition keys for Amazon Route 53](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonroute53.html) and [Permissions required to use the Route 53 API](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/r53-api-permissions-ref.html) + +* **GCP Cloud DNS** + * **Required for DNS-01 record changes**: `dns.changes.create` and relevant record set permissions. + * **Common read permissions**: `dns.managedZones.get`, `dns.managedZones.list`, `dns.resourceRecordSets.get`, and `dns.resourceRecordSets.list`. + * Reference: [Access control with IAM](https://docs.cloud.google.com/dns/docs/access-control) + +* **Azure DNS** + * **Recommended built-in role**: **DNS Zone Contributor** at the DNS zone scope. + * Reference: [Azure built-in roles for Networking - DNS Zone Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/networking#dns-zone-contributor) + +## Troubleshoot DNS Challenge Flows + +If certificate issuance fails during DNS challenge validation, validate the following: + +* The `dns-target-creds` target exists and is configured for the expected provider. +* The provider-specific parameter is set correctly: + * AWS: `hosted-zone` + * Azure: `resource-group` + * GCP: `gcp-project` (when project ID cannot be derived automatically) + * Cloudflare: `dns-zone` +* The requested domain is hosted in the DNS zone managed by the provider target. +* The Gateway has network access to provider DNS APIs. + +> ℹ️ **Note (Least Privilege):** +> +> Scope permissions to only the DNS zones and record operations required for certificate validation. From bcaa0b9eb82a572a645cafb955a8312ea207c333 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Fri, 22 May 2026 10:51:53 -0600 Subject: [PATCH 5/5] docs(google-ca): fix ACME endpoint URLs in console section --- docs/Secrets Management/targets/google-ca-target.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Secrets Management/targets/google-ca-target.md b/docs/Secrets Management/targets/google-ca-target.md index d4cede591..e696f0844 100644 --- a/docs/Secrets Management/targets/google-ca-target.md +++ b/docs/Secrets Management/targets/google-ca-target.md @@ -117,7 +117,7 @@ akeyless target create google-trust \ * **Email**: Email address used to register the ACME account. -* **URL**: Either [Production](https://acme-v02.api.letsencrypt.org/directory) or [Staging](https://acme-staging-v02.api.letsencrypt.org/directory). +* **URL**: Either [Production](https://dv.acme-v02.api.pki.goog/directory) or [Staging](https://dv.acme-v02.test-api.pki.goog/directory). * **EAB KID**: External Account Binding Key ID from Google CA Services.