ACME Accounts - Networking4all ACME Documentation

Understanding the difference between ACME credentials and accounts, and managing multiple accounts

Credentials and Accounts, what is the difference?

The difference between ACME credentials and ACME accounts may seem a bit confusing at first.
When you generate credentials you receive a unique pair of credentials that is directly tied to an organization (relation) you manage.
Using these credentials your ACME client connects to the ACME server and proves that it is allowed to create an ACME account for the relation you selected.
This is known as External Account Binding within the ACME protocol, you bind an account to an external entity. You can create many ACME accounts using one pair of credentials, usually at least one account per server (or client) and one per product type.
In short: the ACME credentials serve as a form of authorization that allows your client to create an ACME account on the server.

ACME credentials

An example of an organization that creates two pairs of ACME credentials for its subsidiaries and uses the ACME credentials of Subsidiary 2 to create a unique ACME account on three individual servers.

Once an account has been created the ACME client does not use the credentials anymore for future requests. The account it created has its own private key that is locally stored by the client and its public key is known by the server. The server therefore trusts that this account is allowed to create and manage orders for the organization in the future.

Why would I need multiple ACME accounts?

In a distributed system where multiple servers or services independently manage certificates it is often necessary or beneficial to use separate ACME accounts for each server or node. Each ACME account is independently tied to the orders, authorizations, and challenges it initiates. By using separate accounts per server or per functional unit:

Compromise of one server does not expose the entire infrastructure's sensitive data like private keys
Revocation or deactivation of one account (due to misuse or security events) does not impact other systems
Using individual accounts allows each server to operate autonomously, without the need to coordinate shared credentials or account states

One other important use of separate ACME accounts is that one client can optionally manage multiple ACME accounts at the same time. This is beneficial in case you need to order certificates for multiple organizations from the same server or node. Depending on the ACME client you use it is often possible to create additional accounts using different sets of credentials. Each account would then be tied to a different organization depending on the credentials that were used.

Managing multiple ACME accounts using the same ACME client/server

Switching to a different set of ACME credentials does not mean your ACME client will automatically attempt to create a new ACME account if an account was already created on your server with another set of credentials before. Certbot for example will ignore any credentials you supply if it has already created an account on a specific ACME server before.
This generally isn't an issue if you need another ACME account for a different product as the server URL is different for every product.
This means the ACME client will treat the different URL as a different ACME server and create a new account.
As a result of this you can create an account when you make your first order through https://acme.networking4all.com/dv and then another one when you make your first order through https://acme.networking4all.com/ov (or any other product). As long as the URL changes clients like Certbot will create a new account. This also means that when the URL changes you also need to include your credentials again once to create the new account.

But what if you needed to order an OV certificate for two separate organizations through https://acme.networking4all.com/ov on the same server? You would need two ACME accounts created with two separate sets of credentials. Not all clients support this functionality natively. Among the clients that support multi-account management natively are: Certify, cert-manager, Posh-ACME, and simple-acme (win-acme). Below are examples on how to deal with this with some common clients.

As explained above Certbot doesn't natively play well with multiple ACME accounts on the same server. A workaround for this is to assign unique working directories for the client to use for every account you need.

Let's say you need to create an OV order example.com for Example Inc. and another OV order networking4all.com for ACME Corporation. Both of these organizations have their own ACME credentials and need their own ACME account. To force Certbot to create a different account for both orders we can add the following to our command: --config-dir /etc/certbot-exampleinc --work-dir /var/lib/certbot-exampleinc --logs-dir /var/log/certbot-exampleinc In this example certbot-exampleinc is simply the directory name of your preference, all the account data will be stored in these custom directories.

Note that you need to use the arguments --config-dir, --work-dir, and --logs-dir when managing certificates for the accounts too.

Full Examples for this scenario:

certbot certonly --config-dir /etc/certbot-exampleinc --work-dir /var/lib/certbot-exampleinc --logs-dir /var/log/certbot-exampleinc --eab-kid <EXAMPLE-INC-KID> --eab-hmac-key <EXAMPLE-INC-SECRET> --server https://acme.networking4all.com/ov -d example.com --webroot

certbot certonly --config-dir /etc/certbot-acmecorporation --work-dir /var/lib/certbot-acmecorporation --logs-dir /var/log/certbot-acmecorporation --eab-kid <ACMECORP-KID> --eab-hmac-key <ACMECORP-SECRET> --server https://acme.networking4all.com/ov -d networking4all.com --webroot

Alternatively, when having to deal with a lot of separate organizations that need their own account, consider moving to a different ACME client that properly supports multiple accounts natively.

acme.sh doesn't natively support multiple ACME accounts on the same server but acme.sh can run from any user or directory individually. There are two possible workarounds for this.

(Easy method) - Create a separate user account and use a unique acme.sh install from the individual accounts. acme.sh will store all data within its own installation folder and set up crons as usual for each user.
(Advanced method) - Provide a custom config home for acme.sh to use using the --config-home parameter.

Let's say you need to create an OV order example.com for Example Inc. and another OV order networking4all.com for ACME Corporation. Both of these organizations have their own ACME credentials and need their own ACME account. To force acme.sh to create a different account for both orders we can add the following to our command: --config-home /root/example-inc In this example example-inc is simply the directory name of your preference, all the account and certificate data will be stored in these custom directories.

Note that you need to use the arguments --config-home when managing certificates for the accounts too. You also need to create the cron for every account yourself.

Full Examples for this scenario, register the account (only needed once) and order the certificate:

./acme.sh --config-home /root/example-inc/ --server https://acme.networking4all.com/ov --eab-kid <EXAMPLE-INC-KID> --eab-hmac-key <EXAMPLE-INC-SECRET> --register-account
./acme.sh --config-home /root/example-inc/ --server https://acme.networking4all.com/ov --issue -d example.com -w /var/www/example.com/

./acme.sh --config-home /root/acmecorporation/ --server https://acme.networking4all.com/ov --eab-kid <ACMECORP-KID> --eab-hmac-key <ACMECORP-SECRET> --register-account
./acme.sh --config-home /root/acmecorporation/ --server https://acme.networking4all.com/ov --issue -d networking4all.com -w /var/www/networking4all.com/

Then create the cronjobs:

59 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" --config-home /root/example-inc/ > /dev/null
59 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" --config-home /root/acmecorporation/ > /dev/null

Alternatively, when having to deal with a lot of separate organizations that need their own account, consider moving to a different ACME client that properly supports multiple accounts natively.

Simple-acme supports managing multiple accounts natively through commandline arguments. Creating the accounts can only be done using these arguments but once you have created them they become available when using the interactive wizard too.

To create an account add --account <NAME-YOUR-ACCOUNT> --eab-key-identifier <YOUR-KID> --eab-key <YOUR-SECRET> to your register command.

Example:

wacs.exe --register --accepttos --account example-account --eab-key-identifier ABCD1234 --eab-key EFGH5678 --baseuri https://acme.networking4all.com/dv

After this you can simply add --account example-account to your commands and it will use the account for your order or you can select the account using the interactive wizard.