Keyfactor ACME onboarding guide: From Command enrollment pattern to ACME client registration

This guide describes the end-to-end process for preparing a Keyfactor Command template and enrollment pattern, authorizing an OAuth identity in Keyfactor ACME, retrieving External Account Binding credentials, and registering an ACME client.

The onboarding flow separates PKI administration from application-team consumption. The PKI team establishes certificate policy and access. The application team uses its OAuth identity to retrieve EAB credentials and register an ACME client.

Roles and responsibilities

Role separation - Use a dedicated administrative identity for claim management and a separate application identity for enrollment. A SuperAdmin can manage claims and accounts but cannot retrieve EAB credentials unless the identity is also explicitly granted EnrollmentUser.

Prerequisites and information to collect

• Keyfactor Command certificate template short name and the target issuing CA.
• Enrollment pattern name, enabled enrollment type (CSR for ACME), default template, and any required workflow.
• Command role that will be permitted to use the enrollment pattern.
• ACME Management API base URL and ACME directory URL (https://customer.keyfactorpki.com/acme).
• OAuth token URL, client ID, client secret or other client credential, audience, and scope.
• The claim type emitted by the identity provider, such as sub, groups, roles, or scope, and the exact claim value.
• An ACME client that supports External Account Binding, such as cert-manager, Certbot, win-acme, or another RFC 8555-compatible client.

Naming rule - When mapping a claim, use the Keyfactor Command template short name, not the enrollment pattern display name. Keyfactor ACME uses the template mapping to locate the applicable default enrollment pattern.

1. Create the Command Enrollment Pattern

Step 1: Select or create the certificate template

Choose the template that defines the certificate policy required by the application, including subject requirements, SAN handling, key algorithm, key size, validity, EKUs, and CA constraints. Publish the template on the CA and import or synchronize it into Keyfactor Command as applicable.

Step 2: Select or create the Command role used by ACME

Select an existing Command role or create a role that represents the Keyfactor ACME service. Grant the role only required for the templates and enrollment patterns that the ACME service is authorized to use. 

• Certificates>Enrollment>CSR
• Certificates>Read

Avoid broad portal, certificate-management, or administrative permissions unless the use case requires them.

Step 3: Create the enrollment pattern

In Keyfactor Command, create an enrollment pattern that uses the selected template. Enable the enrollment method used by ACME, typically CSR enrollment. Configure the default CA and template behavior expected for unattended issuance.

Step 4: Add the ACME role to Allowed Requesters

In the enrollment pattern access or policy settings, add the Command role assigned to the Keyfactor ACME service to the Allowed Requesters list. The same ACME service role can be used across multiple enrollment patterns when appropriate because the requester remains the ACME service. Confirm that the role is also permitted wherever the Command deployment enforces CA- or template-level requester restrictions.

Step 5: Validate workflow behavior

ACME is an automated protocol. Do not attach an approval step that requires human interaction. If an enrollment workflow is used, ensure it can complete synchronously and does not require user input. Handle optional metadata through defaults or a post-enrollment workflow where appropriate.

2. Add the OAuth Claim to Keyfactor ACME

A Keyfactor ACME SuperAdmin creates the claim through the ACME Management API. The claim connects an identity-provider claim to the Command template and grants the EnrollmentUser role.

Step 1: Create the application OAuth identity

Create a confidential client in the organization’s identity provider. Use the OAuth 2.0 client-credentials grant and configure the resource audience and scope required by the ACME API.

Step 2: Inspect the issued access token

Obtain a token and verify the exact claim type and value that Keyfactor ACME will evaluate. For a direct application mapping, this is commonly the sub claim. For group-based onboarding, use the exact claim name configured by the identity provider, such as groups or roles.

Step 3: Authenticate with an ACME SuperAdmin token

Obtain an access token for the administrative identity that is already mapped to the SuperAdmin role in Keyfactor ACME.

Step 4: Create the enrollment claim

Call POST /Claims with the application claim, the template short name, and EnrollmentUser. The claim type/value pair must match the access token exactly.

Illustrative request body

POST https://<acme-host>/<acme-base-path>/Claims
Authorization: Bearer <superadmin-access-token>
Content-Type: application/json

{
  "claimType": "sub",
  "claimValue": "<application-subject-value>",
  "template": "<command-template-short-name>",
  "roles": ["EnrollmentUser"]
}

API behavior - The template is required when EnrollmentUser is assigned. Treat the claim type and claim value as an exact match. A mismatch commonly results in HTTP 401 or an unauthorized response when the application later calls KeyManagement.

Step 5: Verify the claim

Call GET /Claims and confirm the new record contains the intended claim type, claim value, template short name, and EnrollmentUser role. Where possible, test with the application token before handing the process to the application team.

3. Retrieve EAB credentials from the Key Management API

The application team uses its own OAuth client credentials to obtain an access token, then calls the Key Management API. GET /KeyManagement returns the existing EAB credentials or creates them when none exist for the authorized identity.

Step 1: Request an OAuth access token

Use the application client ID and client credential with the configured token URL. Include the required scope and audience for the ACME API.

OAuth token request pattern

POST https://<identity-provider>/<token-path>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<client-id>
&client_secret=<client-secret>
&scope=<scope>
&audience=<audience-if-required>

Step 2: Call GET /KeyManagement

Send the application access token to the ACME Key Management endpoint. If the identity is mapped through multiple roles or templates, include the template query parameter required by the deployment.

Key Management request

GET https://<acme-host>/<acme-base-path>/KeyManagement
Authorization: Bearer <application-access-token>
Accept: application/json

Optional when selecting among multiple mappings:
GET https://<acme-host>/<acme-base-path>/KeyManagement?Template=<template-short-name>

Step 3: Protect the response

The successful response contains keyId and keyValue. Store both values in the organization’s approved secrets-management system. Do not place the keyValue in tickets, email, source control, command history, or general-purpose configuration repositories.

Illustrative response

HTTP/1.1 200 OK

{
  "keyId": "<EAB-Key-ID>",
  "keyValue": "<Base64Url-encoded-HMAC-key>"
}

Credential meaning  - keyId is the EAB key identifier, sometimes labeled EAB KID. keyValue is the HMAC secret, sometimes labeled EAB HMAC key. These values authorize ACME account registration. They are not the certificate private key.

4. Register the ACME client and begin enrollment

Step 1: Configure the ACME directory URL

Set the client’s server or directory URL to the customer-specific Keyfactor ACME directory endpoint. Use the exact endpoint provided for the environment.

Step 2: Add the EAB credentials

Enter keyId as the EAB key identifier and keyValue as the EAB HMAC key. Use the client’s secure secret mechanism or an external secret store whenever available.

Step 3: Register the ACME account

Run the client’s account registration or first enrollment command. During registration, the client proves possession of the EAB HMAC key and creates an ACME account associated with the mapped identity and template.

Step 4: Request a test certificate

Submit a controlled test order with a permitted identifier. Confirm the request reaches the intended template, enrollment pattern, workflow, CA, and certificate policy.

Step 5: Configure automated renewal

Enable the client’s renewal mechanism and verify that it reuses the registered ACME account. Schedule a renewal test in non-production and confirm the renewed certificate is visible in Keyfactor Command.

Client configuration examples

Validation and troubleshooting

Security and operational recommendations

• Use separate OAuth clients for administration and enrollment to preserve least privilege and improve audit attribution.
• Prefer one claim, one template, and one EAB relationship for clear ownership and predictable routing unless the deployed version and design explicitly require another model.
• Store OAuth client secrets and EAB HMAC values in an approved secret manager. Rotate credentials according to organizational policy.
• Use separate identities and EAB credentials for independent workloads when isolation and ownership tracking are required.
• Validate the complete process in non-production before enabling production issuance.
• Document the template short name, enrollment pattern, claim type/value, OAuth application owner, ACME directory URL, and renewal owner in the service record.
• Monitor failed token validation, claim authorization, client registration, order validation, enrollment, and renewal events.

Customer handoff checklist

• Certificate template is published, synchronized, and approved for ACME use.
• Enrollment pattern is configured for unattended CSR enrollment.
• The Command role used by the ACME service is included in Allowed Requesters.
• OAuth confidential client is created and its token contains the expected claim.
• ACME claim maps the exact token claim to the template short name with EnrollmentUser.
• GET /KeyManagement returns keyId and keyValue with HTTP 200.
• EAB credentials are stored securely and supplied to the ACME client.
• ACME account registration completes successfully.
• Test certificate is issued from the intended CA and template.
• Automated renewal is configured, tested, monitored, and assigned to an owner.

Appendix A: Endpoint summary

API base paths, Swagger availability, identity-provider fields, and client prompts can differ by deployment and product version. Use the deployed Keyfactor ACME documentation as the authoritative reference for endpoint paths and request schemas.

Appendix B: Reference material

• Keyfactor ACME API: https://software.keyfactor.com/Guides/ACME/Current/Content/ACME/ACMEAPI.htm
• GET KeyManagement: https://software.keyfactor.com/Guides/ACME/Current/Content/ACME/API-Key-Management-GET.htm
• Configuring claims and fetching EAB keys: https://support.keyfactor.com/hc/en-us/articles/34142880917019-Configuring-claims-and-fetching-EAB-keys-in-Command-ACME-25-1