Manage DNS authorizations

This section describes how to create and manage DNS authorizations for use with Google-managed certificates.

For more information on DNS authorizations, see How Certificate Manager works.

To learn how to deploy a certificate with Certificate Manager, see Deployment overview.

For more information about the gcloud commands used on this page, see the Certificate Manager CLI reference.

Create a DNS authorization

To create a DNS authorization, complete the steps in this section. Because each DNS authorization covers only a single hostname, you must create a DNS authorization for each hostname that you want to use with the target certificate. Currently, there is no way to use DNS authorization for the same domain in two projects.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

gcloud

 gcloud certificate-manager dns-authorizations create AUTHORIZATION_NAME \
     --domain="DOMAIN_NAME"
 gcloud certificate-manager dns-authorizations describe AUTHORIZATION_NAME

Replace the following:

AUTHORIZATION_NAME is a unique name that describes this DNS authorization.
DOMAIN_NAME is the name of the domain for which you are creating this DNS authorization.

This command returns the CNAME record that you must add to your DNS configuration. For example:

createTime: '2022-01-14T13:35:00.258409106Z'
dnsResourceRecord:
  data: 0e40fc77-a37d-4eb8-8fe1-eea2e18d12d9.4.authorize.certificatemanager.goog.
  name: _acme-challenge.example.com.
  type: CNAME
domain: example.com
name: projects/myProject/locations/global/dnsAuthorizations/myAuthorization
updateTime: '2022-01-14T13:35:01.571086137Z'

Terraform

To create a DNS authorization, you can use a google_certificate_manager_dns_authorization resource.

certificate_manager/dns_managed_zone_with_wildcard_certificate/main.tf

View on GitHub Feedback

