Preparing

To support your implementation process, have the following information prepared before beginning the installation of Keyfactor ACME:

1. Determine the Keyfactor Command Connection Authentication Mechanism

   • Windows IIS Installs: The connection Keyfactor ACME makes to the Keyfactor Command server can be authenticated with OAuth, Windows, or Basic authentication. The selection you make will depend on the configuration of your Keyfactor Command implementation.

     If OAuth is selected, this must be an OAuth identity provider that has been configured in Keyfactor Command as a supported identity provider. It does not need to be the same identity provider you use to authenticate ACME clients to Keyfactor ACME (see step 2).

     If your Keyfactor Command is not using OAuth, check the configuration of the Keyfactor API 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. virtual directory on the Keyfactor Command server to determine whether Basic or Windows authentication is in use. If both Basic and Windows authentication are configured, the Keyfactor ACME installation will default to using Windows authentication.

     If you opt to use Windows authentication, a service principal name (SPN) needs to be configured for the Keyfactor ACME application pool service account (see Identify Users and Groups) to allow it to authenticate via Kerberos to the Keyfactor Command server. Show SPN instructions.

     Configure the service principal name (SPN) for the Keyfactor ACME server as follows:

     1. On a server that has the setspn command available (typically it is available on domain controllers, as it installs as part of the Active Directory Domain Services role), open a command prompt using the “Run as administrator” option.

     2. Run the following command (where acme.keyexample.com is the fully qualified domain name of your Keyfactor ACME server or the DNS The Domain Name System is a service that translates names into IP addresses. alias you are using to reference your Keyfactor ACME server, if applicable, and KEYEXAMPLE\svc_acmepool is the domain name and service account name of the service account under which the Keyfactor ACME application pool is running):

        setspn –s HTTP/acme.keyexample.com KEYEXAMPLE\svc_acmepool

   • Container Installs: The connection Keyfactor ACME makes to the Keyfactor Command server can be authenticated with OAuth or Basic authentication. The selection you make will depend on the configuration of your Keyfactor Command implementation. If OAuth is selected, this must be an OAuth identity provider that has been configured in Keyfactor Command as a supported identity provider. It does not need to be the same identity provider you use to authenticate ACME clients to Keyfactor ACME (see step 2).

2. Select OAuth Identity Providers

   ACME clients connecting to the Keyfactor ACME server to request certificates as well as administrators managing Keyfactor ACME authenticate using OAuth. This requires an OAuth identity provider. Keyfactor ACME supports open authorization (OAuth) 2.0 compliant identity providers with a complete implementation of the OpenID Connect (OIDC) protocol. Show OAuth identity provider details.

   OAuth identity providers must meet the following requirements to work with Keyfactor ACME:

   • They must be a complete implementation of OpenID Connect. For more information, see:

     https://openid.net/developers/how-connect-works/
   • Users should not be allowed to choose their own usernames and/or email addresses for access to Keyfactor ACME.
   • Usernames within the realm must be unique.
   • The identity provider must be configurable using the fields provided in Keyfactor ACME. See Table 5: Configure Command Parameters (Windows) and Values File Settings for Containers Under Kubernetes (Containers).

   • The token endpoint An endpoint is a URL that enables the API to gain access to resources on a server. must support POST Form URL requests, using the following parameters:

     • client_id
     • client_secrets
     • grant_type
   • The identity provider must support front-channel logout.

   To prepare one or more OAuth Identity providers for use with Keyfactor ACME:

   • Create a client in the identity provider for use with Keyfactor ACME.
   • Confirm that the client is configured with appropriate redirect URLs, if applicable.

   • Collect the information for the identity provider needed for installation, including:

     • ACME Authority
     • ACME JSON Web Key Set
     • ACME Name Claim Type
     • ACME Role Claim Type
     • ACME Unique Claim Type
     • Command Authority
     • Command Client ID
     • Command Client Secret
     • Command Token URL

   ACME values are used to configure authentication of ACME clients to the Keyfactor ACME server. Command values are used to configure authentication of the Keyfactor ACME server to Keyfactor Command. Different OAuth providers may be used for these roles, if desired. See Table 5: Configure Command Parameters (Windows) and Values File Settings for Containers Under Kubernetes (Containers).

3. Identify Users and Groups

   At a minimum, the following users/groups are required to configure Keyfactor ACME:

   • Keyfactor ACME User: The service account used to authenticate from Keyfactor ACME to Keyfactor Command.

     • Windows Installs: If OAuth is used, this is specified by the commandclientid parameter A parameter or argument is a value that is passed into a function in an application. using the Configure command (see The Configure Command). For Basic authentication, this information is prompted for during the installation. For Windows authentication, integrated authentication is configured for this user, which is the application pool user (see below) and must be a domain account to support integrated authentication.

     • Container Installs: For OAuth, specified by the config > commandConnection > oAuth > clientId parameter. For Basic authentication, specified by the config > commandConnection > basicAuth > username parameter. For more information, see Helm Chart Customization.

   • Application Pool User (Windows Installs Only): The identity the application pool in IIS on the Keyfactor ACME server will run as. The application pool cannot run as the default ApplicationPoolIdentity that IIS will assign when an application pool is initially created. This user needs to be either a domain or local account.

   • SQL User: The SQL user used to authenticate Keyfactor ACME to Microsoft SQL if integrated authentication is not used. Integrated authentication is not supported for container installs. The following permissions are needed in SQL to complete the installation:

     • Integrated Windows Authentication: The user executing the Keyfactor ACME command line tool needs dbcreator and securityadmin to create a database. During configuration on Windows, the IIS application pool user will automatically be set as the database owner (dbo) on the Keyfactor ACME SQL database. This user does not need to be added into SQL ahead of time.

     • SQL Authentication: The service account configured as the SQL user needs dbcreator and securityadmin to create a database.

   • Super Admin User: At least one administrator with SuperAdmin permissions needs to be created to fully configured Keyfactor ACME.
   • Account Admin User (Optional): It may be desirable to create one or more administrators with AccountAdmin permissions to manage accounts. Users with SuperAdmin permissions can also manage accounts, so this is optional.
   • Enrollment Users: At least one user with EnrollmentUser permissions should be created to support enrolling for certificates from an ACME client. Configuring one or more groups with this role might be desirable for ease of claim management.

