Updated Cloudflare section to be a bit easier to read, and also more up to date (account-owned keys), and also have an optimal first code example for people who don't read and just copy code
Deco
parent
6b315c6989
commit
f23f7f4113
63
dnsapi.md
63
dnsapi.md
|
|
@ -181,43 +181,58 @@ 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:
|
||||
As of June 2025, the Cloudflare Domain API can be accessed using three kinds of API keys:
|
||||
|
||||
(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.
|
||||
1. User token;
|
||||
2. Account-owned token; or
|
||||
3. User Global API Key (**Not recommended**).
|
||||
|
||||
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.
|
||||
|
||||
### (a) Using a restrictive API token
|
||||
### Method 1 (User Token) + Method 2 (Account-owned Token)
|
||||
|
||||
You will need to create an API token which either:
|
||||
For these methods, it is recommended that you restrict the permissions of the token as much as possible to minimise the consequences of a compromised token.
|
||||
|
||||
(i) has permissions to edit a single specific DNS zone; or
|
||||
(ii) has permissions to edit multiple DNS zones.
|
||||
At a minimum, a token used by acme.sh requires:
|
||||
|
||||
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 "Zone > DNS > Edit" permission;
|
||||
- permission for the specific zones/domains within which you need to perform ACME DNS challenges;
|
||||
- for the IP address of the host machine running acme.sh to be allowed by "Client IP Address Filtering" (if used); and
|
||||
- for the token to be active (i.e.: unexpired).
|
||||
|
||||
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"`.
|
||||
To create a User Token, go to [Cloudflare Profile -> User API Tokens](https://dash.cloudflare.com/profile/api-tokens).
|
||||
|
||||
#### (i) Single DNS zone
|
||||
To create an Account-owned Token, go to [Cloudflare Dashboard -> Manage Account -> Account API Tokens](https://dash.cloudflare.com/?to=/:account/api-tokens).
|
||||
|
||||
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.
|
||||
Once you have the token, you must provide it to acme.sh by setting the environment variable `CF_Token` to its value.
|
||||
|
||||
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:
|
||||
You must also specify either the ID of a single zone (via `CF_Zone_ID`) or, if you are planning to issue ACME DNS challenges for multiple domains, the ID of the account to which all of the zones belong to (via `CF_Account_ID`). You can find the Zone ID and the Account ID on the right side of the "Overview" page of any zone. For example, if you have `example.com` on your Cloudflare account, on the "Account Home" page, click `example.com` to go its "Overview" page, then on the right side under "API" you will see "Zone ID" and "Account ID".
|
||||
|
||||
```sh
|
||||
export CF_Key="763eac4f1bcebd8b5c95e9fc50d010b4"
|
||||
export CF_Token="zfNp-Xm0VhSaCNun7dkLzwnw0UN7FNjaMurUZ8vf"
|
||||
export CF_Account_ID="763eac4f1bcebd8b5c95e9fc50d010b4"
|
||||
./acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
export CF_Token="zfNp-Xm0VhSaCNun7dkLzwnw0UN7FNjaMurUZ8vf"
|
||||
export CF_Zone_ID="3cc91d809a6ff7a93eb48877bf0ec3ef"
|
||||
./acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
|
||||
```
|
||||
|
||||
### Method 3 (User Global API Key) _(Not Recommended)_
|
||||
|
||||
This method is **not recommended** as leakage of this key will completely compromise your account.
|
||||
|
||||
To retrieve your User Global API Key, go to [Cloudflare Profile -> API Tokens](https://dash.cloudflare.com/profile/api-tokens) and under "API Keys", press the "View" button next to "Global API Key". After verifying your Cloudflare password, it will be revealed to you.
|
||||
|
||||
It should be passed to acme.sh via the `CF_Key` environment variable. If you use this method, you must also specify the email address that is associated with your Cloudflare account via the `CF_Email` environment variable.
|
||||
|
||||
```sh
|
||||
export CF_Key="a62e9c685ac445fce1b3c098dc1790dc"
|
||||
export CF_Email="alice@example.com"
|
||||
./acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
|
||||
```
|
||||
|
||||
### Getting a certificate
|
||||
|
|
|
|||
Loading…
Reference in New Issue