From c53e0adc087ef250e5ee9ffb3b9c086d61acd098 Mon Sep 17 00:00:00 2001 From: Jivan Pal Date: Wed, 11 Oct 2023 15:00:41 +0100 Subject: [PATCH] Improve Cloudflare documentation --- dnsapi.md | 59 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/dnsapi.md b/dnsapi.md index 8fdf794..5f571a8 100644 --- a/dnsapi.md +++ b/dnsapi.md @@ -160,39 +160,54 @@ If your DNS provider doesn't provide API access, you can use our [DNS alias mode ## 1. CloudFlare Option: -Cloudflare Domain API offers two methods to automatically issue certs. +Cloudflare Domain API offers two methods to automatically issue certs: -### Using the global API key -First you need to login to your Cloudflare account to get your [API key](https://dash.cloudflare.com/profile). Each token generated is not stored on cloudflare account and will have expiry if not set correctly. You will get this in API keys section. -```sh -export CF_Key="" -export CF_Email="" -``` +(a) creating a restrictive API token with specific permissions; or +(b) using the global API key associated with your Cloudflare account, which has all permissions. -### Using the new cloudflare api token, you will get this after normal login and scroll down on dashboard and copy credentials. -```sh -export CF_Token="" -export CF_Account_ID="" -``` -In order to use the new token, the token currently needs access read access to Zone.Zone, and write access to Zone.DNS, across all Zones. -See [Issue #2398](https://github.com/acmesh-official/acme.sh/issues/2398) for more info. +Using method (b) is strongly NOT recommended as leakage of the global API token will completely compromise your account, though the key can be reset if this occurs. By contrast, method (a) is recommended because if a restrictive API token is leaked, the attack surface is small, it can simply be deleted/revoked, and its permissions can also be changed at any time via your Cloudflare profile settings. -Alternatively, if the certificate only covers a single zone, you can restrict the API Token only for write access -to Zone.DNS for a single domain, and then specify the `CF_Zone_ID` directly: +### (a) Using a restrictive API token + +You will need to create an API token which either: + +(i) has permissions to edit a single specific DNS zone; or +(ii) has permissions to edit multiple DNS zones. + +You can do this via your Cloudflare profile page, under the [API Tokens section](https://dash.cloudflare.com/profile/api-tokens). When your create the token, under Permissions, select Zone > DNS > Edit, and under Zone Resources, only include the specific DNS zones within which you need to perform ACME DNS challenges. + +The API token is a 40-character string that may contain uppercase letters, lowercase letters, numbers, and underscores. You must provide it to acme.sh by setting the environment variable `CF_Token` to its value, e.g. run `export CF_Token="Y_jpG9AnfQmuX5Ss9M_qaNab6SQwme3HWXNDzRWs"`. + +#### (i) Single DNS zone + +You must give acme.sh the *zone ID* of the DNS zone it needs to edit. This is a 32-character hexadecimal string (e.g. `763eac4f1bcebd8b5c95e9fc50d010b4`), and should not be confused with the *zone name* (e.g. `example.com`). This zone ID can be found via the Cloudflare dashboard, on the zone's Overview page, in the right-hand sidebar. + +You provide this info by setting the environment variable `CF_Zone_ID` to this zone ID, e.g. run `export CF_Zone_ID="763eac4f1bcebd8b5c95e9fc50d010b4"`. + +#### (ii) Multiple DNS zones + +You must give acme.sh the *account ID* of the Cloudflare account to which the relevant DNS zones belong. This is a 32-character hexadecimal string, and should not be confused with other account identifiers, such as the account email address (e.g. `alice@example.com`) or global API key (which is also a 32-character hexadecimal string). This account ID can be found via the Cloudflare dashboard, as the end of the URL when logged in, or on the Overview page of any of your zones, in the right-hand sidebar, beneath the zone ID. + +You provide this info by setting the environment variable `CF_Account_ID` to this account ID, e.g. run `export CF_Account_ID="763eac4f1bcebd8b5c95e9fc50d010b4"`. + +### (b) Using the global API key + +You can get your global API key from your Cloudflare profile page, under the [API tokens section](https://dash.cloudflare.com/profile/api-tokens). Click "View" next to Global API key, verify your Cloudflare password, and it will be revealed to you. It is a 32-character hexadecimal string that you must provide to acme.sh by setting the environment variable `CF_Key` to its value. You must also set `CF_Email` to the email address that is associated with your Cloudflare account; this is the email address you enter when logging in to Cloudflare. For example: ```sh -export CF_Token="" -export CF_Account_ID="" -export CF_Zone_ID="" +export CF_Key="763eac4f1bcebd8b5c95e9fc50d010b4" +export CF_Email="alice@example.com" ``` +### Getting a certificate + Ok, let's issue a cert now: + ```sh -./acme.sh --issue --dns dns_cf -d example.com -d *.example.com +./acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' ``` -The `CF_Key` and `CF_Email` or `CF_Token`and `CF_Account_ID`will be saved in `~/.acme.sh/account.conf` and will be reused when needed. - +Any environment variables that were set and used when issuing the certificate will be saved in `~/.acme.sh/account.conf` so that they can be automatically reused in future when issuing new certificates or renewing existing certificates using `dns_cf`.