ENTERPRISE This is an EJBCA Enterprise feature.

The Automatic Certificate Management Environment (ACME) is a protocol that a Certificate Authority (CA) and an applicant can use to automate the process of verification of the ownership of a domain (or another identifier) and certificate management.

Supported Operations

EJBCAs ACME implementation currently complies with the final ACME standard IETF - RFC8555. All operations must be called with POST requests. For the directory operation, there is a GET request offered, and for the newNonce operation a GET and HEAD request as well.

Operation	URL	Description	RFC 8555 Reference
directory	/ejbca/acme/directory	Get the directory object listing all ACME operation URLs and the ACME configuration meta data.	7.1.1
newNonce	/ejbca/acme/newNonce	Before any POST action is performed, the client needs to retrieve an anti-replay nonce from the server.	7.2
newAccount	/ejbca/acme/newAccount	Create a new ACME account, or retrieve an existing account, including the account URL and the account ID.	7.3
updateAccount	/ejbca/acme/acct/{accountId}	Update or deactivate an existing account. Change its contact information or agree to the new ACME Terms of Service if they have changed.	7.3.2
newOrder	/ejbca/acme/newOrder	Create a new ACME order for one or multiple domains (or other identifiers). This is the first step to request certificate issuance.	7.4
challenge	/ejbca/acme/acct/{accountId}/chall/{challengeId}	Tell the ACME server that it can validate your challenge response and retrieve the challenge object.	7.5.1
newAuthz	/ejbca/acme/newAuthz	Only if Pre-Authorization Allowed is enabled in the Alias configuration.	7.4.1
finalizeOrder	/ejbca/acme/acct/{accountId}/orders/{orderId}/finalize	Send your Certificate Signing Request (CSR) and let the CA issue your certificate.	7.1.3
revokeCert	/ejbca/acme/revokeCert	Revoke a certificate.	7.6
keyChange	/ejbca/acme/keyChange	Replace the key of an existing account.	7.3.5
cert	/ejbca/acme/cert/{certificateId}	Download a certificate.	7.4.2

URL Endpoints and Aliases

The ACME service is available on the following URLs.

Some ACME clients may cut the URL query string (?configurationId=<alias_name>). Use the URL style with the alias name specified in the URL path.

If the user adds or removes an alias, it is set as the default ACME alias, if the operation results in exactly one alias.

An alias must consist of 1 to 250 alphanumeric non-blank characters case-sensitive including minus '-' and underscore'_'.

Default alias with client authentication	https://<server>:8443/ejbca/acme/directory
Default alias without client authentication	https://<server>:8442/ejbca/acme/directory
Custom alias <alias_name> with client authentication	https://<server>:8443/ejbca/acme/directory?configurationId=<alias_name> or https://<server>:8443/ejbca/acme/<alias_name>/directory
Custom alias <alias_name> without client authentication	https://<server>:8442/ejbca/acme/directory?configurationId=<alias_name> or https://<server>:8442/ejbca/acme/<alias_name>/directory

EJBCA Specifics

Approvals in EJBCA for updating an end entity or certificate revocation cannot be used with ACME. Only approvals for ACME account management are supported.
All ACME operations are performed over the peers protocol. Thus it is perfectly possible to use an external RA running EJBCA as an ACME proxy.
Validators for CAA checking etc. are configured as described in Validators Overview.
You need to set up separate aliases for each end entity profile/certificate profile and CA.
End entities are managed in RA mode, which means end entities are created or reset (status = NEW) before a certificate is enrolled. This implicates that the 'Finish User' function available in the CA settings does not impact certificate enrollment with ACME (see CA Fields). Batch generation (clear text pwd storage) must be enabled in the end entity profile.
Optional EJBCA ACME resources are available with client authentication enforced.

ACME Client Specifics

Each ACME client like Certbot or acme.sh might require their unique restriction to enroll certificates. Additionally, you must ensure that the certificate request posted by the ACME client fulfills the CA and profile restrictions. That is, enroll a certificate for several identifiers, additional subject DN attributes, certificate validity, or restrictions on the key specification used.

