Skip to main content
Skip table of contents

ACME with


The following covers how to install and use the ACME client

For general information on ACME (Automatic Certificate Management Environment), see ACME. is an ACME protocol client written in Shell (Unix shell) language, compatible with bash, dash, and sh shells. For more information, refer to on GitHub

Installation and Operation

Supported Versions

EJBCA Enterprise supports version 3.0.6. Download or install from the GitHub repository on GitHub.

Do not use an version prior to 3.0.6 due to the vulnerability described on on GitHub.

Supported Features

The following highlights supported features:

  • supports EJBCA approvals for ACME account management.
  • supports certificate enrollment for IP identifiers as specified in RFC 8738.
  • supports certificate enrollment for DNS identifiers with the tls-alpn-01 challenge as specified in RFC 8737.
  • supports EAB (External Account Bindings) as specified in RFC 8555 section 7.3.4, as well as with public key or certificate.


The following lists prerequisites:

  • Linux-based OS, Mac OSX, or MS Windows including Cygwin. For more information, refer to the Tested OS section on on GitHub.  
  • System tools like curl or wget.
  • Super user permissions.
  • A web server like Apache2 or Nginx.


Download and unpack the latest release from

Post Installation

Set the ACME endpoint URL for

Default ACME URL defined in version of EJBCA is https://localhost:8442/ejbca/acme/directory.

You can use the --server option with to specify this URL or edit the line 24 $CA_EJBCA variable.

Create Challenge Directory for Your Web Server

If you want to use the http-01 challenge validation (default for, make sure that can write to the challenge folder of the web server, usually located in /var/www/html/.well-known/acme-challenge.

(warning) The web server must open port 80 to serve the challenge token with HTTP: http://<hostname>/.well-known/acme-challenge/<filename>.

$ mkdir -p /var/www/html/.well-known/acme-challenge


To reset, move or delete all files or folders below ~/

$ rm -rf ~/*

Show Help with -h

Use the help for detailed information and refer to more information on on GitHub

$ ./ -h

Run Convenience Commands supports lots of single functions like generating account keys, domain keys, or CSRs, or call ACME resources as well as convenience commands which process an entire ACME workflow with a single CLI call like the --issue option command. --issue option command workflow:

  1. If no ACME account is registered already, an account key pair is generated locally by to register a new ACME account at the CA server (use the -ak  option for account key specification). Otherwise tries to recover an existing account using the existing account key stored on the system.
  2. requests the order resource of the CA server and receives the newly created order object including all authorizations and challenges required to enroll the certificate for the given identifiers.
  3. places the challenge token in the challenge directory of the local web server.
  4. requests the CA servers challenge resource.
  5. EJBCA verifies the challenge response with HTTP.
  6. deletes the challenge token.
  7. generates a key pair and posts a CSR for the certificate to be enrolled to the CA servers finalize resource.
  8. EJBCA enrolls and stores the certificate.
  9. downloads the certificate using the URL in the order object received with the finalize resource response.

    $ ./ --issue -d -w /var/www/html --insecure --force --debug 3 -k ec-256 -ak 2048

After was reset, the script registers a new ACME account after it generated a new account key specified with the -ak option, to enroll a certificate for with the key specification given with the -k option.

If you require additional subject-DN attributes or additional certificate extensions to fulfill the end entity and certificate profile restrictions, generate your CSR with the --create-csr option command and enroll your certificate using the -csr option. 

Account Registration with Approvals and Certificate Enrollment

Select an approval profile in the ACME alias configuration field Require approval for account registration. For more information on ACME alias configuration fields, see ACME.

Make sure that you do not have an account already registered. For information on resetting, see ACME with

Repeat the convenience command described in ACME with Convenience Commands above.

$ ./ --issue -d -w /var/www/html --insecure --force --debug 3 -k ec-256 -ak 2048 will log an error message as follows.

$ [...] Register account Error: {"detail":"A request to register your ACME account has been sent for approval. RequestID=694243043","type":"urn:ietf:params:acme:error:approvalRequiredForAccountRegistration"}

Repeat the command after your approval has been approved by the administrators specified in the approval profile. Your account is then registered and your certificate is enrolled.

Run Commands

The following outlines commands for handling ACME accounts and certificates.

Register an ACME Account

To register an ACME account, run:

$ ./ --register-account --insecure --force --email

The register command can be used with approvals as well as EAB. Note that the --issue option command does not seem to recognize the --eab options.

--email specifies the account contact information.

$ ./ --register-account --insecure --force --eab-kid 9UiJbZzO7WtuAU4IDsxNsNaMFl4 --eab-hmac-key Xs8Yi_fYdxWDRKupHMpjewjHAvduSAd1d5QeEKucs5E confirms the account registered showing the account thumbprint.

[...] Create account key ok.
[...] Registering account: https://localhost:8442/ejbca/acme/directory
[...] Registered
[...] ACCOUNT_THUMBPRINT='Fg4_hKmJafc0N_Gviqo-8Xj6GtTDiW4lASS8f6Gb9Lw'

Update an ACME Account

To update the account holders contact information:

$ ./ --update-account --insecure --force --email confirms the account update showing the account URL (including the KID).

$ [...] account update success for https://localhost:8442/ejbca/acme/acct/KpKGJr3I3auSKxvQBK2PVA.

Deactivate an ACME Account

Deactivate the account if you do not want to enroll further certificates with this account.

$ ./ --deactivate-account --insecure --force confirms the account deactivation showing the account URL (including the KID).

$ [...] Deactivate update success for https://localhost:8442/ejbca/acme/acct/KpKGJr3I3auSKxvQBK2PVA.

Certificate issuance with the http-01 challenge

Certificates can be issued using the http-01 challenge. stores the challenge authorization for the DNS or IP identifier in the local web server's root.

$ ./ --issue --insecure --webroot /var/www/html -d

Certificate issuance with the tls-alpn-01 challenge

Certificates for DNS identifiers can be issued using the tls-alpn-01 challenge in standalone mode. launches a TLS server with a self-signed certificate holding the challenge authorization for the identifier on port 443.

The challenge is performed against the IP resolved by the DNS service specified in the ACME alias fields 'DNS Resolver' and 'DNS Port'. DNSSEC is optional and in case must be supported by the DNS service.

$ ./ --issue --insecure --alpn -d

Certificate Revocation

Revocation reasons can be specified from 0 (unspecified) to 10. For more information, refer to

$ ./ --revoke --insecure --domain --ecc --revoke-reason 0

Certificate Renewal

Do not delete the certificate before renewal.

Keep in mind that you cannot use RANDOM usernames if the issuing CA enforces a unique subject-DN for each certificate enrolled.

$ ./ --renew --insecure --domain --ecc --force

Certificate Removal

With the following option command, the certificate is removed from certificate list.

$ ./ --remove --domain --ecc

Note that the key pair, CSR, and certificate are not deleted.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.