Online Authentication 

The term Online Authentication is used as a shorter and more reader-friendly label for the OpenID Connect Authorization Code Flow implemented by the Digital Credential Platform.

Online Authentication is a browser-based authentication flow. It starts when the user chooses to sign in with a Digital Credential on the Relying Party side.

This section helps answer the following questions:

  • How does Online Authentication work from the Relying Party point of view?
  • How does the Relying Party initiate the Authorization Code Flow?
  • How is the browser session paired with the iD Wallet application?
  • What happens when the user approves, rejects, or lets the request time out?
  • How does the Relying Party receive and exchange the authorization code?
  • Where are the approved identity attributes returned?
  • What must be validated before access is granted?

Online Authentication can be used for scenarios such as:

  • access to online services,
  • age-based eligibility checks, for example 16+, 18+, or 21+,
  • citizenship-based access,
  • identity attribute sharing, where required by the service.

Online Authentication Integration Steps 

This section describes the configuration and integration steps that must be completed by the Relying Party to use Online Authentication with the Digital Credential Platform.

As a Relying Party, you need to:

  1. register or obtain your Relying Party client configuration,
  2. retrieve OpenID Connect metadata,
  3. prepare a test credential for authentication testing,
  4. build and send an authorization request,
  5. handle the user approval flow in the iD Wallet application,
  6. process the authorization response,
  7. exchange the authorization code for tokens,
  8. validate the ID Token and consume the shared attributes.

Step 1 — Request client registration through your partner manager 

Online Authentication is a pre-release feature. Client registration is not self-service.

Contact your IDEMIA partner manager to request access. Before reaching out, prepare the parameters listed in the Relying Party Integration Guide — specifically the Online Authentication-specific registration checklist.

After registration, you will receive:

  • client_id,
  • client credentials or key reference, depending on the configured token endpoint authentication method,
  • the platform endpoint base URL for your environment.

The values configured during registration must match the values used in all subsequent authorization and token requests.

Step 2 — Retrieve OpenID Connect Configuration 

Before initiating authentication, the Relying Party should retrieve the OpenID Connect configuration from the discovery endpoint: /.well-known/openid-configuration

The discovery response provides metadata required to configure the Relying Party client, including:

  • authorization endpoint,
  • token endpoint,
  • JWKS URI,
  • supported scopes,
  • supported claims,
  • supported response types,
  • supported grant types,
  • supported token endpoint authentication methods.

The Relying Party should use the metadata returned by the discovery endpoint instead of hard-coding endpoint URLs where possible.

For details, see the OpenAPI documentation.

Step 3 — Prepare a test credential 

Before testing, ensure the test user has a Digital Credential available in the iD Wallet application.

See Setting up a test credential in the Relying Party Integration Guide.

Step 4 — Build the Authorization Request 

To start Online Authentication, the Relying Party redirects the user agent to the Digital Credential Platform authorization endpoint: /authorize

The authorization request should include the parameters configured for the registered Relying Party client.

Typical request parameters include:

  • response_type=code
    Indicates that the Relying Party expects an authorization code.

  • client_id
    Identifies the registered Relying Party client.

  • redirect_uri
    Defines where the user agent is redirected after authentication. This value must match one of the registered redirect URIs.

  • scope
    Defines the requested OpenID Connect scopes. The openid scope is required. Requested scopes determine which credential attributes may be shared. For details, see Scope and Claims Handling.

  • state
    A value generated by the Relying Party to maintain request context and prevent CSRF attacks. It is returned unchanged by the authorization server and must be validated by the Relying Party.

  • nonce
    A value used to bind the client session to the ID Token and protect against replay attacks.

  • acr_values
    Indicates the requested authentication context. For details, see Authentication Context Reference.

Example:

HTTP
1GET https://dc-api.app.dev.identity-dev.idemia.io/oxauth/restv1/authorize?
2response_type=code&
3redirect_uri=https://dc-api.app.dev.identity-dev.idemia.io/samplerp/oauth/callback&
4state=t3MIZoWuZT6WO2ja56uUFbiDDcf4k15gr54GIiI5jZE&
5client_id=FFFFFFFF-7273-6D74-0004-000000000001&
6scope=openid+org.iso.23220.1&
7acr_values=mid&
8nonce=ae74a40d-c476-4de6-ad63-16a7bb802aeb

Step 5 — User Approval in the iD Wallet Application 

After the user is redirected to the Digital Credential Platform, the platform presents a QR code or deeplink.

The QR code or deeplink is used to pair the browser session with the iD Wallet application.

  • In a desktop scenario, the user scans the QR code using the iD Wallet app.
  • In a mobile scenario, the deeplink redirects the user directly to the iD Wallet application.

Inside the iD Wallet application, the user can review:

  • the Relying Party requesting authentication,
  • the requested identity attributes.

The user may approve or reject the request.

If the user approves the request and authentication succeeds, the browser is redirected back to the Relying Party with an authorization code.

If the user rejects the request, does not act in time, or an error occurs, the browser is redirected back to the Relying Party with an error result.

In a test scenario, the tester should approve sharing the requested attributes in the iD Wallet application and wait for the authentication result.

Step 6 — Handle the Authorization Response 

After successful authentication, the browser is redirected to the redirect_uri provided in the authorization request.

The response includes:

  • code — authorization code to be exchanged at the token endpoint,
  • state — the value originally sent by the Relying Party.

The Relying Party must verify that the received state matches the value associated with the original browser session.

If the state value is missing or does not match, the response must be rejected.