Subject-DN attributes and subject-AN DNS entries are configured in the end entity profiles. For more information, see End Entity Profiles Fields and End Entity Profile Configuration.
Key specification and certificate validity (usually < 1 year, or 6 months with Certbot 1.18) are configured in the certificate profiles, see Certificate Profile Fields.

Configuration

End Entity Profile Configuration

Besides requirements depending on your ACME client or individual requirements of your certificate request, the following settings should be used for an end entity profile used with ACME.

A certificate enrolled with ACME for one identifier only, must have at least one additional DNS or IP address SAN field.

Field	Value
Username	Leave empty
Password (or Enrollment Code)	Leave empty
Batch generation (clear text pwd storage)	Enable if you reset the end entity for certificate enrollment. If you do not generate RANDOM with the RA name generate scheme, you must enable this option.
End Entity E-mail	Use, Not Required, Modifiable
Subject DN Attributes
CN, Common name	Required, Modifiable
Default Certificate Profile	<The certificate profile to use>
Default CA	<The CA signing the certificate>
Default Token	User Generated
Other subject attributes
SAN DNS Name or IP address	Not required, Modifiable. Add as many DNS or IP identifiers as you require for your certificates.

Certificate Profile Configuration

Beside your ACME client used or individual requirements of your certificate request, the following settings should be used for a certificate profile used with ACME.

Field	Value
Available Key Algorithms	Choose allowed key algorithms
Available ECDSA curves	Choose allowed ECDSA key algorithms
Available Bit Lengths	Choose desired key length in case of RSA keys
Validity or end date of the certificate	Validity. I.e. 6mo, 1y or 395d.
Extended Key Usage	Server Authentication
Approvals	Clear. Ensure to not select any Approvals as EJBCA supports approvals for ACME account management only.
Available CAs	<The CA signing the certificate>
Single Active Certificate Constraint	Revokes all previously enrolled certificates of an end entity enrolled with this or another certificate profile with this option enabled. Only relevant if the end entity name is not generated randomly using the RA name generation scheme.

Enabling ACME

The ACME protocol is by default disabled. To enable the service, go to CA UI > System Configuration > Protocol Configuration and select Enable for ACME.

images/download/attachments/143748299/Screen_Shot_2018-08-02_at_14.41.27.png

Managing ACME Alias Configurations

Much like other protocols in EJBCA, several different ACME configurations can be maintained at the same time using aliases.

To configure ACME, select ACME Configuration under the System Configuration menu.

Before an ACME alias can be used it must be edited and stored, even if its configuration remains unchanged.

Global Fields

The following fields are defined globally for all ACME operations.

Field	Description
Default ACME Configuration	The configuration to use without alias specified.
Replay Nonce Validity Number	Defines the validity in milliseconds of a generated replay nonce.

ACME Alias Configuration

The following displays an ACME Alias configuration with username selection by the subject DN CN attribute and any type of DNS identifier.

images/download/attachments/143748299/acme_alias-7-11-0.png

The following table lists ACME specific fields for each alias in more detail.

