How-To: Integrate a Headless Build Server¶
This guide connects a headless machine to the Keyserver: a standalone build server, a nightly signing service, or a factory tool that can protect a secret. The machine uses the OAuth2 Client Credentials flow against an Azure Entra ID app registration and receives an access token for the Keyserver, with no human involved.
Prefer federated identity where the platform supports it
Azure DevOps (Workload Identity Federation) and GitLab CI (GitLab-issued ID tokens) store no secrets at all. See Integrate the Keyserver with Azure DevOps and Integrate the Keyserver with GitLab CI. Use a client-credentials service account when the system runs outside such a platform but can hold a secret securely (a vault, a protected CI variable, or a root-only file).
Jenkins and other self-hosted CI servers¶
CI servers without OIDC job tokens, such as Jenkins, follow this guide unchanged: keep the client secret in the CI server's credentials store and request the token inside the pipeline.
How it works¶
sequenceDiagram
participant B as Build server
participant E as Entra ID token endpoint
participant K as Keyserver
B->>E: POST client_id + client_secret<br/>scope=api://KEYSERVER_APP/.default
E-->>B: Access token (aud=Keyserver, roles=[APP_ROLE])
B->>K: POST /api/operations (Bearer token)
K-->>B: 201 operation id
B->>K: POST /api/signorders (Bearer token)
K-->>B: 201 signatureDiagram: Build server; Entra ID token endpoint; Keyserver; POST client_id + client_secret scope=api://KEYSERVER_APP/.default; Access token (aud=Keyserver, roles=[APP_ROLE]); POST /api/operations (Bearer token); 201 operation id; POST /api/signorders (Bearer token); 201 signature
The Keyserver validates the token locally against Entra's published signing keys. It then maps the token's azp claim, which for a client-credentials token is the service app registration's Application (client) ID, to a registered client subject. The subject's roles decide which keys the machine may use.
Prerequisites¶
- The base Entra ID setup for your Keyserver instance is complete: the Keyserver app registration with the
keyserverscope and version 2 access tokens, as described in the Azure Entra ID Integration Guide. Have its Application (client) ID (KEYSERVER_APPLICATION_ID) and your Directory (tenant) ID (TENANT_ID) at hand. - Rights to create app registrations and grant admin consent in your Entra tenant.
- An administrative subject on the Keyserver (to register the new client subject).
- On the headless machine:
curl,jq, andopenssl.
Step 1: Create the service app registration (Azure)¶
- In the Entra portal, choose Add → App Registration. Create one registration per service, so access rights and secret rotation stay independent per machine. No redirect URI is needed.
- On the overview page, copy the Application (client) ID (
SERVICE_APP_CLIENT_ID). It becomes the Subject ID in the Keyserver. - Under Certificates & secrets → New client secret, create a secret (
SERVICE_APP_CLIENT_SECRET). Copy it now (it is shown once) into your secret store, and note its expiry date: signing stops with authentication errors when it expires. See Secret storage and rotation.
Step 2: Authorize the service against the Keyserver app (Azure)¶
The Keyserver app registration must expose an App role, and the service app must be granted that role as an application permission:
- On the Keyserver's app registration, verify an App role exists under Manage → App roles. If your instance already uses Workload Identity Federation, the same role is reused; otherwise create one as described in the Azure guide. Set the role's Value (your
APP_ROLE) toApiCaller. Any other value must be agreed with Cryptera, or tokens are not recognized as service-account tokens. - On the service app registration: API Permissions → Add a permission → APIs my organization uses → select the Keyserver app registration → Application permissions → tick the App role → Add permissions.
- Click Grant admin consent for your tenant. Without consent, tokens are issued without the
rolesclaim and the Keyserver will not treat the caller as a service account.
If Cryptera operates your Keyserver instance and this tenant is already integrated, an additional service account needs no server-side change: the issuer, audience and App role are already configured. You only register the new subject, as in Step 5: Register the client subject in the Keyserver.
Step 3: Request a token from the headless machine¶
export TENANT_ID=<TENANT_ID>
export SERVICE_APP_CLIENT_ID=<SERVICE_APP_CLIENT_ID>
export KEYSERVER_APPLICATION_ID=<KEYSERVER_APPLICATION_ID>
# Load the secret from your secret store, e.g.:
# export SERVICE_APP_CLIENT_SECRET=$(vault kv get -field=secret secret/keyserver/service-app)
# or paste it interactively without echo or shell history:
stty -echo; printf 'Client secret: '; read -r SERVICE_APP_CLIENT_SECRET; stty echo; printf '\n'
export SERVICE_APP_CLIENT_SECRET
TOKEN=$(curl -sS -X POST \
"https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
-d "grant_type=client_credentials" \
-d "client_id=$SERVICE_APP_CLIENT_ID" \
-d "client_secret=$SERVICE_APP_CLIENT_SECRET" \
-d "scope=api://$KEYSERVER_APPLICATION_ID/.default" \
| jq -r .access_token)
export TOKEN
The scope is the Keyserver app registration's Application ID URI with /.default, so Entra issues a token with the Keyserver as audience, carrying the granted App role.
Expected: $TOKEN contains a long eyJ... string. If it is null, the error body from Entra says why; see If something fails.
Step 4: Inspect and verify the token claims¶
Before touching the Keyserver, decode the token payload and check that Entra issued what the Keyserver expects:
PAYLOAD=$(printf '%s' "$TOKEN" | cut -d '.' -f 2 | tr '_-' '/+')
while [ $((${#PAYLOAD} % 4)) -ne 0 ]; do PAYLOAD="$PAYLOAD="; done
printf '%s' "$PAYLOAD" | base64 -d | jq '{iss, aud, azp, roles, ver}'
Expected output:
{
"iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"aud": "<KEYSERVER_APPLICATION_ID>",
"azp": "<SERVICE_APP_CLIENT_ID>",
"roles": ["ApiCaller"],
"ver": "2.0"
}
| Claim | Must be | If it is not |
|---|---|---|
iss | https://login.microsoftonline.com/<TENANT_ID>/v2.0 | The Keyserver rejects tokens from unconfigured issuers |
ver | "2.0" | Set requestedAccessTokenVersion to 2 in the Keyserver app registration's manifest (the resource app decides the token version) |
aud | The Keyserver Application (client) ID | Wrong scope parameter in the token request |
azp | The service app's client ID | This is the value to register as the Subject ID in Step 5 |
roles | Contains your APP_ROLE (ApiCaller by convention) | Admin consent is missing (Step 2) |
A client-credentials token has no scp claim. That is expected and accepted.
Step 5: Register the client subject in the Keyserver¶
In the Keyserver UI, within an administrative session, create a subject as described in Manage Subjects:
- Subject ID: the
azpvalue verified in Step 4, the service app's Application (client) ID as it appears in the token. This is the field matched against the token; putting it in Subject name instead yields401"The user/client is not valid" on every call. - Subject name: any readable label for the machine, e.g.
nightly-build-server. Not matched against anything. - Type: Client.
- Description: what the machine does, e.g.
Nightly firmware signing server, building X. - Roles: a role built from the
fwsignernature for the key(s) the machine signs with (e.g.ci-orderer-fw-quickstart), or from thedevcertsignernature for device certificate issuance. Grant nothing else.
Step 6: Run an end-to-end signing check¶
From the headless machine, with $TOKEN from Step 3:
export KEYSERVER=https://keyserver.<UNIQUE-ID>.cryptera-security.io
export KEYID=<your key id>
OPERATION_ID=$(curl -sS --tlsv1.3 -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
"$KEYSERVER/api/operations" \
-d "{
\"validms\": 600000,
\"description\": \"Client credentials end-to-end check\",
\"new-keyusagerestrictions\": [
{ \"keyid\": \"$KEYID\", \"maxusagecount\": 1 }
]
}" | jq -r .id)
echo "$OPERATION_ID"
Expected output, the operation's UUID:
If the key requires approvers, approve the operation in the Keyserver UI before continuing. Pipelines poll GET /api/operations/$OPERATION_ID until approved is true; see Sign Code Using the REST API.
Then submit a sign order for a test digest:
DIGEST=$(printf '%s' "client credentials smoke test" | openssl dgst -sha256 | cut -d ' ' -f 2)
curl -sS --tlsv1.3 -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
"$KEYSERVER/api/signorders" \
-d "{
\"operationid\": \"$OPERATION_ID\",
\"keyid\": \"$KEYID\",
\"inputdata\": \"$DIGEST\",
\"inputformat\": \"hex\",
\"signatureformat\": \"asn1\",
\"description\": \"Client credentials smoke test\"
}" | jq -r .result
Expected output, the signature as a hex string (here ASN.1 ECDSA):
The machine is now integrated. The complete signing flow with signature verification is in Tutorial Part 2: Sign Code Using the Trial Environment, and its production deltas in Sign Code Using the REST API.
Running it repeatedly¶
Step 1, Step 2 and Step 5 are one-time setup, and the claims check in Step 4 is only needed when a token is rejected. After that, every signing job on the machine does the following:
- Load the client secret from the secret store.
- Request a fresh access token as in Step 3. Tokens last about one hour; do not cache them across runs.
- Create an operation sized to the run:
maxusagecountequal to the number of signatures, andvalidmscovering the approval wait plus the signing. - If the key requires approvers, poll
GET /api/operations/$OPERATION_IDuntilapprovedistrue. Sign Code Using the REST API shows the loop. - Sign: submit sign orders as in Step 6, or run a PKCS#11 tool with
KSC_API_SERVER,KSC_OPERATION_IDandKSC_ID_TOKENset.KSC_ID_TOKENholds the access token; the variable name is historical. See PKCS#11 Library Reference (libpkcs11ks). - Verify each signature against the key's certificate before publishing it.
- If the run fails before using the operation, cancel it with
DELETE /api/operations/$OPERATION_ID, or let it expire.
The practices that apply to every pipeline (tokens, operation budgets, least privilege, verification) are in CI practices.
Secret storage and rotation¶
- Store the secret in a secret manager (HashiCorp Vault, Azure Key Vault, or at minimum a root-only file with mode 600 on the machine). Never in scripts, images, or repositories.
- Rotate before expiry. Entra allows two active secrets per app registration: create the new secret, deploy it to the machine, verify that a token request succeeds, then delete the old one. The machine keeps signing throughout.
If something fails¶
| Symptom | Cause |
|---|---|
Entra returns invalid_client (AADSTS7000215) | Wrong or expired client secret |
| Entra returns AADSTS500011 ("resource principal not found") | Wrong scope. It must be api://<KEYSERVER_APPLICATION_ID>/.default |
| Keyserver returns 401 | Token invalid or expired, iss not among the instance's configured issuers, or ver is 1.0 (Step 4) |
| Keyserver returns 401 "The user/client is not valid" | The token's azp does not match a registered Subject ID. Compare Step 4 with Step 5 character by character |
| Keyserver returns 403 "Access forbidden" | Subject exists but its roles do not permit this action on this key |
| Keyserver returns 409 "Need more approvers" on sign order | Operation not yet fully approved |
| Keyserver returns 410 "Operation has expired" | validms elapsed. Create a new operation |
| Keyserver returns 410 "Operation is cancelled" | An approver clicked Revoke in the Approvals view, or the operation was deleted. Create a new operation |
| Keyserver returns 410 "Signing key has been revoked" | The key is revoked. Use another key |
See the Error Codes Reference for the full list.