How-To: Integrate the Keyserver with Azure DevOps¶
Sign from Azure DevOps Pipelines without storing a secret. The pipeline authenticates through Azure Entra ID Workload Identity Federation (WIF), creates a Keyserver operation, waits for approval, signs through the PKCS#11 library and verifies the signature.
How it works¶
sequenceDiagram
participant P as Pipeline job (AzureCLI task)
participant E as Entra ID
participant K as Keyserver
P->>E: Exchange federated pipeline identity<br/>(service connection, WIF)
E-->>P: Access token (aud=Keyserver app,<br/>roles=[APP_ROLE])
P->>K: POST /api/operations (Bearer token)
K-->>P: 201 operation id
P->>K: Sign orders (PKCS11 module or REST)
K-->>P: SignatureDiagram: Pipeline job (AzureCLI task); Entra ID; Keyserver; Exchange federated pipeline identity (service connection, WIF); Access token (aud=Keyserver app, roles=[APP_ROLE]); POST /api/operations (Bearer token); 201 operation id; Sign orders (PKCS11 module or REST); Signature
The AzureCLI task exchanges the pipeline's federated identity, established by the service connection, for an Entra ID access token. No secret is stored. The Keyserver validates the token locally against Entra's published signing keys and maps the token's azp claim (the service connection app registration's Application (client) ID) to a registered client subject. The subject's roles decide which keys the pipeline may use, and the audit log records every order under that subject.
Prerequisites¶
- An Azure DevOps account with a self-hosted or Microsoft-hosted Debian or Ubuntu pipeline agent with
sudo,openssl,curlandjq(andgitand Docker, if you build the library from source) - The OpenSSL PKCS#11 engine (
libengine-pkcs11-openssl). The pipeline installs it if missing. The engine is removed in OpenSSL 4.x. For the provider alternative, see Provider interface in the PKCS#11 Library Reference. - You have completed the Azure Entra ID guide, including its Workload Identity Federation section
- You know your assigned Keyserver URL:
*.<UNIQUE-ID>.cryptera-security.io - A signing key configured with the approval requirements you need
- The
KSC_*environment variables and the OpenSSL configuration used below are documented in the PKCS#11 Library Reference
Step 1: Set Up the Azure DevOps Service Connection¶
The service connection gets its own app registration in Entra ID, which is granted the App role on the Keyserver's app registration.
- In the Project Settings of the project that needs Keyserver access, open the Service connections tab and click New service connection.
-
Select Azure Resource Manager and fill in:
- Identity type: App registration (automatic)
- Credential: Workload identity federation
- Scope level: Subscription
- Subscription: an active subscription
- Service Connection Name: any name; the pipeline references it
- Grant access permission to all pipelines: leave unchecked; authorize pipelines individually
Click Save. 3. On the new service connection, click Manage App registration. This opens its app registration in the Azure portal. Note the Application (client) ID; it becomes the Subject ID in the Keyserver. 4. Click Add an Application ID URI, then Add next to Application ID URI. Accept the default value and click Save. 5. Under API Permissions, click Add a permission, select APIs my organization uses (or My APIs), and choose the Keyserver's app registration from the Azure Entra ID guide. 6. Select Application permissions, tick the App role created in that guide, and click Add permission. 7. Click Grant admin consent for your tenant.
Step 2: Register the Service Connection as a Keyserver Subject¶
Create one Keyserver subject per service connection. Several service connections give finer control over which pipelines can use which keys.
In the Keyserver:
- Create a client subject
- Set the name to something that links it with the service connection
- Set Subject ID to the Application (client) ID noted in Step 1
- Assign roles (for example a role built from the fwsigner nature scoped to fw-quickstart). The subject must be able to sign and to read the status of a pending operation
Step 3: Acquire and Verify the Access Token¶
The AzureCLI task exchanges the pipeline's identity for an access token. Set azureSubscription to the name of the service connection from Step 1 (the surrounding pipeline is shown in Step 4):
- task: AzureCLI@2
name: GetToken
displayName: "Acquire Azure access token to access Keyserver API"
inputs:
azureSubscription: '<YOUR SERVICE CONNECTION NAME>'
scriptType: 'bash'
scriptLocation: 'inlineScript'
inlineScript: |
set -Eeuo pipefail
ACCESS_TOKEN=$(az account get-access-token \
--tenant $(TENANT_ID) \
--scope $(SCOPE) \
--query accessToken -o tsv)
if [ -z "$ACCESS_TOKEN" ]; then
echo "##vso[task.logissue type=error]Failed to acquire access token"
exit 1
fi
echo "##vso[task.setvariable variable=KSC_ID_TOKEN;issecret=true]$ACCESS_TOKEN"
The task sets the secret variable KSC_ID_TOKEN (an access token, despite the name).
While bringing the integration up, add a temporary task that decodes the token's claims and check them against the table. It prints the claims, never the token:
- task: Bash@3
displayName: "Verify token claims (remove after setup)"
env:
KSC_ID_TOKEN: $(KSC_ID_TOKEN)
inputs:
targetType: inline
script: |
PAYLOAD=$(printf '%s' "$KSC_ID_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}'
| Claim | Must be | If it is not |
|---|---|---|
iss | https://login.microsoftonline.com/<TENANT_ID>/v2.0 | Wrong TENANT_ID, or the token is rejected (401) |
ver | "2.0" | Set requestedAccessTokenVersion to 2 on the Keyserver app registration's manifest |
aud | The Keyserver app registration's client ID (or its api:// URI) | SCOPE points at the wrong app. It must be api://<KEYSERVER_APP_ID>/.default |
azp | The service connection app's Application (client) ID | This value must match the Subject ID from Step 2, otherwise 401 "The user/client is not valid" |
roles | Contains the App role from the Entra ID guide | Admin consent on the API permission is missing (Step 1) |
Step 4: Create the Pipeline¶
The pipeline below:
- Downloads (or builds) the PKCS#11 library
- Acquires an access token
- Creates an operation
- Waits for approval
- Signs a test file through the library
- Verifies the signature
The complete file is available for download at the end of this step: Download the complete pipeline.
Define the initial pipeline¶
The example uses a self-hosted agent named azure-runner; adjust the pool section to your agents. Adapt the variables:
- KEYSERVER: your assigned Keyserver URL
- KEYID: the key name as shown in the Keyserver UI
- TENANT_ID: tenant ID of the primary Azure Entra ID
- CLIENT_ID: client ID of the Keyserver's app registration in the primary Entra ID (not the service connection)
- OP_DESCRIPTION: operation description shown to approvers and in the audit log
trigger:
- main
pool:
name: 'Development'
demands:
- Agent.Name -equals azure-runner
variables:
KEYSERVER: 'https://keyserver.<UNIQUE-ID>.cryptera-security.io'
HASH_ALGORITHM: '-sha256'
KEYID: 'fw-quickstart'
TENANT_ID: 'AZURE ENTRA ID TENANT ID'
CLIENT_ID: 'AZURE ENTRA CLIENT ID (of the primary Entra ID, not the service connection)'
SCOPE: 'api://$(CLIENT_ID)/.default'
OP_DESCRIPTION: 'Azure DevOps PKCS#11 signing'
stages:
- stage: SignBinary
displayName: "Sign Binary"
jobs:
- job: Main
displayName: "Main signing flow"
steps:
# First step: the AzureCLI@2 GetToken task from Step 3
Get the PKCS#11 library¶
Download the prebuilt library to the path the later steps expect. Keep the version pinned and record the module's SHA-256, as Getting the library describes. Cryptera does not publish checksums for it.
- task: Bash@3
displayName: Download prebuilt libpkcs11ks
inputs:
targetType: inline
script: |
set -euo pipefail
mkdir -p "$(Pipeline.Workspace)/scripts"
curl -sSL --fail -o "$(Pipeline.Workspace)/scripts/libpkcs11ks.so" \
https://github.com/cryptera-device-security/libpkcs11ks/releases/download/v1.0.4/libpkcs11ks.so
# Check the SHA-256 you recorded on first download:
# echo "<RECORDED_SHA256> $(Pipeline.Workspace)/scripts/libpkcs11ks.so" | sha256sum -c -
Optional: Build the library from GitHub sources
Use this task instead of the download to build the library on the agent with Docker. It writes to the same path under $(Pipeline.Workspace), so no later step changes.
- task: Bash@3
displayName: Build libpkcs11ks from source (Docker)
inputs:
targetType: inline
script: |
set -euo pipefail
SRC_DIR=$(Pipeline.Workspace)/libpkcs11ks-src
OUT_DIR=$(Pipeline.Workspace)/scripts
rm -rf "$SRC_DIR"
git clone --depth=1 --branch v1.0.4 \
https://github.com/cryptera-device-security/libpkcs11ks.git "$SRC_DIR"
cd "$SRC_DIR"
docker build -t libpkcs11ks .
mkdir -p "$OUT_DIR"
docker run --rm -v "$OUT_DIR:/output" libpkcs11ks
built=$(find "$OUT_DIR" -maxdepth 1 -name 'libpkcs11ks*.so' | head -n1)
if [ -z "$built" ]; then
echo "libpkcs11ks.so not found after build"; exit 1
fi
dest="$OUT_DIR/libpkcs11ks.so"
if [ "$built" != "$dest" ]; then
cp -f "$built" "$dest"
fi
ls -l "$dest"
Install and locate the OpenSSL PKCS#11 engine¶
The engine's path varies by distribution, so this step discovers it and fails early if it is missing.
- task: Bash@3
name: EnsurePkcs11Engine
displayName: "Install and locate the OpenSSL PKCS#11 engine"
inputs:
targetType: inline
script: |
set -euo pipefail
if ! dpkg -s libengine-pkcs11-openssl >/dev/null 2>&1; then
sudo apt-get update
sudo apt-get install -y libengine-pkcs11-openssl
fi
# openssl reports its module directory; the engine lives in engines-<major>
ENGINE_DIR="$(openssl version -e | sed -E 's/^ENGINESDIR: "(.*)"$/\1/')"
ENGINE_PATH="$ENGINE_DIR/pkcs11.so"
[ -f "$ENGINE_PATH" ] || ENGINE_PATH="$ENGINE_DIR/libpkcs11.so"
if [ ! -f "$ENGINE_PATH" ]; then
echo "##vso[task.logissue type=error]PKCS#11 engine not found under $ENGINE_DIR"
exit 1
fi
echo "Using PKCS#11 engine: $ENGINE_PATH"
echo "##vso[task.setvariable variable=PKCS11_ENGINE_PATH;issecret=false]$ENGINE_PATH"
On a self-hosted agent you can preinstall the package on the image and drop the apt-get lines. Keep the existence check.
Generate OpenSSL PKCS#11 config¶
Write an OpenSSL configuration that loads the library through the engine. A static file in the repository works as well.
- task: Bash@3
displayName: Generate OpenSSL PKCS#11 config
inputs:
targetType: inline
script: |
set -euo pipefail
cat >$(Pipeline.Workspace)/scripts/openssl-ks.cnf <<'EOF'
openssl_conf = openssl_init
[openssl_init]
engines = engine_section
providers = provider_sect
[provider_sect]
default = default_sect
base = base_sect
[default_sect]
activate = 1
[base_sect]
activate = 1
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = $(PKCS11_ENGINE_PATH)
MODULE_PATH = $(Pipeline.Workspace)/scripts/libpkcs11ks.so
init = 0
EOF
echo "##vso[task.setvariable variable=OPENSSL_CONF;issecret=false]$(Pipeline.Workspace)/scripts/openssl-ks.cnf"
Create Keyserver Operation¶
Keep validity longer than the approval wait
This task creates the operation with validms: 900000 (15 minutes). The wait task that follows polls for up to 12 × 10 s = 2 minutes, leaving margin for signing. If you lengthen the wait, raise validms to match. Otherwise the sign task fails with 410 "Operation has expired" even though the approver acted in time. Always keep validms > (approval wait + signing time).
Create an operation for one use of $(KEYID):
- task: Bash@3
displayName: Create Keyserver operation
env:
KSC_ID_TOKEN: $(KSC_ID_TOKEN)
KSC_API_SERVER: $(KEYSERVER)
KSC_OPERATION_DESCRIPTION: $(OP_DESCRIPTION)
inputs:
targetType: inline
script: |
set -euo pipefail
: "${KSC_ID_TOKEN:?Missing KSC_ID_TOKEN}"
BODY=$(jq -n --arg d "$KSC_OPERATION_DESCRIPTION" --arg k "$(KEYID)" \
'{validms: 900000, description: $d, "new-keyusagerestrictions": [{keyid: $k, maxusagecount: 1}]}')
RESPONSE=$(curl -sS --tlsv1.3 -X POST "$KSC_API_SERVER/api/operations" \
-H "Authorization: Bearer $KSC_ID_TOKEN" -H "Content-Type: application/json" \
-d "$BODY") || { echo "Create-operation request failed"; exit 1; }
KSC_OPERATION_ID=$(jq -r '.id // empty' <<<"$RESPONSE" 2>/dev/null || true)
if [ -z "$KSC_OPERATION_ID" ]; then
echo "Failed to create operation. Keyserver response:"
printf '%s\n' "$RESPONSE"
exit 1
fi
echo "##vso[task.setvariable variable=KSC_OPERATION_ID;issecret=false]$KSC_OPERATION_ID"
echo "Operation ID: $KSC_OPERATION_ID"
Wait for Approval¶
If the key requires approvers, this task waits until the operation is approved. Otherwise it continues at once.
- task: Bash@3
name: WaitForApproval
displayName: "Wait for signing approval"
env:
KSC_ID_TOKEN: $(KSC_ID_TOKEN)
KSC_OPERATION_ID: $(KSC_OPERATION_ID)
KSC_API_SERVER: $(KEYSERVER)
inputs:
targetType: inline
script: |
set -euo pipefail
: "${KSC_ID_TOKEN:?Missing KSC_ID_TOKEN}"
for i in {1..12}; do
# A network error or a 5xx counts as "not yet". Any other refusal, such as
# 410 "Operation is cancelled", ends the wait at once.
RESP=$(curl -sS --tlsv1.3 -w '\n%{http_code}' \
"$KSC_API_SERVER/api/operations/$KSC_OPERATION_ID" \
-H "Authorization: Bearer $KSC_ID_TOKEN") || RESP=$'\n000'
CODE=${RESP##*$'\n'}
case "$CODE" in
200) STATUS=$(jq -r '.approved' <<<"${RESP%$'\n'*}") ;;
000|5??) STATUS="error" ;;
*) echo "Keyserver refused the poll (HTTP $CODE):"; printf '%s\n' "${RESP%$'\n'*}"; exit 1 ;;
esac
echo "Attempt $i - Approved: $STATUS"
[ "$STATUS" = "true" ] && exit 0
sleep 10
done
echo "Approval timeout"
exit 1
Perform Signing Operation¶
Sign test.txt through the library:
- task: Bash@3
displayName: Sign test file with OpenSSL + PKCS#11
env:
KSC_ID_TOKEN: $(KSC_ID_TOKEN)
KSC_OPERATION_ID: $(KSC_OPERATION_ID)
OPENSSL_CONF: $(OPENSSL_CONF)
KSC_API_SERVER: $(KEYSERVER)
KSC_OPERATION_DESCRIPTION: $(OP_DESCRIPTION)
KSC_HTTP_CLIENT_TIMEOUT: 15s
inputs:
targetType: inline
script: |
set -euo pipefail
: "${KSC_ID_TOKEN:?Missing KSC_ID_TOKEN}"
: "${KSC_OPERATION_ID:?Missing KSC_OPERATION_ID}"
export OPENSSL_CONF
export KSC_API_SERVER
export KSC_OPERATION_DESCRIPTION
export KSC_OPERATION_ID
echo "Test" > test.txt
openssl dgst \
-engine pkcs11 \
-keyform engine \
-sign "pkcs11:object=$(KEYID);type=private" \
$(HASH_ALGORITHM) \
-out test.txt.sig \
test.txt
echo "Signature written to test.txt.sig"
Validate the signature¶
Download the key's certificate and verify the signature against it:
- task: Bash@3
name: GetCertificate
displayName: "Download certificate for signing key (for validation)"
env:
KSC_ID_TOKEN: $(KSC_ID_TOKEN)
KSC_API_SERVER: $(KEYSERVER)
inputs:
targetType: inline
script: |
set -Eeuo pipefail
: "${KSC_ID_TOKEN:?Missing KSC_ID_TOKEN}"
: "${KSC_API_SERVER:?Missing KSC_API_SERVER}"
curl --fail-with-body -sS --tlsv1.3 \
-H "Authorization: Bearer $KSC_ID_TOKEN" \
-H "Accept: application/json" \
"$KSC_API_SERVER/api/keys/$(KEYID)" \
| jq -er '.certificate' > certificate.pem
test -s certificate.pem
echo "Saved certificate to certificate.pem"
- task: Bash@3
displayName: "Validate signature using certificate"
inputs:
targetType: inline
script: |
set -Eeuo pipefail
test -s certificate.pem
test -s test.txt
test -s test.txt.sig
# Extract pubkey from cert
openssl x509 -in certificate.pem -pubkey -noout > pubkey.pem
test -s pubkey.pem
# Verify signature
openssl dgst \
-verify pubkey.pem \
$(HASH_ALGORITHM) \
-signature test.txt.sig \
test.txt
echo "Signature verification OK"
Expected output:
Publish artifacts¶
Publish the signature:
- task: PublishBuildArtifacts@1
displayName: Publish signature
inputs:
PathtoPublish: "$(System.DefaultWorkingDirectory)"
ArtifactName: signed-output
publishLocation: "Container"
Expected outputs per stage¶
| Stage | Success looks like |
|---|---|
| Acquire token | Task succeeds silently; KSC_ID_TOKEN is set as a secret variable (never printed) |
| Get library | libpkcs11ks.so present in $(Pipeline.Workspace)/scripts |
| Create operation | Operation ID: <uuid> in the log |
| Wait for approval | Attempt N - Approved: true, then the task exits 0 |
| Sign | Signature written to test.txt.sig |
| Validate | Verified OK |
Download the complete pipeline¶
The steps above, in pipeline order, as one file: azure-pipelines.yml. It leaves out the temporary claims check from Step 3 and the optional build from source.
Review the pipeline before you run it
The file is a starting point, not a drop-in pipeline. Read every step before you commit it, and adapt it to your project:
- Replace every placeholder:
KEYSERVER,KEYID,TENANT_ID,CLIENT_ID, theazureSubscriptionservice connection name, and thepoolsection. - Set
HASH_ALGORITHMto the signing key's hash algorithm. - Keep
validmslonger than the approval wait plus the signing time. - Record the module's SHA-256 and enable the commented-out check in the download step.
- Replace the
test.txtsigning step with your own build output. - Keep secrets in Azure DevOps secret variables or the service connection, never in the file.
Operational practices¶
Practices shared by every CI integration (secrets and tokens, operation budgets, least privilege, verification) are in CI practices in the PKCS#11 Library Reference. For Azure DevOps:
- One service connection per project or purpose. Its Application (client) ID is the identity the audit log attributes orders to.
- Authorize pipelines individually. Do not grant the service connection to all pipelines; approve only the pipelines that sign.
- Remove the claims-verification task from Step 3 once the integration works. The claims are not secret, but they do not belong in routine build logs.
If something fails¶
| Symptom | Cause and fix |
|---|---|
| "Failed to acquire access token" | The service connection is not authorized for this pipeline, or TENANT_ID/SCOPE is wrong. The scope must be api://<KEYSERVER_APP_ID>/.default |
Token acquired but every Keyserver call returns 401 | The token's audience is not the Keyserver app. Check that SCOPE points at the Keyserver's app registration, not the service connection's (verify with the claims task in Step 3) |
401 "The user/client is not valid" on every call | No Keyserver subject matches the service connection's Application (client) ID. Compare the token's azp (Step 3) with the Subject ID (Step 2) |
403 "Access forbidden" | The subject's role lacks createoperation/order for $(KEYID). Check the fwsigner nature scoping |
| "Failed to create operation" | The Keyserver response is printed below it. Read properties[].message |
"Approval timeout" after Approved: false | No approver acted within the retry window. Notify approvers out-of-band |
"Approval timeout" after Approved: error | Every poll failed with a network error or a 5xx. Check KEYSERVER and that the agent can reach the Keyserver |
| "Keyserver refused the poll (HTTP 410)" | The operation was cancelled (an approver clicked Revoke) or its key revoked; the printed body says which. Run the pipeline again |
409 "Need more approvers" on sign | Signing started before approval completed. The wait task must run before the sign task |
410 "Operation has expired" | validms elapsed before signing. Raise it, or approve faster |
410 "Operation is cancelled" | An approver clicked Revoke in the Approvals view, or the operation was deleted. Run the pipeline again |
410 "Signing key has been revoked" | $(KEYID) names a revoked key. Use another key |
OpenSSL cannot find pkcs11:object=$(KEYID);type=private | KSC_ID_TOKEN/KSC_API_SERVER is missing from the signing task's env:, or the subject cannot see the key |
Full status-code reference: Error Codes. PKCS#11-specific issues: PKCS#11 Library Reference.
Related pages¶
- Integrate a Headless Build Server: client credentials for systems outside federation-capable platforms
- Integrate Keyserver with GitLab CI: the GitLab OIDC counterpart of this workflow