ACME EAB Accounts

This section details how to configure External Account Bindings (EAB).

Introduction

An External Account Binding (EAB) is a pair of credentials made of a MAC Key ID (public identifier) and a MAC Key (shared secret), generated by Horizon and handed over to an ACME client to be used when registering an ACME account, as described in RFC 8555, section 7.3.4. Binding an ACME account to an EAB allows Horizon to:

  • Control which clients can create ACME accounts, when the Require External Account Binding option is enabled on an ACME profile;

  • Enforce additional constraints on the requests carried by the ACME accounts bound to the EAB.

Each EAB account is attached to an EAB policy, which adds a shared layer of constraints on top of the EAB account’s own constraints.

An EAB account can only be used by ACME clients if its status is Valid and its expiration date, if any, is not passed. An expired EAB account behaves like a non-valid one: it blocks the enrollment of new ACME accounts and the use of linked ACME accounts.

Prerequisites

EAB Policy

How to create an EAB account

1. Log in to Horizon Administration Interface.

2. Access ACME from the drawer or card: Protocols  ACME, then open EAB Accounts from the drawer or card.

3. Click on Add an EAB account.

4. Fill in the mandatory fields.

General

  • Name* (string input):
    Enter a meaningful EAB account name. It must be unique for each EAB account. The name can no longer be edited after creation.

  • Description (string input):
    Enter a description of the EAB account.

  • EAB Policy* (string select):
    Select an EAB policy previously created. Every constraint defined by the selected policy applies in addition to the EAB account’s own constraints. If no EAB policy matches your needs, click on Create an EAB policy next to the field to create a new one on the fly: the newly created policy is automatically selected.

  • MAC Key Algorithm* (select):
    Select the algorithm used to generate the MAC Key: HS256, HS384 or HS512. The default value is set to HS256.

  • Validity Duration (finite duration):
    Specify the validity duration of the EAB account, starting from its creation. Once the duration is elapsed, the EAB account is considered expired and can no longer be used. Leave empty to create the EAB account without expiration date. The validity duration can only be set at creation; use the renew action to extend or remove it afterward.

Additional Account Constraints

The following constraints apply in addition to those of the attached EAB policy and of the selected ACME profile: when both levels define constraints, requests must satisfy both of them. Leave a constraint empty to impose no restriction at this level.

  • Allowed Profiles (multiselect):
    Restricts the ACME profiles allowed for this EAB account. If the linked EAB policy also defines a list, only profiles present in both lists will be accepted. Leave empty for no additional restriction; the linked EAB policy’s list still applies.

  • Order Identifier Constraint (regex):
    Every identifier in an order must match this regular expression, in addition to any expression set on the EAB policy.

  • Email Constraint (regex):
    Every contact email address (provided at ACME account creation) must match this regular expression, in addition to any expression set on the EAB policy.

  • Validation Methods (multiselect):
    Limits the validation methods allowed for this EAB account, in addition to those of the EAB policy and the selected ACME profile. Leave empty for no additional restriction.

5. Click on the save button.

The MAC Key ID and the MAC Key are displayed once, right after the save, in a dedicated window: copy them and hand them over to the ACME client owner. Once the window is closed, the credentials cannot be displayed again.

From the EAB Accounts list, you can:

  • edit an EAB account Edit EAB account,

  • duplicate it Duplicate EAB account,

  • delete it Delete EAB account,

  • change its status Change EAB account status,

  • renew its MAC Key Renew EAB account,

  • and display the ACME accounts linked to it Display ACME accounts linked to an EAB account

You won’t be able to delete an EAB account if it is linked to at least one ACME account whose status is Valid, Deactivated or Suspended.

How to search EAB accounts

1. Log in to Horizon Administration Interface.

2. Access ACME from the drawer or card: Protocols  ACME, then open EAB Accounts from the drawer or card.

The EAB Accounts list can be searched using the search bar, in intermediate or expert mode.

Intermediate search

The intermediate search allows filtering the list by name and status.

Expert search

