To ensure your Cloudflare API token has the necessary permissions for Let's Encrypt on Forge, it is essential to configure the token with the correct permissions that allow Forge to manage DNS records needed for the DNS-01 challenge validation used by Let's Encrypt when issuing SSL certificates.
Required Permissions for Cloudflare API Token with Forge
When Forge interacts with Cloudflare to issue certificates via Let's Encrypt, it requires an API token scoped specifically to:
- Zone.Zone Read: This permission allows Forge to read zone details, including the ID of the DNS zone for your domain. This is critical because Forge needs to know which zone to apply DNS changes to when creating verification records.
- Zone.DNS Edit: This permission enables Forge to create, modify, and delete DNS records within the specified zones. It is necessary for Forge to add and remove the TXT records required by Let's Encrypt during SSL certificate validation via the DNS-01 challenge.
These permissions should be granted on all zones attached to your Cloudflare account to cover all domain names you might manage with Forge and request certificates for.
How to Create a Suitable Cloudflare API Token for Forge
1. Log into Cloudflare: Access your Cloudflare dashboard and navigate to your profile settings.
2. Navigate to API Tokens: Select the API Tokens section where you can create and manage scoped API tokens.
3. Create a Custom Token:
- Use the "Create Token" button to start a new token creation.
- Instead of using a full global API key, choose custom permissions for security and minimal privilege.
- Grant the token the following permissions:
- Under the Zone category:
- Zone:Zone Read â Allows reading zone information.
- Zone:DNS Edit â Allows editing DNS records.
- Set the Zone Resources to Include All Zones or specifically include all relevant domains you manage to ensure Forge can operate on all intended domains.
4. Generate and Save Token: Complete token creation and copy the generated token securely. This token will be used by Forge to authenticate API requests to Cloudflare.
Additional Considerations
- Use API Tokens, Not Global API Keys: While Cloudflare's Global API Key can be used, it provides full access to your account which is a significant security risk. API Tokens with scoped permissions are recommended as they offer least privilege access.
- Token Security: Store the API token securely and limit its exposure. Use file permissions to restrict read access when saving token credentials on your server.
- Let's Encrypt DNS Challenge and Wildcard Certificates: Let's Encrypt issues wildcard certificates using the DNS-01 challenge. Therefore, Forge must be able to add and remove TXT records in Cloudflare DNS through the API. Having the DNS Edit permission is non-negotiable.
- Forge Configuration: When configuring your site in Forge for SSL certificates with Let's Encrypt behind Cloudflare, there is normally an interface or configuration file where you input your Cloudflare API token. Forge uses this token to perform the DNS challenges automatically.
- Avoid Proxying During Validation: While Cloudflare proxying does not typically interfere with DNS validation, ensure that the TXT records and domain zone information are accessible and correctly propagating for Let's Encrypt to detect.
- Keep Permissions Minimal: Only assign the needed DNS and zone read permissions to limit risks in case the API token is compromised.
Common Issues and Troubleshooting
- Invalid Request Headers / Zone ID Errors: Errors like "Error determining zone_id: 6003 Invalid request headers" often indicate that the token lacks the necessary permissions or the token is not correctly applied. Double-check that the token includes Zone.Zone Read and Zone.DNS Edit permissions on all relevant zones.
- File Permissions for Token Credentials: When storing the token in a credentials file (for instance, an `.ini` file used by certbot or Forge), ensure the file permissions are secure (usually 600) to avoid errors related to unsafe file permissions.
- Use Updated Cloudflare API Libraries: For integrations using automation scripts (such as certbot with DNS plugins), ensure that the latest Cloudflare API Python library supporting tokens is installed to avoid compatibility issues.
Summary of Permissions Needed
- Zone.Zone Read: To read zone information.
- Zone.DNS Edit: To add/remove DNS TXT records for validation.
Why These Permissions Are Needed
Let's Encrypt issues certificates through domain validation. When using DNS verification:
- It requires the creation of a TXT DNS record under your domain that contains a special token.
- Forge uses Cloudflare's API to create this TXT record automatically.
- After Let's Encrypt verifies this TXT record, Forge deletes the record.
Without the ability to read zones and edit DNS, Forge cannot complete this automated process, and certificate issuance or renewal will fail.
Steps after Creation
Once the Cloudflare API token is created with these permissions:
1. Add the token to Forge's API settings or SSL configuration section.
2. Initiate the SSL certificate issuance through Forge.
3. Monitor certificate creation to ensure all API calls succeed.
4. If you encounter errors, verify token permissions and DNS settings.
This setup secures your Cloudflare account by granting minimal necessary access and facilitates smooth automated SSL certificate issuance through Let's Encrypt on Forge. For detailed guidance, Laravel Forge's official documentation on SSL integration with Cloudflare also outlines this permission structure specifically for Forge users.
This approach ensures your Cloudflare API token is exactly prepared for Let's Encrypt certificate management within Forge without excessive permissions that might pose security risks.