Manage DNS authorizations

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

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

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

Note: The Google Cloud CLI instructions on this page assume that you are using Cloud Shell or another environment with Bash installed.

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

Create a DNS authorization

To create a DNS authorization, complete the steps in this section. Because each DNS authorization covers only a single domain name, you must create a DNS authorization for each domain name that you want to use with the target certificate.

To independently manage certificates across multiple projects, you can use per-project DNS authorization (Preview). Certificate Manager can handle issuing and managing certificates for each project independently within Google Cloud. DNS authorizations and certificates that you use within a project are self-contained and don't interact with those in other projects.

Note: Due to ongoing IETF standardization efforts for account-based DNS authorization, Google uses a custom implementation of account-based DNS authorization for per-project DNS authorizations.

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

To use per-project DNS authorization (Preview), run the following command:

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

Replace the following:

• AUTHORIZATION_NAME: a unique name that describes this DNS authorization.
• DOMAIN_NAME: the name of the domain for which you are creating this DNS authorization. The domain name must be a fully qualified domain name, such as myorg.example.com.

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.myorg.example.com.
  type: CNAME
domain: myorg.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.

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: the ID of the target Google Cloud project.
• AUTHORIZATION_NAME: a unique name that describes this DNS authorization.
• DOMAIN_NAME: the name of the domain for which you are creating this DNS authorization. The domain name must be a fully qualified domain name, such as myorg.example.com.

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 about how Certificate Manager uses this CNAME record to verify domain ownership, see Domain authorizations for Google-managed certificates.

gcloud

1. Initiate the DNS record transaction:

   gcloud dns record-sets transaction start --zone="DNS_ZONE_NAME"
   

   Replace the following:

   • DNS_ZONE_NAME: the name of the target DNS zone.

2. 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: the full value of the CNAME record returned by the gcloud command that created the corresponding DNS authorization.
   • DOMAIN_NAME: the name of the target domain. The domain name must be a fully qualified domain name, such as myorg.example.com. You must also include the trailing period after the target domain name.
   • DNS_ZONE_NAME: the name of the target DNS zone.
   Note: You must include the trailing period after the target domain name.

3. 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: 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.

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 about 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: the name of the target DNS authorization.
• LABELS: an optional flag that specifies the labels for this DNS authorization.
• DESCRIPTION: 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: the ID of the target Google Cloud project.
• AUTHORIZATION_NAME: the name of the target DNS authorization.
• DESCRIPTION: an optional field that specifies the description for this DNS authorization.
• LABEL_KEY: a label key applied to this DNS authorization.
• LABEL_VALUE: a label value applied to this DNS authorization.

List DNS authorizations

To list the 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: an expression that constrains the returned results to specific values. For example, you can filter results by the following criteria:

  • Domain: --filter='domain=myorg.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: the number of results to return per page.

• LIMIT: the maximum number of results to return.

• SORT_BY: a comma-delimited list of name fields by which the returned results are sorted. The default sort order is ascending. For a descending sort order, prefix the field with a tilde (~).

API

List all of the 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: the ID of the target Google Cloud project.
• FILTER: an expression that constrains the returned results to specific values.
• PAGE_SIZE: the number of results to return per page.
• SORT_BY: a comma-delimited list of field names by which the returned results are sorted. The default sort order is ascending. For a descending sort order, prefix the field with a tilde (~).

Delete a DNS authorization

To delete a DNS authorization, complete the steps in this section. To delete a DNS authorization that is 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: the name of the target DNS authorization.

API

Delete a DNS authorization 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: the ID of the target Google Cloud project.
• AUTHORIZATION_NAME: the name of the target DNS authorization.

What's next

• Manage certificates
• Manage certificate maps
• Manage certificate map entries
• Manage certificate issuance configs