Skip to content

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: Signature

Diagram: 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, curl and jq (and git and 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.

  1. In the Project Settings of the project that needs Keyserver access, open the Service connections tab and click New service connection.
  2. 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:

  1. Downloads (or builds) the PKCS#11 library
  2. Acquires an access token
  3. Creates an operation
  4. Waits for approval
  5. Signs a test file through the library
  6. 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:

Verified OK

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, the azureSubscription service connection name, and the pool section.
  • Set HASH_ALGORITHM to the signing key's hash algorithm.
  • Keep validms longer 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.txt signing 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.