The authorization code must not be treated as proof of authentication. Authentication is complete only after the code has been exchanged and the returned ID Token has been validated.

Step 7 — Exchange the Authorization Code for Tokens 

The Relying Party backend must exchange the authorization code at the token endpoint.

Typical token request parameters include:

  • grant_type=authorization_code,
  • code,
  • redirect_uri.

The redirect_uri must match the value used in the original authorization request.

Client authentication must follow the method configured during Relying Party client registration.

Step 8 — Process and Validate the Token Response 

If the token request is successful, the Digital Credential Platform returns a token response.

The ID Token contains the identity claims approved by the user and requested through OpenID Connect scopes.

The shared attributes requested by the Relying Party are returned as claims in the ID Token.

Before granting access, the Relying Party must validate the ID Token.

At minimum, the Relying Party should validate:

  • token signature using keys from the JWKS URI,
  • issuer,
  • audience,
  • expiration time,
  • issued-at time,
  • nonce,
  • expected signing algorithm,
  • required claims for the business use case.

The Relying Party should grant access after the ID Token has been successfully validated and the required claims are present.

Example of encoded value of ID Token

Text
1eyJraWQiOiI5MGQ1Mjg5OS01OGIzLTRhYTEtYWQ4Ni1mMzQ5OTYzYzA2M2Jfc2lnX3JzMjU2IiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJ..

Example of decoded value of ID Token:

JSON
1{
2  "at_hash": "ivo5Zc7DXYsqLDtOV8pHoQ",
3  "sub": "fce5148e-33d3-49cd-ae07-affbf7cc009a",
4  "code": "5606fbd3-ec93-4f2b-be20-d57af20b7795",
5  "age_over_18": "true",
6  "amr": ["60"],
7  "birth_date": "1968-01-01",
8  "iss": "https:\/\/dc-api.app.dev.identity-dev.idemia.io",
9  "age_in_years": "58",
10  "resident_postal_code": "99999-5012",
11  "sid": "183eeaea-5cc7-4bf5-9d7e-ef7dcc2d6547",
12  "acr": "mid",
13  "issue_date": "2022-02-01",
14  "issuing_country": "USA",
15  "auth_time": 1780480248,
16  "resident_state": "ST",
17  "exp": 1780483849,
18  "resident_country": "USA",
19  "iat": 1780480249,
20  "resident_city": "ANYTOWN",
21  "document_type": "DRIVING_LICENSE",
22  "document_number": "201714014",
23  "expiry_date": "2030-01-01",
24  "sex": "M",
25  "given_name": "JOE MIDDLE",
26  "portrait": "\/9j4AAQSkZJRgABAgAAAQABAKT3(shorted)",
27  "nonce": "ae74a40d-c476-4de6-ad63-16a7bb802aeb",
28  "mid_tenant": "idemia_dcdev_eucentral14iqhpnuln",
29  "aud": "FFFFFFFF-7273-6D74-0004-000000000001",
30  "c_hash": "oGc9oKLN5-UsfxUqJqR9-Q",
31  "issuing_authority": "idemia_dcdev_eucentral14iqhpnuln",
32  "resident_address": "012 MAIN STREET",
33  "age_over_25": "true",
34  "correlationID": "2dbf679f-410d-4c99-b606-d78f8c0e11a8",
35  "grant": "authorization_code",
36  "family_name": "MACSAMPLE",
37  "age_over_21": "true"
38}

Online Authentication Error Handling 

The Relying Party must be prepared to handle unsuccessful authentication outcomes.

Possible outcomes include:

  • user rejection,
  • session timeout,
  • invalid or expired request,
  • validation failure,
  • technical error.

If authentication does not complete successfully, the Relying Party should display an appropriate message to the user and must not grant access.

Example of a timeout response returned to the Relying Party:

HTTP
1/callback?
2error=interaction_required&
3error_description=Timeout+awaiting+user+authentication&
4state=O71G9lI5k4L2dtBMWsJ_bvnx64nWjQINHGrNNtnl9V0

The Relying Party should not treat the authorization code itself as proof of authentication. Authentication is complete only after the authorization code has been exchanged and the returned ID Token has been received and validated.

The attributes shared by the user are available as claims in the ID Token, based on the scopes and claims requested by the Relying Party and approved by the user.

Online Authentication flow overview 

In Online Authentication, the user starts in the browser and completes authentication in the iD Wallet application.

At a high level, the flow works as follows:

  1. The user selects Sign in with Digital Credential on the Relying Party page.
  2. The user action triggers an authentication request on the Relying Party side.
  3. The Relying Party forwards the request to the Digital Credential Platform.
  4. The Digital Credential Platform creates an authentication session.
  5. The browser displays a QR code or deeplink to pair the session with the iD Wallet application.
  6. The user scans the QR code or opens the deeplink using the iD Wallet application.
  7. The user reviews the request card in the iD Wallet application.
  8. The user approves, rejects, or does not complete the request before it expires.
  9. If the user approves and authentication succeeds, the Digital Credential Platform redirects the browser back to the Relying Party with an OpenID Connect authorization code.
  10. The Relying Party exchanges the authorization code at the token endpoint.
  11. The Relying Party validates the ID Token and uses the approved claims to grant or deny access.

From the Relying Party point of view, this remains a standard OpenID Connect Authorization Code Flow: initiate an authorization request, receive an authorization code, exchange the code for tokens, and validate the returned ID Token.

Online Authentication detailed flow 

Detailed OIDC Code Flow
The following figure illustrates a sample OpenID Connect Authorization Code Flow in details