# API Enrollment

{% hint style="info" %}
This feature requires version **2.3.689** or above.
{% endhint %}

{% hint style="warning" %}
SCEPman Enterprise Edition only
{% endhint %}

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

{% stepper %}
{% step %}

### App Registration

Create a new *App Registration* that describes your use case. You application will authenticate as this application against SCEPman.
{% endstep %}

{% step %}

### API Permissions

#### CSR.Request.Db

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

Example: 

```powershell
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:

<figure><img src="https://2535731700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LoGejQeUQcw7lqnQ3WX%2Fuploads%2FDcTPqAoP7o03QirKhyMH%2Fimage.png?alt=media&#x26;token=7233bb9a-a9c1-49aa-9cbc-21f90931c59c" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Client Secret

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

### 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***.

<figure><img src="https://2535731700-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LoGejQeUQcw7lqnQ3WX%2Fuploads%2F9UeFFxwefnV8Cb7Zz14u%2Fimage.png?alt=media&#x26;token=210ea9b7-ecd5-4b2b-9641-22447246e718" alt=""><figcaption></figcaption></figure>

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](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#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](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#appconfig-dbcsrvalidation-allowrenewals)

*Required for certificate renewal*

Set this variable to ***true*** to enable certificate renewals.

#### [AppConfig:DbCSRValidation:ReenrollmentAllowedCertificateTypes](https://docs.scepman.com/advanced-configuration/application-settings/dbcsr-validation#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:

{% content-ref url="scepmanclient" %}
[scepmanclient](https://docs.scepman.com/certificate-management/api-certificates/scepmanclient)
{% endcontent-ref %}

## Other Examples

See our [Open Source Sample Library on GitHub](https://github.com/scepman/csr-request) to find out how to use SCEPman's REST API.