EAB (External Account Binding) #

To enforce quota limits, provide technical support, or prevent abuse, some ACME CAs may require an existing account in a non-ACME system, such as a CA customer database, as a prerequisite for creating new ACME accounts. This account association is called EAB (External Account Binding). It is specified in RFC 8555.

CAs having this requirement advertise it by setting the meta.externalAccountRequired field to true in the JSON object returned by the ACME Directory URL.

Before creating an account with such CAs, clients must retrieve a MAC (Message Authentication Code) key and a key identifier provided by the CA using a mechanism outside of ACME. Clients can then create a new ACME account by setting the externalAccountBinding field in the newAccount request. The value of this field must be derived from the MAC key and key identifier previously provided by the CA. See RFC 8555 for more information.

The CA returns an externalAccountRequired error if it receives a newAccount request without the externalAccountBinding field set.

Getting the MAC Key and the Key Identifier #

Since these values must be retrieved using a mechanism outside of ACME, each CA implements its own method to get the MAC key and the key identifier. For example:

• Google Trust Services requires running the gcloud CLI.
• ZeroSSL requires using their REST API.
• SSL.com requires using their web dashboard.

Setting the externalAccountBinding Field #

Not all ACME clients support EAB. Make sure to use a client that supports EAB if your CA requires it.

Refer to the documentation of your ACME client to find out how to pass the EAB MAC key and the key identifier. For example:

• certbot supports the --eab-hmac-key and --eab-kid flags.
• LEGO supports the --kid and --hmac flags; in addition, the --eab flag must also be set.
• Caddy supports an acme_eab TLS Option.