Skip to content

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:

Register App

  1. Under Redirect URI (optional), select type Web and enter the REDIRECT_URI Cryptera gave you, of the form https://keyclient.<UNIQUE-ID>.cryptera-security.io/login/oauth2/code/keyserver-client. The Authorization Code Flow will not work without it.
  2. Click Register.
  3. From the application overview, copy two values for Cryptera:
    • Application (client) ID → APPLICATION_ID
    • Directory (tenant) ID → TENANT_ID
  4. 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

  1. On the Overview page, click Endpoints.
  2. Copy the URL labelled OpenID Connect metadata document → OPENID_CONNECT_METADATA_DOCUMENT.
  3. 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):

  1. Select Manage → Manifest.
  2. Select the Microsoft Graph App Manifest tab if it is not already active.
  3. Under api, set requestedAccessTokenVersion to 2.
  4. 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:

  1. On the application overview, select Manage → Expose an API.
  2. Click Add a scope. Entra ID prompts for an application ID URI first:

    Add Application ID URI

  3. Accept the default and click Save.

Add the scope:

  1. Click Add a scope again.
  2. Scope name: keyserver
  3. Who can consent: Admins and users
  4. State: Enabled
  5. Click Add scope. The remaining fields are display text and can be anything meaningful.

    Add Scope

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

  1. Select Manage → API permissions → Add a permission.
  2. Choose My APIs, then the application you registered above.
  3. Select Delegated permissions and tick the keyserver scope.
  4. Click Add permissions.

Request API Permission

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:

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.

  1. Select Manage → Authentication → Add a platform.
  2. Choose Mobile and desktop applications:

    Add a platform

  3. Under Custom redirect URIs, enter the PKCE_REDIRECT_URI Cryptera gave you.

  4. 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.