API Enrollment

Use this REST API using Microsoft Identities for authentication to enroll certificates as an alternative to the SCEP endpoints that require the SCEP-style of authentication.

This feature requires version 2.3.689 or above.

SCEPman Enterprise Edition only

SCEPman features a REST API to enroll certificates. This is an alternative to the SCEP endpoints that require the SCEP-style of authentication, while the REST API uses Microsoft Identities for authentication. The protocol is also much simpler than SCEP.

Prerequisites

1. Service Principal

1

App Registration

Create a new App Registration that describes your use case. You application will authenticate as this application against SCEPman.

2

API Permissions

CSR.Request.Db

Assign the required permissions by running the Register-SCEPmanApiClient cmdlet from the SCEPman PowerShell module.

Example:

Register-SCEPmanApiClient -ServicePrincipalId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

ServicePrincipalId

The Object ID of the complementing Enterprise Application of the App Registration we created in the previous step. Note that this does not refer to the Enterprise Application usually named SCEPman-api, which identifies SCEPman itself.

To manually assign this permission you can navigate to API Permissions and add a permission from the permissions your organization uses. Assign the CSR.Request.Db permission from SCEPman-api as an application permission.

Application.Read.All (Optional)

Service Principals will also require the Graph permission Application.Read.All to allow automatic retrieval of SCEPman's API scope for authentication.

The permission can be added manually like so:

3

Client Secret

Create a client secret under "Certificates & Secrets." The Client Secret will be used as a password to authenticate the application later.

2. App Service Settings

Configuration

Required for certificate renewal

Configure your SCEPman App Service to accept mTLS client certificates. In the Configuration blade of the Settings section, verify that the Client certificate mode in Incoming client certificates is set to Optional Interactive User.

Do not set the Client certificate mode to Require or Allow, as that would break normal operation of SCEPman on the SCEP endpoints!

Environment Variables

In order to make use of this scenario, you must set the following Environment Variables on the SCEPman app service.

AppConfig:DbCSRValidation:Enabled

Required for certificate enrollment and renewal

Set this variable to true to enable the validation of certificate signing requests (CSRs).

AppConfig:DbCSRValidation:AllowRenewals

Required for certificate renewal

Set this variable to true to enable certificate renewals.

AppConfig:DbCSRValidation:ReenrollmentAllowedCertificateTypes

Required for certificate renewal

Set this variable to a comma separated list of certificate types that you want to allow the renewal. See the linked variable documentation for a list of possible certificate types.

Example: Static,IntuneUser,IntuneDevice

Enrolling certificates

After you have prepared the prerequisites, you can POST a PKCS#10/CMS to your SCEPman with the HTTP path api/csr. The HTTP Response will be the freshly issued certificate in DER encoding.

SCEPman will store all issued certificates automatically in its Storage Account, so you can conveniently list and revoke them via the Certificate Master component.

A convenient method to send those request is our SCEPmanClient PowerShell module:

SCEPmanClient

Other Examples

See our Open Source Sample Library on GitHub to find out how to use SCEPman's REST API.