Enrolling through the Gateway

The Keyfactor Windows EnrollmentClosed 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). Gateway allows you to enroll for certificates from an EJBCA CAClosed 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. managed by Keyfactor using familiar Microsoft GUI and command-line certificate request tools.

Requests that do not require manager approval should be issued immediately and the certificate returned to the requester seamlessly. If more than one EJBCA CA is available that supports the requested templateClosed A certificate template defines the policies and rules that a CA uses when a request for a certificate is received., an EJBCA CA will be selected randomly to which to direct the certificate request.

The following are some special enrollment situations you may encounter.

On an enrollment request through the gateway for a Microsoft template that is configured to build the subject from Active Directory, the subject, SANClosed The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. and SID information for the user or subject and SAN information for a computer will be retrieved from the local Active Directory and delivered along with the request to Keyfactor Command, where they will be stored in enrollment fields and used to make a certificate request to the EJBCA CA using a supply in request subject method.

Tip:  When a machine or user certificate is issued with a template that has either the "User principal name (UPN)" or "Service principal name (SPN)" SAN boxes checked, and the subject's account does not have a value for userPrincipalName:

  • If the account enrolling is a machine, the PrincipalName SAN will be set to samAccountName$@domain.fqdn.

  • If the account enrolling is a user, the PrincipalName SAN will be set to samAccountName@domain.fqdn.

Be sure that you have completed all the configuration to support building the subject from AD. See Templates Configured to Build the Subject from the Local Active Directory.

On an enrollment request through the gateway for a template that has a Keyfactor Command workflowClosed A workflow is a series of steps necessary to complete a process. In Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. and requires manager approval at the Keyfactor Command level, the gateway will return the request ID rather than the issued certificate. Once the pending certificate request has been approved, this request ID may be used to make another request through the gateway for the issued certificate. The Microsoft certificates MMC does not have the ability to display this request ID to the requester, so an alternative enrollment method should be used for certificates requiring manager approval.

Example:  To request a certificate from the command line for a template configured in Keyfactor Command to require manager approval, you can generate a CSRClosed 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. and then use a certreq command something like the following to submit the request to the gateway (where mygateway.keyexample.com is the FQDN or your gateway server, GTWYSRVR-CA is the CA logical nameClosed The logical name of a CA is the common name given to the CA at the time it is created. For Microsoft CAs, this name can be seen at the top of the Certificate Authority MMC snap-in. It is part of the FQDN\Logical Name string that is used to refer to CAs when using command-line tools and in some Keyfactor Command configuration settings (e.g. ca2.keyexample.com\Corp Issuing CA Two). assigned to your gateway, GatewayWebServer is a local template in your environment that you have mapped to an EJBCA template that has been configured for enrollment in Keyfactor Command, and MyCSR.csr is a CSR you have generated for enrollment):

certreq -submit -config "mygateway.keyexample.com \GTWYSRVR-CA" -attrib "certificateTemplate: GatewayWebServer" MyCSR.csr

Tip:  The certreq command is case sensitive when referencing things like the CA, so if your CA’s logical name as registered in your local Active Directory is GTWYSRVR-CA but you enter a certreq command with GtwySrvr-CA, your CA won’t be found.

You would receive back a response looking something like this:

RequestId: 923
RequestId: "923"
Certificate request is pending: Awaiting 1 more approval(s) from approval roles. (0)

Once the certificate request has been approved in Keyfactor Command, you can use certreq to retrieve the issued certificate using a command similar to (where 923 is the certificate request ID provided in response to the initial request and MyCert.cer is an output file into which to place the issued certificate):

certreq -retrieve -config "mygateway.keyexample.com \GTWYSRVR-CA" 923 MyCert.cer

If the certificate has not yet been issued, you will receive a status report—including any error—on the retrieve command rather than the certificate.

Note:  If a workflow fails and needs to be restarted in order for the certificate to be issued, the request ID will change.

The enrollment flow for auto-enrollment requests is the same as for any other build-from-AD enrollment request from a gateway perspective. Be sure that you have completed all the configuration to support building the subject from AD. See Templates Configured to Build the Subject from the Local Active Directory.

If the application you’re using to make an enrollment request to the gateway is running as NETWORK SERVICE or Local System, when the request is received by the gateway, the requester on the request will be changed to the computer account identity (e.g. mygateway$) of the server on which the gateway is running to allow the enrollment to complete. The computer account will need appropriate enrollment permissions in the local template and on the Security tab in the gateway.