4. Identify Keyfactor Command API URL

   Know the URL of the Keyfactor API, which can be found on the API tab of the Keyfactor Command configuration wizard.

5. Identify Templates and CAs

   Identify at least one template A certificate template defines the policies and rules that a CA uses when a request for a certificate is received. and CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. to use in conjunction with the Keyfactor ACME server. The templates used for Keyfactor ACME must:

   • Grant Read and Enroll permissions to the Keyfactor ACME user.

   • Be configured in Keyfactor Command to support CSR A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. enrollment Certificate enrollment refers to the process by which a user requests a digital certificate. The user must submit the request to a certificate authority (CA). (see Enrollment Pattern Operations - Adding or Modifying an Enrollment Pattern: Basic Information Tab in the Keyfactor Command Reference Guide).

   Tip:  For Microsoft CAs, Keyfactor recommends making a copy of the default Web Server template and modifying that to meet the requirements for Keyfactor ACME.
   Note:  Beginning with version 2.0, Certbot issues ECDSA ECDSA (Elliptic Curve Digital Signature Algorithm) is used for digital signatures in public-key cryptography. It offers strong security with smaller key sizes compared to RSA, making it ideal for resource-constrained environments. (secp256r1) certificates by default. In many cases, a web server certificate template is configured for RSA 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. encryption and so will not be compatible with this default. You may either configure the Keyfactor ACME server with a certificate template that supports ECDSA (secp256r1) or specify an appropriate key type The key type identifies the type of key to create when creating a symmetric or asymmetric key. It references the signing algorithm and often key size (e.g. AES-256, RSA-2048, Ed25519). and key size The key size or key length is the number of bits in a key used by a cryptographic algorithm. in your Certbot requests.

6. Prepare for Application-Level Encryption (Optional)

   Prepare a methodology for application-level encryption on the Keyfactor ACME server if you plan to use this feature (see Application-Level Encryption).

7. Prepare Certificate Root Trusts

   HTTPS is used with Keyfactor ACME to secure the following communication channels:

   • Keyfactor ACME to Keyfactor Command: Used to enroll for certificates.

   • Keyfactor ACME to the ACME OAuth identity provider: Used to authenticate users when acquiring EAB keys.

   • Keyfactor ACME to the Command OAuth identity provider: Used to authenticate the service account communicating with Keyfactor Command.

   • ACME clients to Keyfactor ACME: Used for registering accounts and requesting certificates.

   These communications require TLS TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. (SSL TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers.) certificates on the servers for Keyfactor ACME, Keyfactor Command, and the OAuth identity providers. The certificates may be:

   • Publicly rooted certificates (e.g., from DigiCert, Entrust, etc.), or

   • Privately issued certificates from an internal certificate authority A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. (CA).

   If you're using publicly rooted certificates, they are likely already trusted by the server. However, if you are using any internally generated certificates, Keyfactor ACME may not automatically trust them. In such cases, you will need to import the certificate chain or chains into the appropriate trust store:

   • Keyfactor ACME on Windows: Import the certificates into the local machine certificate store.

   • Keyfactor ACME in Container: Import the certificates into the root certificate store of the container.

     Methods for doing this vary depending on the Linux implementation.

     Tip:  Beware of ending up with Windows line endings in the trusted root store, as this can create root trust issues inside the container.

8. Acquire a TLS (SSL) Certificate

   The Keyfactor ACME server requires a TLS/SSL certificate to secure communications to it.

9. Install IIS (Windows Installs Only)

   Install IIS if you’re not using a shared server (see Install IIS, .NET Framework, and ASP.NET) and bind your TLS certificate to the default web site.

10. Create an Application Pool (Windows Installs Only)

    Create or identify an application pool in IIS for use with the Keyfactor ACME server using the identified application pool user (see Identify Users and Groups).

    Note:  If you are installing Keyfactor ACME on the Keyfactor Command server, this would typically be one of the application pools in use for Keyfactor Command.

11. Configure Metadata Population (Optional)

    Identify any metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. you wish to populate upon enrollment in Keyfactor Command and create the PowerShell script or user-defined metadata extension to populate that metadata (see Keyfactor ACME Metadata).

12. Update Keyfactor Command Enrollment Pattern Requirements

    Disable the default Common Name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). regular expression A regular expression--RegEx--is a pattern used to validate data by ensuring it meets specific criteria. Several fields on the CSR enrollment, CSR generation, and PFX enrollment pages support RegEx validation, including certificate subject and metadata fields. that requires entry of a value for enrollments in Keyfactor Command. This is found under Enrollment Patterns on the Enrollment Regexes tab (see Enrollment Pattern Operations - Adding or Modifying an Enrollment Pattern: Enrollment RegExes Tab in the Keyfactor Command Reference Guide).

13. Grant Keyfactor Command Permissions

    Grant the Keyfactor ACME user Certificates > Collections > Read permissions to allow reading of existing certificates and Certificates > Enrollment > Csr permissions to allow certificate enrollment in Keyfactor Command. This can be done by creating a new security role or leveraging an existing one (see Security Overview in the Keyfactor Command Reference Guide).

    If you plan to support certificate revocation initiated through Keyfactor ACME, grant the Keyfactor ACME user Certificates > Collections > Revoke permissions.