2. Integration Steps

Prerequisites

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

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

• The end user (employee, contractor, etc.) has received a Verifiable Credential issued by the LEAR of their organization.

• DID method supported: did:key.

• Access to developer documentation and environment URLs (Verifier Authorization Server and APIs).
  

Step 1 – User credential issuance

The organization’s LEAR uses the Issuer service to issue a Verifiable Credential to the employee or user who will log in through the public client.

• The credential is bound to the user’s DID.

• It includes roles or permissions within the organization.

• The credential is stored in the user’s Wallet application, which can later present it during authentication.

Outcome:
User holds a valid LEAR Credential stored in their wallet and ready to be presented during the login process.

Step 2 – Client configuration

Client type: Public (web or mobile app).

• Obtain and store the assigned client_id, which can be a did:key or a unique identifier.
• Register the  redirect_uri.

• Implement PKCE support (code_challenge / code_verifier) to protect the authorization code exchange.

• Ensure secure handling of redirects and state parameters.

Outcome:
Public client is configured and ready to initiate the OAuth 2.1 Authorization Code Flow with PKCE.

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 4 – Authorization request

The public client initiates the authentication process by redirecting the user to the Verifier’s Authorization Endpoint, including the required parameters:

• 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 recommended if you rely on the ID token)

• code_challenge (derived from code_verifier)

• code_challenge_method=S256

Non-normative example:

Outcome:
User is redirected to the Verifier login screen and authenticates using their Wallet and Verifiable Credential.

Step 5 – Authorization response

After successful authentication and consent, the Authorization Server redirects the user back to the client with the authorization code and state.

Non-normative example:

Outcome:
The public client receives the authorization code and verifies that the returned state matches the one it initially sent.

Step 6 – Token request

The client exchanges the received authorization code for tokens by calling the Token Endpoint.
This request must include the original code_verifier used to generate the challenge.

Non-normative example:

Outcome:
The Verifier validates the code and code_verifier and issues an access token and ID token.

Step 7 – Token response

Non-normative example:

Outcome:

• access_token is used to call protected APIs on the Verifier.

• id_token identifies the authenticated user.

• Tokens have a limited lifetime (typically 1 hour).

Step 7 – Use access token

The public client includes the access token in the Authorization header when calling Verifier-protected APIs:

The Verifier validates the token, checks its signature and expiration, and grants access to the requested resources.

Pitfalls to avoid

• Mismatch between client_id or redirect_uri in request and registration.

• Missing or incorrect code_verifier / code_challenge.

• Using a weak or predictable state value (CSRF risk).

• Reusing authorization codes.

• Not handling token expiration and refresh flow.

• Forgetting to set Cache-Control: no-store in responses.