Integration Steps

Prerequisites

• The legal entity has completed onboarding in the DOME ecosystem.

• The LEAR has obtained a valid LEARCredentialMachine through the Issuer service.

• DID method supported: did:key.

• The confidential client (backend service or secure web app) is registered in the Verifier with its:

  • client_id (DID or URI).

  • redirect_uri (for authorization response).

  • jwks_uri (endpoint exposing the client’s public key set).

• The client’s private key is securely stored (e.g., in an HSM or vault).

• Access to developer documentation and environment URLs.

Step 1 – MachineGenerating key pair: did:key + private key

You will need a did:key / private-key pair. It can be obtained through different methods. One option we can propose is to use our Issuer: when issuing a LEARCredentialMachine, a key pair is generated for the client. The corresponding did:key is set as the mandatee.id in the credential issuance(which

Theyou LEARcan ofcheck in the organizationdetails issuespage aafter LEARCredentialMachineissuing it --no need to theactivate backendit). service (the confidential client).

• The credential is a Verifiable Credential (VC) in JWT format.

• It is bound to the machine’s DID, derived from its public key.

• The private key must be kept securely storedon your side and is never shared.

Outcome:
The machine (confidential client) holds a valid LEARCredentialMachine and its associated DID key pair.

Step 2 – Client configuration

Client type: Confidential.

• Obtain

  Registerand store the clientassigned client_id, which should be the did:key generated in the Verifier’sprevious Authorization Server.

• Provide the jwks_uri exposing the public keys used for signing JWTs.

  step.

• Ensure the redirect_uri is pre-registered and uses HTTPS.

• Implement JWT-based client authentication (client_secret_jwt). You client will need a request_uri where a signed JWT token must be exposed (see the authorization request step).

Outcome:
The confidential client is fully configured to authenticate using signed JWTs and perform the Authorization Code Flow.

Step 3 – Registering to the Verifier (Trusted Services List)

The relying party must be registered in the Trusted Services List. The data must match with your client's configuration (see step 2).

Step 34 – Authorization request

The confidential client starts the authorization process by redirecting the user to the Authorization Endpoint with athese signedparameters Authorization:

Object.
This
• object

  client_id: has to match the one in your client's configuration

• redirect_uri: has to match the one in your client's configuration

• response_type=code

• scope = openid learcredential

• state : random string

• nonce: random string (this will be added in the ID token, so it is arecommended JWTif containingyou allrely authorizationon parameters,the hostedID attoken)

  a
• request_uri.
  :

  The Authorization Server retrieves this JWT, validates its signature againstsee the client’sexplanation registeredbelow*

jwks_uri, and proceeds with the flow.

Non-normative example:

Step 45 – Authorization response

After the user successfully authenticates and authorizes access, the Authorization Server redirects back to the client’s redirect_uri with an authorization code.

Non-normative example:

Step 56 – Token request

The client exchanges the authorization code for tokens by calling the Token Endpoint.
In this step, the client authenticates using client_secret_jwt, sending a signed JWT in the client_assertion parameter.

Non-normative example:

Non-normative example of a Token Request:

Outcome:
The Authorization Server validates:

Step 67 – Token response

Non-normative example:

Outcome:

Step 78 – Use access token

The confidential client uses the access_token to call Verifier-protected APIs: