Access Control and Claims

The Keyfactor ACME server uses claims to control access for users and groups/roles. Claims define which users or groups have permission to perform specific actions within the Keyfactor ACME server, including registering ACME clients, enrolling for certificates, and administering the system with the Keyfactor ACME APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command.. Claims can be managed through the following methods, depending on your Keyfactor ACME installation:

  • Windows Installation (IIS): Claims can be managed with the claims command in the Keyfactor ACME command line tool (KeyfactorACMEConfig.exe) or the claims API endpoints in the Keyfactor ACME API.

  • Container Installations (Kubernetes): Claims are managed via the claims API endpoints in the Keyfactor ACME API (see Keyfactor ACME API).

In either case, the tool is used to add or remove claims, and to map certificate templates to users or groups/roles. This mapping determines which certificate templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. in Keyfactor Command will be used for certificate enrollments associated with the user’s EAB key.

Note:  No users are included in the claims list initially. Claims must be explicitly assigned to users or groups.

There are three roles within Keyfactor ACME, each with specific access privileges:

  • AccountAdmin: Users can administer accounts in the Keyfactor ACME database including listing and revoking accounts and associated EAB keys.

  • EnrollmentUser: Users can request external account binding (EAB) keys, register ACME clients and enroll for certificates. Users can revoke certificates if this functionality is enabled.

  • SuperAdmin: Users can configure the Keyfactor ACME implementation and manage claims and identifiers in the Keyfactor ACME database using the Keyfactor ACME API. SuperAdmin users inherit AccountAdmin permissions and can administer accounts in the Keyfactor ACME database. SuperAdmin users do not inherit EnrollmentUsers permissions and cannot request EAB keys, register ACME clients, or enroll for certificates unless specifically granted the EnrollmentUser permission.

Note:  A user must be issued an EAB key (see GET KeyManagement) before being able to register an ACME client (for Certbot, see Register an Account) and request a certificate.
Windows Installations (IIS)
Tip:  Run the Keyfactor ACME commands at the command line or in a regular PowerShell window, NOT using the PowerShell ISE (as it does not have support for the “Console” class).

After configuring the Keyfactor ACME software, configure at least one claim as follows:

  1. Open a command prompt using the Run as administrator option.

  2. Change to the Configuration directory under the directory in which you installed Keyfactor ACME. By default, this is:

    C:\Program Files\Keyfactor\ACME\Configuration

  3. Execute a command similar to the following examples, using appropriate values for your environment (see Table 7: Claims Command Options).

    Note:  The Keyfactor ACME command line tool (KeyfactorACMEConfig.exe) is executed in the context of either the IIS application pool user or the SQL user, depending on the SQL authentication mechanism, and does not require AccountAdmin or SuperAdmin permissions to operate (see SQL Access Control and the Command Line Tool).

    For example:

    • Add a claim for the acme-template-CorpWebServer-RSAClosed A widely used public-key cryptosystem, RSA is commonly used for encryption and digital signatures. It is based on the mathematical difficulty of factoring large integers. role, grant users with this role the EnrollmentUser permission, associate the role with the Corporate_CorpWebServer-RSA certificate template:

      KeyfactorACMEConfig.exe claims --add --claimtype role --roles EnrollmentUser --template Corporate_CorpWebServer-RSA --claimvalue acme-template-CorpWebServer-RSA

      Any user in the acme-template-CorpWebServer-RSA group in the OAuth identity provider can now request an EAB key, register an ACME client, and enroll for a certificate.

    • Add a claim for the client ACME-Admin-JSmith, grant this client both the EnrollmentUser and AccountAdmin permissions, associate the client with the Corporate_CorpWebServer-MultiKey certificate template:

      KeyfactorACMEConfig.exe claims --add --claimtype client_id --roles EnrollmentUser,AccountAdmin --claimvalue ACME-Admin-JSmith --template Corporate_CorpWebServer-MultiKey

      The user specified by client ID ACME-Admin-JSmith can now request an EAB key, register an ACME client, and enroll for a certificate. The user can also list and revoke accounts registered by any ACME client and delete the EAB keys stored in Keyfactor ACME associated with these accounts.

    • Add a claim for the user whose sub is 6d0bae03-75a2-4dfd-87cf-6b2d8d697fc7 and grant this user the SuperAdmin permission:

      KeyfactorACMEConfig.exe claims --add --claimtype sub --roles SuperAdmin --claimvalue 6d0bae03-75a2-4dfd-87cf-6b2d8d697fc7

      The user specified by sub 6d0bae03-75a2-4dfd-87cf-6b2d8d697fc7 can now fully administer Keyfactor ACME. The user cannot request an EAB key, register an ACME client, or enroll for a certificate unless the user is a member of a group that grants the EnrollmentUser permission.

    Note:  Without a template mapping, a user will not be able to request an EAB key, unless the user inherits a template mapping via a role.

Table 7: Claims Command Options

Short Name

 Long Name Description
-a
--add
 Add a claim to the claims list.
-x
--remove
 Remove a claim from the claims list.
-l
--list

List all claims that are in currently in the claims list.

Note:  The list option includes legacy Active Directory claims for Keyfactor ACME servers upgraded from older versions that supported Active Directory. Legacy Active Directory claims cannot be used to register new ACME clients, though existing ACME clients registered with EAB keys belonging to these users will continue to function.
-c
--claimtype
 The type of the OAuth claim (e.g. sub).
-v
--claimvalue
 The value of the OAuth claim.
-t
--template
 The template to be used for enrollment by this entity. A given entity can be associated with only one template.
-r
--roles

The role(s) this entity will have, provided as a comma-separated list. Supported roles are:

  • AccountAdmin: Users can administer accounts in the Keyfactor ACME database including listing and revoking accounts and associated EAB keys.

  • EnrollmentUser: Users can request external account binding (EAB) keys, register ACME clients and enroll for certificates. Users can revoke certificates if this functionality is enabled.

  • SuperAdmin: Users can configure the Keyfactor ACME implementation and manage claims and identifiers in the Keyfactor ACME database using the Keyfactor ACME API. SuperAdmin users inherit AccountAdmin permissions and can administer accounts in the Keyfactor ACME database. SuperAdmin users do not inherit EnrollmentUsers permissions and cannot request EAB keys, register ACME clients, or enroll for certificates unless specifically granted the EnrollmentUser permission.