resource "google_certificate_manager_dns_authorization" "default" {
  name        = "${local.name}-dnsauth-${random_id.tf_prefix.hex}"
  description = "The default dns auth"
  domain      = local.domain
  labels = {
    "terraform" : true
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

Create a DNS authorization by making a POST request to the dnsAuthorizations.create method as follows:

POST /v1/projects/PROJECT_ID/locations/global/dnsAuthorizations?dns_authorization_id=AUTHORIZATION_NAME"
{
  "domain": "DOMAIN_NAME",
}

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
AUTHORIZATION_NAME is a unique name that describes this DNS authorization.
DOMAIN_NAME is the name of the domain for which you are creating this DNS authorization.

Add the CNAME record to your DNS configuration

When you create a DNS authorization, Google Cloud returns the corresponding CNAME record for the validation sub-domain. You must add this CNAME record to your DNS configuration in the DNS zone of the target domain. If you're using Google Cloud to manage your DNS, complete the steps in this section. Otherwise, consult the documentation for your third-party DNS solution.

For more information on how Certificate Manager uses this CNAME record to verify domain ownership, see Domain authorizations for Google-managed certificates.

gcloud

Initiate the DNS record transaction:
```
gcloud dns record-sets transaction start --zone="DNS_ZONE_NAME"
```
Replace the following:
- DNS_ZONE_NAME is the name of the target DNS zone.
Add the CNAME record to the target DNS zone:
```
gcloud dns record-sets transaction add CNAME_RECORD \
 --name="_acme-challenge.DOMAIN_NAME." \
 --ttl="30" \
 --type="CNAME" \
 --zone="DNS_ZONE_NAME"
```
Replace the following:
- CNAME_RECORD is the full value of the CNAME record returned by the gcloud command that created the corresponding DNS authorization.
- DOMAIN_NAME is the name of the target domain.
- DNS_ZONE_NAME is the name of the target DNS zone.
Note: You must include the trailing period after the target domain name.
Execute the DNS record transaction to save your changes:
```
gcloud dns record-sets transaction execute --zone="DNS_ZONE_NAME"
```
Replace the following:
- DNS_ZONE_NAME is the name of the target DNS zone.

Terraform

To add the CNAME record to your DNS configuration, you can use a google_dns_record_set resource.

certificate_manager/dns_managed_zone_with_wildcard_certificate/main.tf

View on GitHub Feedback

resource "google_dns_record_set" "cname" {
  name         = google_certificate_manager_dns_authorization.default.dns_resource_record[0].name
  managed_zone = google_dns_managed_zone.default.name
  type         = google_certificate_manager_dns_authorization.default.dns_resource_record[0].type
  ttl          = 300
  rrdatas      = [google_certificate_manager_dns_authorization.default.dns_resource_record[0].data]
}

For more information on DNS records, see Managing records.

Update a DNS authorization

To update a DNS authorization, complete the steps in this section. You can update a DNS authorization as follows:

Specify new labels
Specify a new description

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

gcloud

 gcloud certificate-manager dns-authorizations update AUTHORIZATION_NAME \
     --update-labels="LABELS" \
     --description="DESCRIPTION"

Replace the following:

AUTHORIZATION_NAME is the name of the target DNS authorization.
LABELS is an optional flag that specifies the labels for this DNS authorization.
DESCRIPTION is an optional flag that specifies the description for this DNS authorization.

API

Update a DNS authorization by making a PATCH request to the dnsAuthorizations.patch method as follows:

PATCH /v1/projects/PROJECT_ID/locations/global/dnsAuthorizations/AUTHORIZATION_NAME?updateMask=labels,description"
{
    description: "DESCRIPTION",
    labels: { "LABEL_KEY": "LABEL_VALUE" }
}

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
AUTHORIZATION_NAME is the name of the target DNS authorization.
DESCRIPTION is an optional field that specifies the description for this DNS authorization.
LABEL_KEY is a label key applied to this DNS authorization.
LABEL_VALUE is a label value applied to this DNS authorization.

List DNS authorizations

To list currently configured DNS authorizations, complete the steps in this section.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Viewer
Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

gcloud

gcloud certificate-manager dns-authorizations list \
    --filter="FILTER" \
    --page-size="PAGE_SIZE" \
    --limit="LIMIT" \
    --sort-by="SORT_BY"

Replace the following:

FILTER is an expression that constrains the returned results to specific values. For example, you can filter results by the following criteria:
- Domain: --filter='domain=example.com'
- Labels and creation time: --filter='labels.key:value AND create_time > "2021-09-01T00:00:00Z"'
For more filtering examples that you can use with Certificate Manager, see Sorting and filtering list results in the Cloud Key Management Service documentation.
PAGE_SIZE is the number of results to return per page.
LIMIT is the maximum number of results to return.
SORT_BY is a comma-delimited list of name fields by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the desired field with ~.

API

List currently configured DNS authorizations by making a GET request to the dnsAuthorizations.list method as follows:

GET /v1/projects/PROJECT_ID/locations/global/dnsAuthorizations?filter=FILTER&pageSize=PAGE_SIZE&sortBy=SORT_BY

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
FILTER is an expression that constrains the returned results to specific values.
PAGE_SIZE is the number of results to return per page.
SORT_BY is a comma-delimited list of field names by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the desired field with ~.

Delete a DNS authorization

To delete a DNS authorization, complete the steps in this section. To delete a DNS authorization that is currently assigned to one or more Google-managed certificates, you must delete those certificates before you can delete the DNS authorization.

To complete this task, you must have the Certificate Manager Owner role on the target Google Cloud project.

For more information, see Roles and permissions.

gcloud

gcloud certificate-manager dns-authorizations delete AUTHORIZATION_NAME

Replace the following:

AUTHORIZATION_NAME is the name of the target DNS authorization.

API

Delete a DNS authorizations by making a DELETE request to the dnsAuthorizations.delete method as follows:

DELETE /v1/projects/PROJECT_ID/locations/global/dnsAuthorizations/AUTHORIZATION_NAME

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
AUTHORIZATION_NAME is the name of the target DNS authorization.

Manage DNS authorizations

Create a DNS authorization

gcloud

Terraform

API

Add the CNAME record to your DNS configuration

gcloud

Terraform

Update a DNS authorization

gcloud

API

List DNS authorizations

gcloud

API

Delete a DNS authorization

gcloud

API

What's next