Field	Description
RA Name Generation Scheme	DN: Will take a part of the request DN, and use it as the username (use the list to choose which parts). Several DN attributes can be specified to have a fall-back. For example: UID;SN;CN. First, try UID. If it does not exist try SN, etc. RANDOM (default): Uses the generated 43 character long ACME order ID. FIXED: Enter the DN attributes manually as a semicolon-delimited String (e.g. CN;UID;SN), instead of adding the values using the Add button when the DN optionn is selected. USERNAME: Use the entire request DN as username. It is possible to use a constant username, as long as no DN attribute is specified, i.e. myUser. Enable Batch generation in the end entity profile, if you don't use RANDOM usernames (see End Entity Profile Configuration).
RA Name Generation Prefix	Specify a prefix to the generated username. '${RANDOM}' can be used to have 12 random chars as prefix.
RA Name Generation Postfix	Specify a postfix to the generated username. '${RANDOM}' can be used to have 12 random chars as postfix.
End Entity Profile	The end entity profile to use for end entities enrolled using this alias. The CA signing the certificate is the default CA of this end entity profile, and the certificate profile used for the certificate is the default certificate profile of this end entity profile. Keep in mind that ACME identifiers (i.e. DNS name, IP number) to be included in the certificate are included in its SAN if specified in CSRs SAN (normal case). At least one identifier is written into the subject DN (i.e. certbot only uses SANs in the CSR). Multiple identifiers are written into the subject DN, if the CSRs subject DN contains multiple CNs.
Pre-Authorization Allowed	Pre-authorization, as defined in section 7.4.1 of RFC 8555. The ACME client may authorize the certificates identifiers before order creation.
Wildcard Certificate Issuance Allowed	Whether this alias can be used to issue certificates with wildcard DNS names in their SANs. Refer to section 7.1.3 of RFC 8555.
Wildcard Certificate with http-01 Challenge Allowed	If disabled, no http-01 challenge for identifiers with a wildcard (i.e. *.primekey.com) is generated. Only active if 'Wildcard Certificate Issuance Allowed' is enabled. Default: enabled.
DNS identifier challenge types	Select Any type to create all challenge types. If only a certain challenge type is required, select for example the http-01 or dns-01 challenge only.
Site URL	URL to a website describing this CA. Optional. Refer to section 7.1.1 of RFC 8555.
Terms of Service URL	URL to your terms of service for ACME. Refer to section 7.1.1 of RFC 8555.
Changes of Terms of Service URL	URL to advise how to handle changes of your terms of service for ACME. Refer to section 7.3.1 of RFC 8555.
Require client approval for Terms of Service changes	Specifies whether users must approve the new version if the Terms of Service URL is changed. Default: enabled.
Agree to new Terms of Service allowed	Specifies whether users are allowed to agree to new Terms of Service after they have changed. ACME clients must request the updateAccount resource with termsOfServiceAgreed set to true. If not allowed, clients have to request a new account (including new keys). Only active if Require client approval for changes of Terms of Service is enabled. Default: enabled.
DNS Resolver	A specified DNS resolver, used when processing dns01 challenges.
DNS Port	Port used for DNS communications.
DNSSEC Trust Anchor	The ICANN trust anchor, configurable should it ever change.
Retry After	Value used to indicate that client should try polling the authorization endpoint again after a while (in seconds). Default is 0 and this is used mainly for clients such as cert-manager which send post-as-get request while waiting for ACME server to prepare the challenge.
Authorized Redirect Ports	List of authorized ports for client side redirects for the http-01 challenge validation for DNS identifiers. Default is 22,25,80,443. Leave empty for no restrictions.
Order Validity	The time span within the challenges for the orders identifiers have to be completed. Format is human readable validity with second precision, i.e. 10d 12h or 30s 30m 1h. The format string is normalized when the form data is stored. Default value is 1h.
Require approval for account registration	Approval profile to be applied for ACME account registration, see Approvals. Default: None.
Require approval for account key change	Approval profile to be applied for ACME account key change, see Approvals. Default: None.
Require client certificate	The ACME client must authenticate using a valid client certificate and authorization to view, create and edit end entities as well as access the signing CA.
Preferred Root CA subject DN	If there are cross certificate chains present for the designated CA, then this setting may be used to mandate a single cross certificate chain for all clients requesting through this configuration. It has a default value of "default" and to remove any such restriction delete the value and save the configuration. When it has a default value, finalizeOrder contains the link to the chain with default CA certificate chain and link headers in cert response contains links to alternate chains as mentioned section 7.4.2 of RFC 8555 . If a chain is mandated finalizeOrder contains the link to the chain with configured cross chain and cert response do not include any links for alternate certificate chains.
Require External Account Binding	External Account Binding (EAB), as defined in section 7.4.3 of RFC 8555.

ACME with client authentication

If Require client certificate is enabled, an ACME client requires a valid client certificate for HTTPs client authentication and sufficient access rules for certificate enrollment or revocation and other functions available with ACME. If the client certificate is revoked, requests to ACME resources, except the directory and newAccount resource will fail.

Grant this set of access rules to the client certificate used for ACME.

