English German
Breadcrumbs

ACME Client

The ACME Client enables IGEL OS 12 devices to request and renew client certificates automatically through the Automatic Certificate Management Environment (ACME) protocol. This article describes how to deploy the CA certificate, configure an ACME certificate request, verify the result, and troubleshoot certificate enrollment.

The IGEL ACME Client supports the http-01 challenge. Other ACME challenge types are not supported.

How the ACME Client Works

The ACME Client performs the following tasks:

  • Registers an account with the configured ACME server.

  • Requests a certificate for one or more configured device names.

  • Stores the certificate and private key on the device.

  • Checks the certificate expiration date at a configured interval.

  • Requests a renewed certificate during the configured renewal period.

  • Supports External Account Binding (EAB) with ACME Client 1.0.0+3 or later.

For each certificate instance, the client stores the generated files in:

/wfs/acme_certificates/<directory>/

For the default instance and directory, the files are:

/wfs/acme_certificates/default/client.cert
/wfs/acme_certificates/default/client.key

Protect the private key from unauthorized access. Do not copy private keys to logs, documentation, or unsecured storage.

Prerequisites

  • Configure an ACME server that supports the http-01 challenge.

  • Create DNS records for the names requested by each device.

  • Obtain the ACME directory URL.

  • Obtain the CA root certificate if the ACME server certificate is not trusted by default.

  • For EAB, use ACME Client 1.0.0+3 or later and obtain the EAB key identifier and HMAC key from the ACME server administrator.

Deploy the CA Root Certificate

If the ACME server uses a private CA, upload the CA root certificate to the UMS and assign it to the target devices. For details, see Upload and Assign Files in the IGEL UMS Web App.

Store the certificate in a protected location such as:

/wfs/ca-certs/acme-root-ca.crt

Ensure that the ACME Client can read the file. The path configured under CA Bundle must match the deployed file path.

Install and Configure the ACME Client

  1. Import the ACME Client from the IGEL App Portal and assign the required version to the IGEL OS devices. For instructions, see How to Import IGEL OS Apps from the IGEL App Portal.


  1. Create an IGEL OS 12 profile for the ACME Client.


  1. Enable Manage certificates with ACME.


  1. Edit the ACME Certificate under the default directory.

Instance 0, with the directory default, is available by default. Use this instance for most configurations. Add another instance by clicking the + icon only when the device requires a separate certificate, for example, during a transition to a different ACME server.

image-20260928-152957.png
image-20260928-153028.png


The following table provides an overview of the ACME Client configuration parameters:

Parameter

Description

Default value

Example

Registry key

Manage certificates with ACME

Activates or deactivates certificate management with ACME.

Disabled

Enabled

app.acme_client.enable

Directory

Specifies the subdirectory of /wfs/acme_certificates/ where the certificate, private key, and other data for this instance are stored. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.

default

default

app.acme_client.cert%.directory

Names

Specifies the space-separated names for which the certificate is requested. %H expands to the fully qualified hostname and %h to the short hostname. The names are requested as Subject Alternative Names (SANs). The first name is also requested as the Common Name (CN), but the ACME CA can ignore the CN. For the usual hostname certificate, use %H.

%H

%H

app.acme_client.cert%.names

Account key length (bits)

Specifies the length of the key used for the ACME account. Available values: 1024, 2048, 4096.

4096

4096

app.acme_client.cert%.accountkeylength

ACME server URL

Specifies the URL of the ACME directory on the ACME server.

Empty

https://my-stepca.example.com/acme/acme/directory

app.acme_client.cert%.serverurl

CA Bundle

Specifies the CA bundle used to verify the ACME server certificate.

Empty

/wfs/ca-certs/acme-root-ca.crt

app.acme_client.cert%.cabundle

Email address

Specifies the email address used when creating the account on the ACME server.

Empty

admin@example.com

app.acme_client.cert%.email

Key length (bits)

Specifies the type and length of the private key for which the certificate is requested. Values without the ec- prefix create RSA keys; values with the ec- prefix create elliptic curve keys. Available values: 1024, 2048, 4096, 8192, ec-256, ec-384, ec-512.

4096

ec-384

app.acme_client.cert%.keylength

Certificate expiry check interval (days)

Specifies the number of days between certificate expiration checks.

1

1

app.acme_client.cert%.checkinterval

Certificate renewal period (days)

Specifies how many days before the certificate expiration the ACME Client starts attempting to renew the certificate.

30

30

app.acme_client.cert%.renewalperiod

Debug level

Specifies the debug level used by acme.sh. Available values: 0, 1, 2, 3. Increase the level when troubleshooting certificate enrollment.

0

0

app.acme_client.cert%.debuglevel


  1. Use the following parameters to configure additional CSR attributes:

Parameter

Description

Default value

Example

