Skip to content

DOCS-818: Expand Target DNS guidance #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
harrison-akeyless wants to merge 6 commits into
base: v1.0
Choose a base branch
from
Open

DOCS-818: Expand Target DNS guidance #267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1222842
docs(lets-encrypt): add Azure managed identity DNS-01 guidance
harrison-akeyless May 22, 2026
7559cf3
docs(lets-encrypt): expand cloud identity examples and improve guide
harrison-akeyless May 22, 2026
ec73856
docs(lets-encrypt): improve page information architecture
harrison-akeyless May 22, 2026
b461068
docs(targets): improve IA for DigiCert and Google CA pages
harrison-akeyless May 22, 2026
bcaa0b9
docs(google-ca): fix ACME endpoint URLs in console section
harrison-akeyless May 22, 2026
ba280a9
Merge branch 'v1.0' into v1.0_docs-818-lets-encrypt-azure-example
harrison-akeyless May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 103 additions & 51 deletions docs/Secrets Management/targets/digicert-target.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,38 @@ 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 \
--name <Target Name> \
--digicert-url <us-production / eu-production / us-demo / eu-demo> \
--email <ACME Account Email> \
--eab-key-id <EAB Key ID> \
--eab-hmac-key <EAB HAMC Key> \
--eab-hmac-key <EAB HMAC Key> \
--acme-challenge dns \
--dns-target-creds <AWS DNS Target Name> \
--hosted-zone <Route53 Hosted Zone ID>
Expand All @@ -36,7 +47,7 @@ akeyless target create digicert \
--digicert-url <us-production / eu-production / us-demo / eu-demo> \
--email <ACME Account Email> \
--eab-key-id <EAB Key ID> \
--eab-hmac-key <EAB HAMC Key> \
--eab-hmac-key <EAB HMAC Key> \
--acme-challenge dns \
--dns-target-creds <GCP DNS Target Name> \
--gcp-project <GCP Project ID>
Expand All @@ -47,7 +58,7 @@ akeyless target create digicert \
--digicert-url <us-production / eu-production / us-demo / eu-demo> \
--email <ACME Account Email> \
--eab-key-id <EAB Key ID> \
--eab-hmac-key <EAB HAMC Key> \
--eab-hmac-key <EAB HMAC Key> \
--acme-challenge dns \
--dns-target-creds <Azure DNS Target Name> \
--resource-group <Azure Resource Group Name>
Expand All @@ -64,62 +75,103 @@ akeyless target create digicert \
--dns-zone <Cloudflare 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 <AWS DNS Target Name> \
--use-gw-cloud-identity \
--region <AWS Region>
```
```shell Azure
akeyless target create azure \
--name <Azure DNS Target Name> \
--connection-type cloud-identity \
--subscription-id <Azure Subscription ID> \
--resource-group-name <Azure DNS Resource Group Name>
```
```shell GCP
akeyless target create gcp \
--name <GCP DNS Target 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.
99 changes: 86 additions & 13 deletions docs/Secrets Management/targets/google-ca-target.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -64,7 +75,7 @@ akeyless target create google-trust \
--dns-zone <Cloudflare 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.

Expand All @@ -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.

Expand All @@ -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)**.

Expand All @@ -106,13 +117,13 @@ Where:

* **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.

* **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**).

Expand All @@ -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 <AWS DNS Target Name> \
--use-gw-cloud-identity \
--region <AWS Region>
```
```shell Azure
akeyless target create azure \
--name <Azure DNS Target Name> \
--connection-type cloud-identity \
--subscription-id <Azure Subscription ID> \
--resource-group-name <Azure DNS Resource Group Name>
```
```shell GCP
akeyless target create gcp \
--name <GCP DNS Target 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.
Loading
Loading