Azure Entra ID Integration Guide¶
This guide explains how to integrate Azure Entra ID with the Cryptera Keyserver.
Entra ID serves as the external identity provider for:
- Human users (UI login)
- CI/CD clients (Azure DevOps pipelines)
- Provisioning tools (PKCE-enabled)
- Service accounts performing automated signing
The Keyserver does not manage users or passwords internally.
All authentication flows rely on standard OAuth2 or OpenID Connect (OIDC) tokens issued by Entra ID.
Overview¶
Azure Entra ID provides:
- OAuth2 Authorization Code Flow for human users
- OAuth2 Client Credentials Flow for service clients
- Workload Identity Federation (WIF) for Azure DevOps pipelines
- PKCE-enabled Authorization Code Flow for provisioning devices on "public" clients
- JWKS endpoint for token signature verification
The Keyserver validates all tokens locally using Entra ID’s published signing keys.
Keyserver configuration with Microsoft Entra ID/Azure - Customer Administrator Part¶
Access to Keyserver's approval- and administration area is performed using a user registered in Microsoft Entra ID (former Azure AD) to do a web login. In some cases, access to Keyservers firmware signing and/or device certificate creation functionality also needs to be performed using an Entra ID/Azure user. This is the case if the customer has no secured provisioning client that can be trusted with Access token and client secret thus ruling out a Client Credentials Flow.
To implement this, one of the following flows can be configured.
Note: It is important that all steps are followed exactly, as the Keyserver backend relies on the exact configuration.
Authorization Code Flow (and Open ID Connect) with BFF¶
In this flow, the user logs into KeyServer's backend-for-frontend called the "keyclient" using the BFF pattern. This keyclient handles the Authorization Code Flow between the webbrowser and Entra ID/Azure. The role of the keyclient in the BFF pattern is to host the Client Secret and obtain the ID token and Access Token on behalf of the user behind a web browser thus avoiding exposing the token and client secret to an insecure environment. The keyclient also hosts Keyservers approval- and administration area ((Javascript SPA) and acts as a proxy for interaction with KeyServer's backend. Note that this flow cannot be used for the actual firmware signing and/or device certificate creation.
PKCE-enhanced Authorization Code Flow (Optional)¶
In cases where the customer has no secured client for handling the provisioning of devices (flashing signed firmware and/or device certificates) the need for a "public" client is needed. As such a public client is unprotected (as opposed to the keyclient in the BFF pattern) the access to KeyServer's firmware signing and/or device certificate creation must be protected using an Azure user doing a web login. To facilitate this, THE PKCE-enhanced flow comes into play. This flow is a an extension of the classic Authorization Code Flow that protects the Authorization code from hijacking by introducing a Code Challenge and Code Verifier scheme but still delivers Access token to the client.
Reading Guide¶
The following guide covers both flows as they are almost identical to setup. First, the setup of the standard Authorization Code Flow is described. Then the PKCE addition is described.
In a few places the reader is instructed to copy some data which is needed for configuring the customers KeyServer instance to interact with Azure. This will be explicitly noted.
You need to obtain the following values from Cryptera:
REDIRECT_URI
PKCE_REDIRECT_URI
The last is only required if configuring the PKCE flow
You must collect the following values from the setup and deliver to Cryptera
TENANT_ID
APPLICATION_ID
CLIENT_SECRET
OPENID_CONNECT_METADATA_DOCUMENT
APP_ROLE (Only if this app registration should be associated with an Azure DevOps service connection)
Initial setup¶
Assuming that you have a tenant registered, go into the overview page and choose Add->App Registration from the menu. This gives the following page:
Input the REDIRECT_URI (https://keyclient.
Pressing register gives the an application overview:
From this page, the configuration Application (client) ID is seen. Copy this value as APPLICATION_ID for Cryptera. Also copy the Directory (tenant) ID' as TENANT_ID
Then we need to create Client Credentials. This is needed for the communication between the Keyclient and Entra ID/Azure. Press the Add a certificate or secret link and press New client secret. Copy the Value as (CLIENT_SECRET) for Cryptera. As the name implies, this value is highly confidential!. The secret cannot be viewed in Azure after leaving the page so copy immediately!
Getting OpenID Connect metadata document URL¶
On the Overview page, click the menu Endpoints and copy the URL named OpenID Connect metadata document as(OPENID_CONNECT_METADATA_DOCUMENT) for Cryptera. Verify that the value contains "v2.0"!
From this URL, Keyserver will optain all the required URLs needed to perform the OAuth2 Authorization Code flow.
Add Owner of application¶
Select Manage->Owners and click Add owners. Choose yourself (i.e. the Global Administrator or the like). Select the user.
Choose version 2 access tokens¶
As we use v2.0 endpoints in Entra ID/Azure, we need to specify that we need "version 2" access tokens ("ver" claim). This is done in the Manifest. Select Manage->Manifest in the menu to the left. Now click the tab Microsoft Graph App Manifest if not already selected and under "api", find the property requestedAccessTokenVersion and set it to 2. Click Save
Expose keyserver API - the keyserver scope¶
To allow Keyserver to validate that the authorizing Access Token is intended for Keyserver we need to configure a keyserver scope. Currently, only one scope is in use besides the standard Open ID Connect scopes (openid, profile and email).
On the Application overview page, select Manage->Expose API and press the Add a scope link. This will show:
Select Save to create the application ID URI.
Now press Add a scope and enter keyserver into the Scope name field and select Admins and users can consent. The field State is set to Enabled The rest of the fields are of less importance. Finally, click Add scope
Then select Add a client application, input the Application (client ID)/APPLICATION_ID and select the scope created above. Press "Add application"
Configure API Permission¶
Now add API permissions by selecting Manage->API Permissions. Select Add a permission. Select My APIs and choose the application (test-app). Select Delegated permissions and click the keyserver scope.
Save changes by clicking Add permissions
Configure Workload Identity Federation (Optional)¶
When using Entra ID with services like Azure DevOps, Workload Identity Federation (WIF) can be used to authenticate CICD against the keyserver using existing Entra ID infrastructure with the addition of an addition App registration. If this app registration is going to be used as "External Identity Provider" as described in the Microsoft resource at Workload identity federation concepts in an Azure DevOps setup it is necessary to create an "App role". This App role is used to connect this app registration to a "Service Registration" where this App Role must be selected. Select App roles in the menu under Manage and click Create app role: 
Display name and value can be chosen freely but the contents of the Value-field must be collected for cryptera as APP_ROLE
Configure PKCE flow (Optional)¶
If there is no secure client for storing credentials like on a Desktop PC or production equipment, the PKCE flow can be used.
To support this flow, it's necessary to to configure a special redirect uri. Click on Manage->Authentication and click Add a platform and select "Mobile and desktop applications". This gives the following dialog:
Click Insert PKCE_REDIRECT_URI into the "Custom redirect URIs" field and press "Configure".
The Azure application is now ready to use. Send the copied values to Cryptera in an agreed secure way so Keyserver can be configured to use the new Entra ID/Azure application.
Summary¶
You have now configured Azure Entra ID to:
- Authenticate human users using Authorization Code Flow
- Authenticate CI/CD using Client Credentials or (Optionally) WIF
- (Optionally) Enable PKCE for provisioning workflows
- Provide signed JWTs that the Keyserver validates locally
- Allow role-based access control through Keyserver subjects
Azure Entra ID now serves as a secure, scalable identity backbone for all Keyserver interactions.