Verifier M2M Integration Guide

• 1. Introduction
• 2. Integration Steps

1. Introduction

Purpose and scope

This runbook explains how a backend service or component can integrate with the Verifier as an Authorization Server (AS) in M2M mode. It provides the end-to-end steps needed by developers: from preparing configuration and credentials, to calling the Token Endpoint with a LEARCredentialMachine, to using access tokens to consume protected APIs.

• Integration of backend services with the Verifier using M2M authentication.

• Use of LEARCredential inside a Verifiable Presentation (VP) as the client assertion.

• OAuth 2.1 client_credentials profile with Private Key JWT.

• Token acquisition and usage for accessing Verifier-protected resources.

• Security, error handling, observability.

Intended audience

• Developers building components/services in the ecosystem.

• Technical integrators responsible for connecting a system to the Verifier.

• SRE and security engineers validating compliance.

High‑level architecture

1. Client requests access token from Verifier Token Endpoint using client_credentials grant and client_assertion = VP (containing LEARCredentialMachine).

2. Verifier authenticates client, validates VP and LEARCredentialMachine.

3. Verifier issues access token with 1h lifetime.

4. Client uses access token to call protected resources.

High-level flow

1. The client requests an access token by authenticating with the authorization server (VCVerifier) and presenting the authorization grant. Since the client authentication is used as the authorization grant, no previous authorization request is needed.

2. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.

3. The client requests the protected resource from the resource server and authenticates by presenting the access token.

4. The resource server validates the access token presented and if valid, returns the resource requested.

2. Integration Steps

Prerequisites

• Legal entity has completed onboarding in the ecosystem.

• LEAR can access the Issuer service and issue a LEARCredentialMachine to its machine(s).

• DID method supported: did:key.

• Access to developer documentation and test environment URLs.

Step 1 - Machine credential issuance

• The legal entity accesses the Issuer service and issues a LEARCredentialMachine to its machine.

• The service generates a key pair that is bound to the LEARCredentialMachine. Keep the Private Key secure.

• The machine obtains a DID identifier. This DID will act as the client identifier. The DID is the result of using the public key of the key pair in a did:key format.

• The LEARCredentialMachine is a JWT VC.

• The process to obtain the LEARCredentialMachine in the LEAR wallet is similar to the other VC issuances.

Outcome: machine holds a valid LEARCredentiaMachine bound to its DID.

Step 2 - Client configuration

• Client type: confidential.

• Store LEARCredentialMachine and Private Key securely (Vault, HSM).

Outcome: client is ready to authenticate.

Step 3 - Acquire token

To acquire a token, the client must build a Verifiable Presentation (VP) that contains the LEARCredentialMachine (as jwt_vc_json), sign this VP as a JWT with the machine’s private key, embed it inside a client assertion JWT with the required claims, and finally POST a client_credentials request to the Verifier Token Endpoint.

Build the VP JWT (vp_token)

LEARCredentialMachine as a JWT VC string. If it is stored Base64‑encoded, decode it first.

VP object claims:

• @context

• type

• verifiableCredential

Example VP object:

VP JWT claims (signed with the machine private key):

• iss = DID of the machine (same as ‘sub’ in LEARCredentialMachine).

• sub = DID of the machine.

• aud = Verifier Token Endpoint URL.

• iat = current time (seconds).

• nbf = same as iat.

• exp = short expiry (e.g. iat + 10s).

• jti = UUID (unique).

• vp = VP object above.

Example VP JWT payload:

Build the client assertion JWT

Claims (profile):

• iss = DID of the machine.

• sub = DID of the machine.

• aud = Verifier Token Endpoint URL (issuer identifier per RFC 8414).

• jti = UUID v4 (single use).

• iat = current time in seconds.

• exp = iat + 10 seconds (short lifetime to prevent replay).

• vp_token= base64url (unpadded) encoding of the VP JWT string.

Correctness rules:

• Use NumericDate in seconds for iat/exp.

• Use base64url per RFC 7515 for vp_token, not standard Base64.

• Do not include presentation_submission.

• Sign with machine private key (Header: alg = ES256 or RS256, kid = DID key).

Make the request

• Endpoint: POST /token

• Content-Type: application/x-www-form-urlencoded

• Parameters:

• grant_type=client_credentials (REQUIRED)

• client_id=<DID or configured client id> (REQUIRED)

• client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer (REQUIRED)

• client_assertion=<JWT> (REQUIRED)

Obtain the response

If the request is valid, the Verifier issues an access token:

• Cache-Control: no-store must be included in the response.

• Refresh tokens are not supported.

Format of the access_token:

Pitfalls to avoid

• Milliseconds vs seconds in time claims.

• Using Base64 instead of Base64URL.

• Wrong iss/sub values (must be DID).

• VP with more than one LEARCredentialMachine.

• Replay attacks: enforce unique ‘jti’ within the expiration window.