/ca_functionality/create_certificate/
/ra_functionality/create_end_entity/
/ra_functionality/edit_end_entity/
/ra_functionality/view_end_entity/
/ra_functionality/revoke_end_entity/
/ca/${Name of CA}/
/endentityprofilesrules/${Name of EEP}/create_end_entity/
/endentityprofilesrules/${Name of EEP}/edit_end_entity/
/endentityprofilesrules/${Name of EEP}/view_end_entity/
/endentityprofilesrules/${Name of EEP}/revoke_end_entity/

Managing ACME External Account Bindings (EAB)

If Require External Account Binding is disabled, EAB requests nested in the ACME newAccount request are not considered. Otherwise, an ACME newAccount request without a nested EAB request will fail with an HTTP status code 400 (Bad Request) and the ACME error externalAccountRequired, if the client does not send a valid EAB with the newAccount request.

EJBCA supports the ACME compliant EAB with symmetric key MAC protected EAB requests. Additionally, EJBCA supports EAB with asymmetric private key signature protected EAB requests.

Combine ACME EAB with General Account Binding

The ACME EAB with symmetric key supports the combination with general external account bindings, see External Account Bindings.

The base64Url encoded Key Identifier of the ACME EAB must match one of the external account binding IDs, available in the EAB namespace configured in the relevant certificate profile. It does not matter if the ACME account was registered with this key identifier or if the value was stored after the registration.

ACME EAB with Symmetric Key Configuration

images/download/attachments/143748299/EJBCA-EE-7-7-1-ACME-EAB-symmetric-configuration-sample.png
Initial ACME EAB with symmetric key configuration.

RFC8555 compliant ACME EAB

Field	Description
EAB Type	RFC8555 compliant (MAC - symmetric key)
Generate Key	Generates a 256 bits AES symmetric key. The key is stored either encrypted or not (see Encrypt Key). It is rendered as base64Url encoded value in the text field Insert base64Url Key. The SHA-1 hash of the AES key is generated and stored as a base64Url encoded value as key identifier and rendered in the text field Key Identifier as is.
Key Identifier	The secret key identifier of the symmetric key. The value must not be empty, but max. 256 characters long and base64Url encoded. The value does not need to be a fingerprint depending on any known algorithm. It is entered by the user. Since the EAB is stored at the ACME alias configuration, EJBCA only verifies, that the EAB message contains the correct key identifier.
MAC Algorithm	The secret MAC algorithm to sign the MAC protected EAB request (only HS256 at the time).
Encrypt Key	Encrypts the shared key in the data store if selected (rendered in clear text in the GUI).
Encryption Key	The crypto token used to encrypt / decrypt the shared key.
Encryption Key Alias	The key alias of the crypto tokens key pair used to encrypt / decrypt the shared key.
Upload PEM/DER Key	Upload PEM or DER encoded symmetric AES key or a byte sequence. If a key is uploaded, the Insert base64Url Key below does not need to be specified and is populated after the form is saved. To generate a 192 bits AES key file, use 'openssl rand 192 > name.key' or 'cat /dev/urandom \| head -c 192 > name.key'.
Insert base64Url Key	Symmetric key. The value must not be empty (except a file is uploaded), but max. 512 characters long and base64Url encoded.

Key Identifier, MAC Algorithm and Insert base64Url Key must be shared with the ACME account holders in order to request a newAccount resource with a valid EAB request. For information on the message format, see newAccount request with RFC8555 compliant EAB.

ACME EAB with asymmetric private/public key configuration.

images/download/attachments/143748299/EJBCA-EE-7-7-1-ACME-EAB-asymmetric-configuration-sample.png
Initial ACME EAB with symmetric key configuration.

Asymmetric key signature protected EAB

