Bridge SSL
ACME account: the key, the contacts and what you can change
An ACME account is the set of metadata an ACME server, run by a certificate authority, keeps for one client. It is identified by a key pair: the server stores the public key that verifies the signature on the creation request and uses it to authenticate that account's later requests [1]. Issuance itself is laid out in the ACME overview; this page covers the account those steps run under, which means what it holds, what its key signs and which changes the protocol allows. Here "account" means the protocol object defined in RFC 8555, not a login on a website.
- Created by
- A signed POST to the server's newAccount URL; the server answers 201 (Created) with the account URL in the Location header [1]
- Identified by
- The account key pair; the account URL becomes the kid value in later requests [1]
- Status values
- valid, deactivated and revoked [1]
- Fields at creation
- Any subset of contact, termsOfServiceAgreed, onlyReturnExisting and externalAccountBinding [1]
- Key change
- A rollover request carrying signatures by both the old and the new key [1]
- After deactivation
- ACME provides no way to reactivate the account [1]
What the account object holds
The server's account object has five fields [1]. The server ignores any value a client sends for orders, and the table shows which of the other fields a client can change later.
| Field | Required | What it carries | Client can change it later |
|---|---|---|---|
| status | yes | valid, deactivated or revoked; "deactivated" marks a client-initiated deactivation, "revoked" a server-initiated one | Only to deactivate |
| contact | no | URLs the server can use to reach the client about the account, for example to notify about server-initiated revocation or certificate expiration | Yes, by an account update |
| termsOfServiceAgreed | no | true in a newAccount request means the client agrees to the terms | No |
| externalAccountBinding | no | In a newAccount request, approval by the holder of an existing non-ACME account to bind it to this one | No |
| orders | yes | The URL from which the list of orders submitted by this account can be fetched | No, the server ignores updates |
The orders URL ties each order to the account that submitted it. A certificate resource is a single, immutable certificate, and a client that wants a renewed one starts a new order process [1]. How that cycle is kept running is covered in ACME certificate renewal automation.
Where the account key is used
The same key pair appears in three places.
Signing requests. A newAccount request carries the public key in a jwk field. Every other request signed by an existing account carries a kid field holding the account URL, and the two fields are mutually exclusive [1].
Proving control of a domain. All challenges defined in the ACME RFC use a key authorization: the challenge token, a dot and the base64url thumbprint of the account key [1].
Revoking a certificate. A revocation request can be signed with the account key pair or with the key pair in the certificate. The server must treat at least two accounts as authorized: the one that issued the certificate and one that holds authorizations for all of its identifiers [1].
Account lifecycle, request by request
The requests below create, find, change and end an ACME account on an ACME server. Each row names the request, the server's response and the limit the RFC text sets; contact, terms and key details follow in later sections.
Create, find and bind
A client sends these requests to the ACME server, starting with the one that creates the ACME account. Binding an external account to it has its own section below.
| Need | Request | Server response | Limit in the RFC |
|---|---|---|---|
| Register | POST to newAccount, with the public key in jwk | Stores the key, answers 201 with the account URL in Location | A server that requires terms must reject a request without termsOfServiceAgreed set to true |
| Recover an account URL from its key | newAccount signed with the registered key | 200 and the account URL in Location | Fields in the request are ignored |
| Look up without creating | newAccount with onlyReturnExisting set to true | The account URL if the account exists | If it does not, error 400 accountDoesNotExist; nothing is created |
| Tie to a customer record | externalAccountBinding in newAccount | Server may require the field | Cannot be updated later |
Change and end
| Need | Request | Server response | Limit in the RFC |
|---|---|---|---|
| Change contacts | POST to the account URL with new contact values | 200 with the resulting account object | Updates to orders, termsOfServiceAgreed and status are ignored, except deactivation |
| Replace the key | Rollover request signed by the new key and, around it, by the old key | Replaces the old key with the new one, answers 200 | If an account with the new key exists, 409 (Conflict) with that account in Location is the recommended answer; pending orders and authorizations must not be invalidated |
| Deactivate | POST to the account URL with status deactivated, signed by the account key | 200 with the account object; later POSTs from it get 401 unauthorized | No reactivation; the server should cancel pending operations such as orders and should not revoke certificates the account issued |
Contacts and terms
The contact field of an ACME account is optional. An ACME server that validates contact URLs must support the mailto scheme. A client must not send a mailto URL that contains hfields or more than one addr-spec in the to component, and a server that meets one should reject it as invalid [1]. A server that rejects a contact URL for an unsupported scheme returns the error unsupportedContact; one rejected for an invalid value in a supported scheme gets invalidContact [1].
A server that wants clients to agree to its terms of service publishes their URL in the termsOfService subfield of meta in the directory object, and it must reject newAccount requests where termsOfServiceAgreed is not true. Clients should not agree by default but should require some user interaction [1]. If the terms change and the server will not process a request without a new agreement, it answers 403 with the error userActionRequired, a Link header of type terms-of-service and an instance URL where a human can see how to agree [1].
External account binding
A server may require the externalAccountBinding field in newAccount requests. It associates the ACME account with an existing account in a non-ACME system, such as a CA customer database [1]. The CA hands the client a MAC key and a key identifier by some mechanism outside ACME [1].
The client then signs a binding JWS whose payload is the account key in JWK form. Its header must carry a MAC-based alg, the CA's key identifier as kid, the same url as the outer request and no nonce; the signature is the MAC computed with the CA's MAC key [1]. This page names no authority; check the documentation of the one you use.
How clients handle the account
An ACME account is created on an ACME server [1]. The table shows what three clients' own documentation says about the ACME account, its contact email and its account key. To choose a client by class, see choosing an ACME client by class; one certificate authority's ACME service is in Let's Encrypt and ACME.
| Client | What its documentation says about the account |
|---|---|
| Certbot | Four account subcommands: register creates an ACME account, unregister deactivates it, update_account updates it and show_account displays its details. The option -m sets the email address for important account notifications and --agree-tos agrees to the Subscriber Agreement of the ACME server. To revoke a certificate, Certbot tries the account key by default, and --key-path revokes with the certificate's private key from any account [2] |
| cert-manager | An ACME issuer is configured with an email, a server URL, a privateKeySecretRef and one or more solvers. The Secret named by privateKeySecretRef stores the account's private key, "your identity with your ACME provider". The example issuer with external account binding sets keyID and keySecretRef under externalAccountBinding. With disableAccountKeyGeneration, cert-manager uses the key already in the Secret instead of creating a new ACME account [3] |
| acme.sh | The --server option picks the certificate authority; the account is registered automatically if you have not used that authority before [4] |
If the account key is lost
cert-manager's documentation says that after losing the account Secret you can generate a new one and issue certificates for the domains managed with the previous account, but you cannot revoke certificates generated using the previous account [3]. The RFC lets a revocation request be signed with the key pair in the certificate instead of the account key [1]. The sources say nothing further about a lost ACME account key, so the rest depends on the client and the certificate authority.
FAQ
What is an ACME account?
The set of metadata an ACME server keeps for one client, tied to the account key and reachable at the account URL. It has a status and the URL of its orders, and it can carry a contact list.
Do I need an email address for an ACME account?
The RFC defines the contact field of an ACME account as optional, and an ACME server that validates contact URLs must support mailto. Agreeing to the terms of service is a separate field. Certbot's -m option sets the address for important account notifications.
What happens if I lose the ACME account key?
cert-manager's documentation says you can generate a new ACME account and issue certificates for the same domains, but you cannot revoke certificates generated with the previous account. The RFC also allows a revocation request signed with the key pair in the certificate instead of the account key. Anything beyond that depends on the client and the certificate authority.
Can I delete or reactivate an ACME account?
A client can deactivate its ACME account by posting status deactivated, signed by the account key. After account deactivation the ACME server must not accept further requests authorized by that key, and ACME provides no way to reactivate. Beyond that, the RFC says a server may take a variety of actions and gives deleting related data and mailing the contacts as examples. Certbot's unregister subcommand deactivates an account.
How do I change the account key?
Send a key rollover request to the ACME server with signatures by both the old and the new key; the request names the account by its account URL. The RFC says a client may do this to recover from a key compromise or proactively mitigate an unnoticed one.
What is external account binding?
An ACME server may require this optional newAccount field. It ties the ACME account to an account in a non-ACME system, such as a CA customer database, and the certificate authority supplies a MAC key and a key identifier outside ACME.
Sources
RFC 8555, Automatic Certificate Management Environment (ACME): sections 6.2, 7.1.2, 7.3 to 7.3.6, 7.4.2, 7.6 and 8.1: rfc-editor.org/rfc/rfc8555.
Certbot documentation, User Guide: eff-certbot.readthedocs.io/en/stable/using.html.
cert-manager documentation, ACME: cert-manager.io/docs/configuration/acme/.
acme.sh, README: github.com/acmesh-official/acme.sh.