Registry key

Organizational unit

Adds an Organizational Unit (OU) attribute to the CSR. Whether the attribute is accepted and included in the certificate depends on the ACME CA.

Empty

IT

app.acme_client.cert%.organizationalunit

Country

Adds a Country (C) attribute to the CSR. Whether the attribute is accepted and included in the certificate depends on the ACME CA.

Empty

DE

app.acme_client.cert%.country

State

Adds a State or Province (ST) attribute to the CSR. Whether the attribute is accepted and included in the certificate depends on the ACME CA.

Empty

North Rhine-Westphalia

app.acme_client.cert%.state

Locality

Adds a Locality (L) attribute to the CSR. Whether the attribute is accepted and included in the certificate depends on the ACME CA.

Empty

Augsburg

app.acme_client.cert%.locality

Organization

Adds an Organization (O) attribute to the CSR. Whether the attribute is accepted and included in the certificate depends on the ACME CA.

Empty

Example Corp

app.acme_client.cert%.organization

Name separator

Specifies a separator for multiple values in State, Locality, Organization, and Organizational Unit. The values are added as multiple single-valued Relative Distinguished Names (RDNs).

The parameter is only available as a registry key.

Empty

;

app.acme_client.cert%.multivalueseparator

SubjectAltName Suffix (+K)

Specifies whether a suffix is automatically added to the corresponding SAN. Available options include none and dot + DNS domain (auto).

Not Applicable

dot + DNS domain (auto)

app.acme_client.cert%.subjectaltname_otherK_suffix

Type of SubjectAltName (+K)

Specifies the type of an additional SAN. Up to four additional SANs can be configured (K = 1 to 4). Available types include None, IP address, DNS name, IP address (auto), DNS name (auto), Email address, DNS name as UPN (auto), and UPN.

Not Applicable

DNS name

app.acme_client.cert%.subjectaltname_otherK_type

SubjectAltName (+K)

Specifies the value of the additional SAN. Up to four entries can be configured (K = 1 to 4).

Empty

device.example.com

app.acme_client.cert%.subjectaltname_otherK


  1. If the ACME server requires External Account Binding (EAB), configure the following:

Parameter

Description

Default Value

Example

Registry Key

EAB Key ID

Specifies the key identifier supplied by the ACME server administrator.

Empty

<EAB-key-ID>

app.acme_client.cert%.eab_kid

EAB HMAC Key

Specifies the HMAC key supplied by the ACME server administrator. The value is stored as a protected password.

Empty

Not Applicable

app.acme_client.cert%.eab_hmac_key_crypt_password
image-20260928-153110.png


  1. Save the profile and assign it to the target devices.


  1. Restart the devices or apply the configuration according to your normal UMS workflow.

Example: Using an ACME Certificate for Network Authentication

Depending on your ACME Client configuration, the resulting client.cert and client.key files can be used for EAP-TLS and EAP-PEAP/TLS authentication over Ethernet or Wi-Fi. The following example shows how to use an ACME-generated certificate for EAP-TLS authentication.

Assume that Directory in the ACME Client configuration is set to default. The ACME Client stores the generated certificate and private key in:

  • Client certificate: /wfs/acme_certificates/default/client.cert

  • Private key: /wfs/acme_certificates/default/client.key

To use these files for EAP-TLS, configure the authentication settings under one of the following:

  • Network > Wireless > Wi-Fi Network

  • Network > LAN Interfaces > [Interface] > Authentication

Configure the following settings:

Parameter

Configuration

EAP Type

Select TLS.

Validate Server Certificate / CA Root Certificate

Configure the CA root certificate required to verify the RADIUS server's certificate.

Manage certificates with SCEP (NDES)

Disable.

Client Certificate

Enter /wfs/acme_certificates/default/client.cert.

Private Key

Enter /wfs/acme_certificates/default/client.key.

Identity

Leave empty. The identity is automatically derived from the subject of the client certificate.

Private Key Password

Leave empty.

Verify the Certificate

Check that the following files exist:

/wfs/acme_certificates/<directory>/client.cert
/wfs/acme_certificates/<directory>/client.key

To inspect the certificate, run:

Bash
openssl x509 -noout -text -in /wfs/acme_certificates/<directory>/client.cert

Verify the subject, subject alternative names, issuer, and validity period.

Troubleshoot Certificate Enrollment

To monitor ACME Client messages, run:

Bash
journalctl -f | grep acme

If no certificate is created, check:

  • The ACME Client is enabled.

  • The ACME directory URL is complete and correct.

  • DNS resolves each requested name correctly.

  • The device and ACME server can communicate.

  • The CA Bundle path and file permissions are correct.

  • The ACME server supports http-01.

  • The configured EAB credentials are valid when EAB is required.

  • The output directory name contains only supported characters.