Field	Description
EAB Type	Certificate / Public Key (asymmetric account key signature)
Use public key	Set to true, if you want to upload a public key or set to false if you want to upload an X.509 certificate. If set to true and a certificate is uploaded, only the public key is stored and the fingerprint is generated using the signature algorithm selected.
Signature Algorithm	The secret signature algorithm to sign the signature protected EAB request. It is considered only if a public key is used. Otherwise, this field will be filled with the certificate's signature algorithm after the form is saved.
Upload PEM/DER Public Key or Certificate	Upload PEM or DER encoded RSA or ECDSA public key or X.509 certificate. If a certificate or key is uploaded, the text fields Public Key or Certificate Fingerprint and Insert PEM Public Key or Certificate below do not need to be filled manually but are populated after the form is saved.
Public Key or Certificate Fingerprint	The public key or certificate fingerprint. The value must not be empty, but max. 256 characters long and base64Url encoded. The value does not need to be a fingerprint depending on any known algorithm. It can be overwritten by the user. Since the EAB is stored at the ACME alias configuration, EJBCA only verifies, that the EAB message contains the correct string. This string might be used as a secret message, which is transmitted on a separate channel.
Insert PEM Public Key or Certificate	PEM formatted X.509 certificate or RSA or ECDSA public key including boundaries. The value must not be empty, but max. 4096 characters long.

Public Key or Certificate Fingerprint, Signature Algorithm (in case of public key) and Insert PEM Pulbic Key or Certificate must be shared with the ACME account holders in order to request a newAccount resource with a valid EAB request. The EAB request must be signed either with the certificate's signature algorithm or in the case of a public key, the one given by the user. For more information on the message format, see newAccount request with EAB with asymmetric key signature.

Identifiers and Challenge Validation

EJBCA currently supports the validation of domain and IP identifiers.

Domain identifiers can be validated either using the http-01 or dns-01 challenge as defined in section 8 of RFC 8555. IPv4 or IPv6 identifiers can be validated with http-01 challenge only as defined in section 5 of RFC 8738 (JDK8). IPv6 identifier challenge validation requires a running application server with IPv6 enabled (-Djava.net.preferIPv6Addresses=true, Wildfly14 can be operated with IPv4 or IPv6 only).

HTTP Challenge (http01)

If the client chooses to use the http-01 challenge type, it intends to prove that it controls the domain or IP requested in the certificate by provisioning a resource under the same domain name or IP and port 80, i.e. http://example.org/.well-known/acme-challenge.

DNS Challenge (dns01)

If the client chooses to use the dns-01 challenge type, it instead obligates itself to supply a TXT record containing the same token response as described above. As per RFC 8555, DNSSEC is required for dns01 challenges.

Approvals

Approvals can be used with ACME account management.

Approvals for the newAccount Resource

If approvals are used for the newAccount resource, requests to this resource return an HTTP 500 (Internal Server Error) response including an ACME problem message of type urn:ietf:params:acme:error:serverInternal indicating the state of the created approval request and its request ID. For example, A request to register your ACME account has been sent for approval. RequestID=123456789 after the first ACME resource request has been posted. Further requests return responses in the same matter indicating the state of the approval request either with state PENDING, REJECT, or EXPIRED. If the approval has been accepted, a request to the newAccount resource creates the account and returns the HTTP 201 (Created) as expected. If an approval has expired, it is no longer possible to register the keys for this account and you must generate new keys.

Approvals for the keyChange Resource

If approvals are used for the keyChange resource, requests to this resource return an HTTP 500 (Internal Server Error) response including an ACME problem message of type urn:ietf:params:acme:error:serverInternal indicating the state of the created approval request and its request ID, see example in Approvals for the newAccount Resource. If an approval request has expired, it is renewed automatically if the keyChange resource is requested.

Terms of Service

When an ACME account is initially registered using the newAccount resource, the account holder must agree to ACME service Terms of Service. If 'Require client approval for changes of Terms of Service' is enabled and the Terms of Service have changed, requesting ACME resources except the newAccount resource will fail. To agree to the new ACME service Terms of Service, clients must either register a new account using the newAccount resource (with new keys) or agree to the new Terms of Service using the updateAccount resource (see Workflow examples). Therefore Agree to new Terms of Service allowed must be enabled.

Compatibility with ACME Clients

