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.

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.

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 Permissions and roles.

gcloud

 gcloud beta certificate-manager dns-authorizations create AUTHORIZATION_NAME \
     --domain="DOMAIN_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:

_acme-challenge.www.example.com CNAME 534959-1a8a-40cf-90b6-b1f5f8d22517.2.authorize.certificatemanager.goog

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.

  1. 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.
  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 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.
  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 is the name of the target DNS zone.

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 Permissions and roles.

gcloud

 gcloud beta 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 Permissions and roles.

gcloud

gcloud beta 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 Permissions and roles.

gcloud

gcloud beta 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.

What's next