Certificate Enrollment Service
HYPR Workforce Access Client: Windows
Beta Feature
This article is subject to change as the feature develops and we make improvements.
HYPR Certificate Enrollment Service is designed to manage authentication certificates for end users enrolling with the HYPR Workforce Access Client and the HYPR Device Manager.
When users add a new device to the Device Manager for a workstation authentication, Control Center will make REST API calls to the Enrollment Service to enroll the certificate on the user's behalf - and then transport this certificate to the user's mobile device.
If the user follows the prompt, they will be taken to the Updating a Key's PIN dialog described in Pairing with a Security Key.
See the diagram below for the flow of the service.
One of Us
The server where the Enrollment Service is installed must be joined to the domain and have persistent and reliable network connectivity with a domain controller and the Active Directory Certificate Services (AD CS) server.
HYPR Feature Flags
Following feature flags needs to be enabled on the global and Application levels:
RP_APP_WORKSTATION_ENABLED
ASYNC_REGISTRATION
WINDOWS_WEB_ENROLLMENT
VIRTUAL_DESKTOP_INFRASTRUCTURE
ENDPOINT_API_SECURITY_TOKEN_DEVICE
ENDPOINT_API_SECURITY_TOKEN_WORKSTATION
Managing Feature Flags
API Token Required
Please ensure to generate an API access token in the Control Center to proceed with next steps.
To enable the feature flag on the Application level:
curl --location --request POST 'https://<YOUR CONTROL CENTER URL/rp/api/versioned/features/toggle/B<FEATURE FLAG NAME>/<YOUR RP APP NAME>' \--header 'Connection: keep-alive' \
--header 'Cache-Control: max-age=0' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Sec-Fetch-Site: same-origin' \
--header 'Sec-Fetch-Mode: cors' \
--header 'Accept-Encoding: gzip, deflate, br' \
--header 'Accept-Language: en-US,en;q=0.9' \
--header 'Authorization: Bearer <YOUR ACCESS TOKEN' \
--data-raw ''
To enable the feature flag at the Control Center level:
curl --location --request POST 'https://<YOUR CONTROL CENTER URL/rp/api/versioned/features/toggle/B<FEATURE FLAG NAME>' \--header 'Connection: keep-alive' \
--header 'Cache-Control: max-age=0' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Sec-Fetch-Site: same-origin' \
--header 'Sec-Fetch-Mode: cors' \
--header 'Accept-Encoding: gzip, deflate, br' \
--header 'Accept-Language: en-US,en;q=0.9' \
--header 'Authorization: Bearer <YOUR ACCESS TOKEN' \
--data-raw ''
Certificate Template
Just One Example
Screenshots below were taken with the AD 2008. Your AD may have a different User Interface if you're on a newer version.
To enroll certificates in behalf of another user, an Enrollment Agent certificate must be present on the Windows server where the HYPR Enrollment Service is running. In addition, a User template must be defined to allow user certificates to be issued.
HYPR Enrollment Agent Template
- On a Windows server with the Active Directory Certificate Services (ADCS) role configured, run MMC and load the Certificate Templates snap-in.
- Right-click the Enrollment Agent (Computer) template and choose the All Tasks β Duplicate Template menu option.
- Choose the appropriate minimum version for the CA from the choices displayed in the following dialog:
- Name the new template HYPR Enrollment Agent.
- Select the Security tab to display the current access control list for the template.
- To tighten the access controls on the template, click Add⦠and add an entry for the computer where the HYPR Enrollment Service will be running.
- Check the Enroll checkbox and click Apply to save the template..
HYPR Enrollment User Template
- Duplicate an existing template (see Creating a Custom Certificate Template) and name it HYPR Enrollment User. This is the template that will be used to issue user certificates.
- Select the Issuance Requirements tab.
- Check This number of authorized signatures and give it a value of 1.
- Set the Application Policy to Certificate Request Agent.
- Click Apply to save the template.
- Load the Certification Authority snap-in into MMC.
- Choose the Certificate Templates node.
- Right-click and select the New β Certificate Template to Issue menu option.
- Select the HYPR Enrollment Agent and HYPR Enrollment User templates from the list.
- Click OK to publish the certificate templates for use.
- Deploy the HYPR Enrollment Agent template. On the Windows server where the HYPR Enrollment Service is running, deploy the Enrollment Agent certificate to the Local Machine certificate store. Run
certlm.msc
. - Navigate the the Personal β Certificates node.
- Right-click and choose All Tasks β Request New Certificate.
- Continue to click Next until the following dialog is displayed.
- Choose the HYPR Enrollment Template and click Enroll to deploy the Enrollment Agent certificate to the Windows server.
How It Works
- The HYPR Enrollment Service is a service running on a Windows computer (Windows 10 or Windows Server 2008/2012/2016/2019) hosted on-premises at the customer with network connectivity to Active Directory Certificate Services (ADCS)
- The service runs under the SYSTEM account
- The computer on which the service is running will have an Enrollment Agent (Computer) certificate enrolled and stored in the Local Machine certificate store.
- A certificate template named HYPR Enrollment User will be defined for enrolling user certificates. The service will utilize this template to enroll user certificates on behalf of a specified user. The policy for this template will be set to require one signature from an Enrollment Agent.
- The service will continually poll the HYPR CC server for certificate requests by invoking the
api/certificate/requests
endpoint with a secure API token. The service will attempt to enroll a user certificate on behalf of the specified user for each request. - The enrollment service uses the
CertENROLL
(a Microsoft-provided DLL that ships with every MS OS) ActiveX component to enroll user certificates
Identity Mapping
When a userID is presented to the HYPR Enrollment Service, it will attempt to look up the user in Active Directory. It will try the lookup by User Principle Name (UPN) first and then try via the mail attribute (EMAIL address).
Installation
The Enrollment Service is distributed as an MSI installer package. The file name is HyprEnrollmentService_x64.msi
. The installer has no user interface β it is intended to be installed by an IT professional on a server, where a GUI may not be available. Installation parameters must be passed on the msiexec
command line.
Installation Parameters
Parameter | Description | Type |
---|---|---|
HYPRAPITOKEN | API Token that Enrollment Service will use to access the HYPR server. Must be generated for the Control Center Admin application. Note that this is a traditional API Token, and not a Workstation Installation Token. | Required |
HYPRHASH | SSL/TLS public key pinning hash. | Required |
HYPRRP | URL of the HYPR server (e.g. https://bank.hypr.com/rp ). | Required |
HYPRLOGLEVEL | Log level to the Enrollment Service (5 = Debug, 6 = Trace, other values should be avoided). Default is 5 if not specified. | Optional |
HYPRPROXYSERVER | Proxy server address and port (e.g., proxy.foobar.com:8080 or 12.34.56.78:8888 ). | Optional |
HYPRTEMPLATE | Template that the Enrollment Service will use to request user certificates. Defaults to HYPREnrollmentUser if not specified. | Optional |
HYPRPROXYBYPASS | Subnets and/or hosts that should bypass the proxy. | Optional |
Installation Example
@if "%1%"=="" goto USAGE
@if not exist "%1%" goto USAGE
set RP="https://<YOUR CONTROL CENTER URL>/rp"
set HASH="<SSL/TLS PUBLIC KEY PINNING HASH>"
set APITOKEN="<YOUR CONTROL CENTER ADMIN RP APP ACCESS TOKEN>"
set TEMPLATE="<CERTIFICATE TEMPLATE NAME>"
msiexec /i %1 /qn /norestart /L*V install.log HYPRRP=%RP% HYPRHASH=%HASH% HYPRAPITOKEN=%APITOKEN% HYPRTEMPLATE=%TEMPLATE%
@exit /b 0
:USAGE
@echo Usage: install "<PATH TO MSI>"
@exit /b 1
Updated 10 months ago