EJBCA is compatible with the following ACME clients (listed in Letsencrypt's list of compatible ACME clients). For information on installation and use, see the respective ACME client section:

Swagger UI

Swagger UI allows you to visualize and interact with the API’s resources. The Swagger UI playground is available in your browser on the URL https://localhost:8443/ejbca/swagger-ui (use port 8443 since ACME uses client certificate authentication).

You can switch between displaying ACME or the REST API using the Swagger UI Select a spec list.

images/download/attachments/143748299/image2018-10-9_10-57-19.png

The Swagger UI is only available if you build EJBCA in non-production mode, i.e. with ejbca.productionmode=false set in conf/ejbca.properties.
The Swagger UI for ACME will only be available if ACME is activated as a protocol, see Enabling ACME.

Request Examples

The following lists ACME operations to perform in order to get a certificate. For newAccount and for revokeCert requests there MUST be a 'jwk' field, otherwise a 'kid' field.

getDirectory request

Returns the URLs for each ACME operation and the service metadata.

GET /acme/directory HTTP/1.1
 
{  
   "newNonce":"https://footrust.local:8443/ejbca/acme/newNonce",
   "newAccount":"https://footrust.local:8443/ejbca/acme/newAccount",
   "newOrder":"https://footrust.local:8443/ejbca/acme/newOrder",
   "newAuthz":"https://footrust.local:8443/ejbca/acme/newAuthz",
   "revokeCert":"https://footrust.local:8443/ejbca/acme/revokeCert",
   "keyChange":"https://footrust.local:8443/ejbca/acme/keyChange",
   "meta":{  
      "termsOfService":"https://footrust.com/acme/terms",
      "website":"https://footrust.com",
      "caaIdentities":[  
         "footrust.com"
      ],
      "externalAccountRequired":false
   }
}

newAccount request

Creates a new ACME account to EJBCA and returns it with the response. EJBCA uses a public key to verify the JWS (that is, the jwk element of the JWS header) to authenticate future requests from the account. EJBCA supports RSA and EC key types. If the account with this key already exists, it is returned with the response.

POST https://localhost:8442/ejbca/acme/newAccount HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/newAccount"
  }),
  "payload": base64url({
    "contact": [
      "mailto:cert-admin@example.com"
    ],
    "termsOfServiceAgreed": true
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

newAccount request with RFC8555 compliant EAB

Creates a new ACME account to EJBCA and returns it with the response.

The nested EAB request is signed using a symmetric key and HMAC algorithm shared by the CA.

POST https://localhost:8442/ejbca/acme/newAccount HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/newAccount"
  }),
  "payload": base64url({
    "contact": [
      "mailto:cert-admin@example.com",
      "tel:+12025551212"
    ],
	"termsOfServiceAgreed": true,
	"externalAccountBinding": {
         "protected": base64url({
           "alg": "HS256",
           "kid": /* key identifier from CA */,
           "url": "https://example.com/acme/newAccount"
         }),
         "payload": base64url(/* same as in "jwk" above */),
         "signature": /* MAC using MAC key from CA */
       }
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

newAccount request with EAB with asymmetric key signature

Creates a new ACME account to EJBCA and returns it with the response.

The nested EAB request is signed by the same JWK that signed the outer message. Compared to the standard EAB request (see above), this EAB requests payload contains a map including the account key to be registered. Additionally, this map contains the public key or certificate fingerprint shared by the CA and the signature over the account key by a private key shared with the CA and the agreed signature algorithm.

POST https://localhost:8442/ejbca/acme/newAccount HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "jwk": {...},
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/newAccount"
  }),
  "payload": base64url({
    "contact": [
      "mailto:cert-admin@example.com",
      "tel:+12025551212"
    ],
	"termsOfServiceAgreed": true,
	"externalAccountBinding": {
 	"protected": base64url({
        "alg": "HS256",
        "url": "https://example.com/acme/newAccount"
      }),
      "payload": base64url({
        "key": / * same as in "jwk" above * /,
        "cf":  / * certificate or public key fingerprint shared by the CA * /,
        "aks": / * signature of the account key using the signature algorithm 
                   and private key corresponding to the public key sent to the ACME CA * /,
      }),
      "signature": / * MAC using same MAC key that signed the outer JWS message. * /
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request

Updates an ACME accounts contact information.

POST https://localhost:8442/ejbca/acme/acct/evOfKhNU60wg HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
  "payload": base64url({
    "contact": [
      "mailto:cert-admin@example.com",
    ]
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request and agree to new Terms of Service

Updates an ACME agreement to the new Terms of Service if they have changed. This is a non-RFC compliant function. To use this newAccount request Require client approval for changes of Terms of Service and Agree to new Terms of Service allowed must be enabled.

POST https://localhost:8442/ejbca/acme/acct/evOfKhNU60wg HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "6S8IqOGY7eL2lsGoTZYifg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
    "termsOfServiceAgreed": true
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

updateAccount request and account deactivation

Deactivates an ACME account (not reversible).

POST https://localhost:8442/ejbca/acme/acct/evOfKhNU60wg HTTP/1.1
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "ntuJWWSic4WVNSqeUmshgg",
    "url": "https://example.com/acme/acct/evOfKhNU60wg"
  }),
  "payload": base64url({
    "status": "deactivated"
  }),
  "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

newOrder request

Creates a new ACME order.

POST /acme/newOrder HTTP/1.1
Content-Type: application/jose+json
 
{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "5XJ1L3lEkMG7tR6pA00clA",
   "url": "https://example.com/acme/new-order"
 }),
 "payload": base64url({
   "identifiers": [
	 { "type": "dns", "value": "www.example.org" },
	 { "type": "dns", "value": "example.org" }
   ],
   "notBefore": "2016-01-01T00:00:00Z",
   "notAfter": "2016-01-08T00:00:00Z"
 }),
 "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}

The newOrder response contains information about challenges. For more information, refer to section 7.5.1 of RFC 8555.

newAuthz request

Request a pre-authorization for an identifier (one request per identifier).

POST /acme/newAuthz HTTP/1.1
Host: example.com
Content-Type: application/jose+json
 
{
  "protected": base64url({
    "alg": "ES256",
    "kid": "https://example.com/acme/acct/evOfKhNU60wg",
    "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
    "url": "https://example.com/acme/newAuthz"
  }),
  "payload": base64url({
    "identifier": {
      "type": "dns",
      "value": "example.org"
    }
  }),
  "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
}

challenge request

Call EJBCA's ACME service to verify the challenge response, that proves you possess control over the domain.

POST /acme/acct/{accountId}/chall/{challengeId} HTTP/1.1
Content-Type: application/jose+json
 
{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
   "url": "https://example.com/acme/chall/prV_B7yEyA4"
 }),
 "payload": base64url({}),
 "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
}

