Azure Entra ID Integration Guide¶
Configure Azure Entra ID as the external identity provider for the Keyserver. The Keyserver does not manage users or passwords: all authentication relies on OAuth2/OIDC tokens issued by Entra ID and validated locally against Entra's published signing keys.
Which section do you need?¶
| You want to enable | Flow | Section in this guide |
|---|---|---|
| Human login to the Keyserver UI | Authorization Code (BFF) | Initial setup through Configure API permissions, the mandatory base setup |
| Azure DevOps pipelines | Workload Identity Federation | Configure Workload Identity Federation (plus the Azure DevOps guide) |
| Headless build servers / signing services | Client Credentials service account | Configure a Service Account with Client Credentials (pointer to the Headless Build Server guide) |
| Provisioning stations without a secret store | Authorization Code + PKCE (Proof Key for Code Exchange) | Configure the PKCE flow (plus the PKCE guide) |
The base setup is required in all cases; the other three sections are optional extensions on top of it.
Login flows¶
Authorization Code Flow with BFF¶
Users log in to the Keyserver's keyclient, a Backend-for-Frontend (BFF) that sits between the browser and Entra ID. The keyclient:
- holds the client secret and performs the code exchange, so neither the secret nor the tokens reach the browser
- hosts the approval and administration area (a JavaScript SPA)
- proxies that SPA's calls through to the Keyserver backend
This flow is for administrators and approvers only, not for signing or certificate issuance.
PKCE-enhanced Authorization Code Flow (optional)¶
For signing or certificate issuance from a client that cannot hold a secret, such as a provisioning station on a factory floor, a public client is registered instead, and an operator logs in for each session. The PKCE Client Integration Guide covers the client side, including how PKCE protects the authorization code. The PKCE flow is configured like the standard flow, with one extra platform at the end.
Values to exchange with Cryptera¶
Obtain from Cryptera before you start:
| Value | Needed for |
|---|---|
REDIRECT_URI | Always |
PKCE_REDIRECT_URI | Only when configuring the PKCE flow |
Collect during setup and return to Cryptera:
| Value | Needed for |
|---|---|
TENANT_ID | Always |
APPLICATION_ID | Always |
CLIENT_SECRET | Always |
OPENID_CONNECT_METADATA_DOCUMENT | Always |
APP_ROLE | Only for Workload Identity Federation or a client-credentials service account |
Deviations cause 401s
A renamed scope, a missing application ID URI, or v1 access tokens all produce 401 responses that look like credential problems. Follow the steps below as written.
Initial setup¶
With your tenant open, go to the Overview page and choose Add → App registration:

- Under Redirect URI (optional), select type Web and enter the
REDIRECT_URICryptera gave you, of the formhttps://keyclient.<UNIQUE-ID>.cryptera-security.io/login/oauth2/code/keyserver-client. The Authorization Code Flow will not work without it. - Click Register.
- From the application overview, copy two values for Cryptera:
- Application (client) ID →
APPLICATION_ID - Directory (tenant) ID →
TENANT_ID
- Application (client) ID →
-
Create the client secret the keyclient uses to talk to Entra ID.
Copy the secret now, and send it only through the secure channel
Entra ID shows the secret's value once; after you leave the page it can only be regenerated. Copy it straight into the secure channel Cryptera provided. Never send it by email, chat, or in a ticket.
Click Add a certificate or secret → New client secret, then copy the Value →
CLIENT_SECRET.
Getting the OpenID Connect metadata document URL¶
- On the Overview page, click Endpoints.
- Copy the URL labelled OpenID Connect metadata document →
OPENID_CONNECT_METADATA_DOCUMENT. - Check that the URL contains
v2.0. If it does not, you have copied the v1 endpoint and the Keyserver will reject the tokens.
The Keyserver derives every other OAuth2 endpoint it needs from this one URL.
Add an owner to the application¶
Select Manage → Owners → Add owners, and choose your own account (typically the Global Administrator).
Choose version 2 access tokens¶
The Keyserver uses the v2.0 endpoints, so the application must issue version 2 access tokens (the ver claim):
- Select Manage → Manifest.
- Select the Microsoft Graph App Manifest tab if it is not already active.
- Under
api, setrequestedAccessTokenVersionto2. - Click Save.
Expose the Keyserver API — the keyserver scope¶
This scope sets the token audience the Keyserver checks. Apart from openid, profile and email, it is the only scope used.
Create the application ID URI:
- On the application overview, select Manage → Expose an API.
-
Click Add a scope. Entra ID prompts for an application ID URI first:

-
Accept the default and click Save.
Add the scope:
- Click Add a scope again.
- Scope name:
keyserver - Who can consent: Admins and users
- State: Enabled
-
Click Add scope. The remaining fields are display text and can be anything meaningful.

Authorize the application to request its own scope:
Select Add a client application, enter the APPLICATION_ID from Initial setup, tick the scope you just created, and click Add application.
Configure API permissions¶
- Select Manage → API permissions → Add a permission.
- Choose My APIs, then the application you registered above.
- Select Delegated permissions and tick the
keyserverscope. - Click Add permissions.

Configure Workload Identity Federation (Optional)¶
Workload Identity Federation (WIF) lets Azure DevOps pipelines authenticate without a stored secret (see Microsoft's Workload identity federation concepts). It requires an App role on this registration, which the pipeline's service connection is granted. Client-credentials service accounts use the same App role.
Select Manage → App roles → Create app role:

Fill in the form as shown: Display name and Value set to ApiCaller, Allowed member types set to Applications, and the role enabled. Collect the Value for Cryptera as APP_ROLE. The Keyserver instance is configured to recognize this value, so use a different one only by agreement with Cryptera.
Configure a Service Account with Client Credentials (Optional, headless installations)¶
Standalone build servers, Jenkins, or other systems that can protect a secret use an Entra app registration as a service account (OAuth2 Client Credentials). Follow Integrate a Headless Build Server; it reuses the App role above. From this tenant it needs TENANT_ID, the Keyserver APPLICATION_ID and the APP_ROLE value.
Configure the PKCE flow (optional)¶
Configure this only if signing or certificate issuance must run from a client that cannot hold a secret, such as a desktop tool or production equipment, where an operator logs in instead.
- Select Manage → Authentication → Add a platform.
-
Choose Mobile and desktop applications:

-
Under Custom redirect URIs, enter the
PKCE_REDIRECT_URICryptera gave you. - Click Configure.
The client-side implementation is covered in the PKCE Client Integration Guide.
Hand the values back to Cryptera¶
Send Cryptera the values listed in Values to exchange with Cryptera, using the secure channel Cryptera provided.
Next, register each Entra identity as a Keyserver subject with the roles it needs. See Manage Subjects in the Keyserver.