The expert mode allows building HEABQL (Horizon External Account Binding Query Language) queries, by combining elements, conditions and operators. The query structure is the following:

  • <element> <condition> <"value"> (<operator> [<element> <condition> <"value">])

Table 1. Table element
Element Description Available conditions

id

EAB account ID

equals, not equals, contains, not contains, in, not in

name

EAB account name

equals, not equals, contains, not contains, in, not in

status

EAB account status

equals, not equals, contains, not contains, in, not in

mackey.algorithm

MAC key algorithm

equals, not equals, contains, not contains, in, not in

expiration.date

EAB account expiration date

equals, before, after, not before, not after, exists, not exists

created.at

EAB account creation date

equals, before, after, not before, not after

eab.policy

EAB policy name

equals, not equals, contains, not contains, in, not in

validation.methods

EAB validation methods

exists, not exists, contains, not contains, in, not in
Table 2. Table operator
Operator Description

or

The EAB account matches at least one of the combined criteria

and

The EAB account matches all the combined criteria

MAC Key management

The EAB account credentials are materialized by:

  • The MAC Key ID, which is the public identifier of the EAB account, provided by the ACME client when registering an ACME account;

  • The MAC Key, which is the shared secret used by the ACME client to sign the registration request.

The MAC Key ID and the MAC Key are only displayed once, right after the EAB account creation and after each MAC Key renewal, in a dedicated window where they can be copied. Once this window is closed, the credentials can no longer be displayed from the Horizon Administration Interface: if the MAC Key is lost, renew the EAB account to generate a new one.

When duplicating an EAB account, a new MAC Key is generated: the copy does not share the credentials of the original EAB account.

The MAC Key must be kept secret: any party holding it can bind an ACME account to the EAB account and therefore benefit from its authorizations. If the MAC Key is suspected to be disclosed, renew it or compromise the EAB account.

Both values are only known by Horizon and the ACME client. At ACME account registration, the client sends the MAC Key ID and signs the registration request with the MAC Key; the MAC Key itself never appears in any ACME protocol exchange.

How to renew an EAB account

1. Click on Renew EAB account from the EAB account form or the EAB Accounts list.

2. Fill in the optional fields:

  • MAC Key Algorithm (select):
    Select a new algorithm to generate the MAC Key: HS256, HS384 or HS512. Leave empty to keep generating the key with the current algorithm.

  • New validity duration (finite duration):
    Specify a new validity duration, starting from the renewal. Leave empty to renew the EAB account without any expiry.

3. Click on the confirm button.

Renewing an EAB account generates a new MAC Key while keeping the MAC Key ID unchanged. ACME accounts already bound to the EAB account are not impacted: only registrations performed with the previous key are rejected. The new MAC Key is displayed once, right after the renewal, in the same dedicated window as at creation: copy it and hand it over to the ACME clients that should keep using this EAB account. The number of key regenerations is displayed in the EAB account form.

ANSSI recommends a validity period of no more than 3 years for this kind of secret.

EAB account statuses

The status of an EAB account can be changed by clicking on Change status from the EAB account form or the EAB Accounts list.

The following statuses are available:

Status

Description

Valid

Can enroll new ACME accounts, and the linked ACME accounts operate normally.

Disabled

Temporarily disables the account for any reason. Blocks the enrollment of new accounts and the use of linked accounts.

Suspended

Temporarily disables the account in case of a suspected compromise. Blocks the enrollment of new accounts and the use of linked accounts.

Deactivated

Deactivating this account deactivates all linked ACME accounts. Only compromising it will remain possible afterwards.

Compromised

Compromising an EAB forces the compromise of all linked ACME accounts and triggers the revocation of the certificates they enrolled. This status is irreversible.

Compromising an EAB account

When setting the status to Compromised, the following fields are requested:

  • Revoke certificates issued after (date input):
    Certificates issued after this date and time will be revoked. Leave empty to revoke all certificates linked to this EAB account.

  • Revocation reason (select):
    The revocation reason applied to every certificate revoked through this compromise, on this EAB account and on all the ACME accounts linked to it.