finalizeOrder request

To generate the certificate.

POST /acme/acct/{accountId}/orders/{orderId}/finalize HTTP 1.1
Content-Type: application/jose+json
 
{
 "protected": base64url({
   "alg": "ES256",
   "kid": "https://example.com/acme/acct/evOfKhNU60wg",
   "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
   "url": "https://example.com/acme/order/TOlocE8rfgo/finalize"
 }),
 "payload": base64url({
   "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
 }),
 "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
}

The response to the finalizeOrder call is the certificate.

HTTP Status Codes

HTTP Status Code	Description
200	Success
201	Created
204	No content
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
409	Conflict
500	Internal Server Error

Supported Operations

URL Endpoints and Aliases

EJBCA Specifics

ACME Client Specifics

Configuration

End Entity Profile Configuration

Certificate Profile Configuration

Enabling ACME

Managing ACME Alias Configurations

Global Fields

ACME Alias Configuration

ACME with client authentication

Managing ACME External Account Bindings (EAB)

Combine ACME EAB with General Account Binding

ACME EAB with Symmetric Key Configuration

RFC8555 compliant ACME EAB

ACME EAB with asymmetric private/public key configuration.

Asymmetric key signature protected EAB

Identifiers and Challenge Validation

HTTP Challenge (http01)

DNS Challenge (dns01)

Approvals

Approvals for the newAccount Resource

Approvals for the keyChange Resource

Terms of Service

Compatibility with ACME Clients

Swagger UI

Request Examples

getDirectory request

newAccount request

newAccount request with RFC8555 compliant EAB

newAccount request with EAB with asymmetric key signature

updateAccount request

updateAccount request and agree to new Terms of Service

updateAccount request and account deactivation

newOrder request

newAuthz request

challenge request

finalizeOrder request

HTTP Status Codes

Related Content