Relying Party Integration Guide

Introduction

This guide describes how a Relying Party integrates with the IDEMIA Digital Credential Platform to authenticate users, request identity attributes, or obtain user approval for transaction-related scenarios.

The Digital Credential Platform acts as the OpenID Connect Identity Provider (IDP).
The Relying Party acts as the OpenID Connect Client (Client).

The platform supports two main OpenID Connect-based integration patterns:

Online Authentication
A browser-based authentication flow based on the OpenID Connect Authorization Code Flow.
This use case supports login, eligibility checks, and attribute sharing. In this guide, this flow is referred to as Online Authentication.
CIBA Authentication
A backchannel authentication flow based on OpenID Connect Client-Initiated Backchannel Authentication (CIBA).
This flow is used when the request is initiated by the Relying Party backend, and the user confirms the request independently in the iD Wallet application.

Both flows rely on the iD Wallet application as the trusted user interaction channel.

NOTE
With the Identity on the Edge approach, the Digital Credential Platform does not store personal data on the server side, even temporarily. Identity attributes are obtained from the user’s Digital Credential and returned only as part of the configured OpenID Connect flow.

Choosing the right integration approach

Before starting the integration, a Relying Party integrator should be able to answer the following questions:

Which authentication flow should be used for the business use case?
Is the user expected to start from a browser-based page or from a backend-triggered process?
Does the Relying Party need verified identity attributes, transaction approval, or both?
Which OpenID Connect endpoints are required?
How is the Relying Party client registered?
Which scopes and claims are needed?
How should successful and unsuccessful outcomes be handled?

Based on the answers to these questions, the Relying Party should choose the appropriate authentication flow.

When should I use the Online Authentication flow?

Use Online Authentication when:

the user starts from a browser-based Relying Party page,
the user can scan a QR code or use a deeplink,
the user can be redirected through a browser-based flow,
the Relying Party needs an Authorization Code Flow result,
the use case involves login, eligibility proof (for example age-based (16+, 18+, 21+)), or identity attribute sharing.

The following figure illustrates a sample authorization code flow

When should I use the CIBA flow?

Use CIBA Authentication when:

the request is initiated by the Relying Party backend,
the user does not need to remain in the same browser session,
the user confirms the request independently in the iD Wallet application,
the use case involves transaction confirmation, second factor authentication, assisted authentication, or shared-device scenarios,
the Relying Party needs to continue the process after receiving the user’s decision asynchronously.

The following figure illustrates a sample Client Initiated Backchannel Authentication flow

Common integration guidance

OpenID Connect endpoints

The Digital Credential Platform exposes the following OpenID Connect endpoints to a Relying Party:

OpenID Connect Discovery
/.well-known/openid-configuration Used to retrieve OpenID Connect configuration and metadata.
OpenID Connect Authorization Endpoint
/authorize Used to initiate browser-based Online Authentication through the Authorization Code Flow.
OpenID Connect CIBA Endpoint
/bc-authorize Used to initiate backchannel authentication through the CIBA flow.
OpenID Connect Token Endpoint
/token Used to retrieve tokens after successful authentication or transaction confirmation.

IMPORTANT
The Digital Credential Platform does not support the OpenID Connect endpoints:

/end_session

/userinfo

The /end_session endpoint, typically available in OpenID Connect Identity Providers, is not available in the Digital Credential Platform because SSO session management is not supported. This is aligned with the Identity on the Edge approach, where personal data and identity claims are not stored on the server side.

The /userinfo endpoint is not supported because, with the Identity on the Edge approach, personal data and identity claims are not stored on the server side.

Relying Parties should not rely on /userinfo to retrieve user attributes. Approved identity attributes are returned as part of the configured OpenID Connect token response, according to the selected flow, requested scopes, and issuer settings.

Scope and claims handling

The Relying Party requests authentication and user attributes through OpenID Connect scopes.

The openid scope is required for OpenID Connect authentication.

Additional scopes may be used depending on the business use-case required.

Scopes are used as part of the OpenID Connect flow to request access to selected groups of attributes. The supported scopes expose the corresponding PhotoID attributes as OIDC claims

Scopes may be customized, and additional scopes can be defined to address specific business or integration requirements.

Default Claims

The attributes shared with the relying party, presented in table below, are based on the Photo ID data elements defined by ISO/IEC TS 23220-4.

OIDC Claim Name	Attribute shared within the scope
`full_name`	End-user's full name in displayable form, including all name parts such as given name, family name, and suffix, ordered according to the user's locale or document format.
`family_name`	Last name or surname of the user.
`given_name`	First name(s) or given name(s) of the user.
`birth_date`	Date of birth of the user.
`name_suffix`	User’s name suffix, if any.
`resident_address`	Resident address of the user.
`resident_postal_code`	Postal code / ZIP code of the resident address.
`resident_city`	City or locality component of the resident address.
`resident_state`	State, province, prefecture, or region component of the resident address.
`resident_country`	Country component of the resident address.
`portrait`	Base64-encoded image of the user’s facial portrait.
`document_number`	Document number.
`document_type`	Type of document, such as driver’s license or state ID.
`issuing_country`	Country that issued the document.
`issuing_authority`	Organization or authority that issued the document.
`issuing_jurisdiction`	Jurisdiction that issued the document.
`issue_date`	Date when the document was issued.
`expiry_date`	Date when the document expires.
`sex`	Gender / sex of the user.
`age_over_18`	Boolean claim indicating whether the user is over 18 years old.
`age_over_21`	Boolean claim indicating whether the user is over 21 years old.
`age_over_25`	Boolean claim indicating whether the user is over 25 years old.
`age_in_years`	User’s age in years.
`dg1`	ICAO 9303 Data Group 1.
`dg2`	ICAO 9303 Data Group 2.
`dg14`	ICAO 9303 Data Group 14.
`dg15`	ICAO 9303 Data Group 15.
`sod`	ICAO 9303 Security Object Document.

Legacy Claims

The following claims are supported for backward compatibility purposes.

OIDC Claim Name	Attribute shared within the scope
`lastName`	Last name of the credential subject.
`firstName`	First name of the credential subject.
`gender`	Gender of the credential subject.
`address`	Address of the credential subject.
`documentId`	Document identifier associated with the credential subject.
`frontPortrait`	Front portrait image of the credential subject.
`is18`	Age assertion indicating that the credential subject is 18 years old or older.

Default scopes

The table below presents the predefined scopes currently available for relying party integrations.

An extension to OpenID Connect discovery endpoint allow

Scope	Claims
`id_basic`	lastName1 firstName1 gender address1 documentId
`id_names`	full_name family_name given_name name_suffix
`id_address`	resident_address resident_postal_code resident_city resident_state resident_country
`id_portrait`	portrait
`id_document`	document_number document_type issuing_country issuing_authority issuing_jurisdiction issue_date expiry_date
`id_sex`	sex
`id_birth_date`	birth_date
`age_over_18`	age_over_18
`age_over_21`	age_over_21
`age_over_25`	age_over_25
`org.iso.23220.1`	family_name given_name name_suffix resident_address resident_postal_code resident_city resident_state resident_country portrait document_number document_type issuing_country issuing_authority issuing_jurisdiction issue_date expiry_date sex age_over_18 age_over_21 age_over_25 birth_date age_in_years
`org.iso.23220.datagroups.1`	dg1 dg2 dg14 dg15 sod

Authentication Context Reference

While scopes define what attributes are requested, the Authentication Context Reference - ACR defines how the authentication should be performed.

ACR Values allows to a relying party to drive:

The User Authentication factors required for the user to use and thus the Authentication Level of Assurance.
If multiple credentials are used, which type of credential can be used.

At runtime, ACR is requested using the acr_values parameter. After successful authentication, the achieved authentication context is returned as the acr claim in the ID Token.

ACR is required for both Online Authentication and CIBA flows.

During client registration, the Relying Party may be configured with optional default_acr_values. The default_acr_values parameter defines the authentication context to be used when the Relying Party does not explicitly provide acr_values in a particular authentication request.

ACR can be customized through for specific customer needs through your partner manager.

Default ACR

ACR	Description
mid	Base authentication requiring Device authentication
mid_pin loa-2	2 factor authentication: Device Authentication PIN
mid_face loa-3	2 factor authentication: Device Authentication Biometrics against selected credential reference portrait
mid_pin_face mid_face_pin loa-4	3 factor authentication: Device Authentication PIN Biometrics against selected credential reference portrait

Attributes approved for sharing are returned as part of the configured token response.

If identity attributes are returned in an ID Token, the Relying Party must validate the token before using the claims.

If identity information is obtained through an additional endpoint or response, the Relying Party must validate the access token and the returned data according to the configured security model.

Client registration

Client registration defines how the Relying Party is allowed to interact with the Digital Credential Platform through OpenID Connect — which flows it can use, how it authenticates itself to the token endpoint, and which scopes and ACR values it may request.

Client registration is not self-service. To gain access, contact your IDEMIA partner manager, who will coordinate registration on your behalf.

Once registered, the Relying Party receives a client_id and, depending on the chosen authentication method, either a client secret or a public key reference.

Requesting client registration

To request registration, reach out to your IDEMIA partner manager. Prepare the following information in advance so that registration can be completed without back-and-forth.

The required parameters depend on the flow and client authentication method you intend to use. Use the flow-specific checklists below — Online Authentication or CIBA — to identify exactly what you need to provide.

Common parameters required for all clients:

Client Name — the name displayed to the end-user in the iD Wallet application during the authentication request. Locale-specific variants can be provided if needed.
Scopes — the set of user attributes the client is allowed to request. See Scope and claims handling for available values.
Redirect URIs define the list of callback URI values allowed for the client.
Authentication method for the token endpoint — how the client authenticates when calling /token. Available options:
Default ACR values — define the default authentication context used when the Relying Party does not explicitly provide acr_values in a particular authentication request. For details see ACR subchapter,
Grant types — the flows the client is allowed to use:
- authorization_code — for Online Authentication.
- urn:openid:params:grant-type:ciba — for CIBA Authentication.
Logo URI — a link to your logo as a square SVG file. Displayed on the request card in the iD Wallet application.

What you will receive after registration:

client_id — the identifier used in all authentication requests.
Client credentials or key reference — according to the configured authentication method.
Platform endpoint base URL — the host to use for all OpenID Connect requests in your environment.

CIBA-specific registration

If CIBA is used, additionally provide:

backchannel_token_delivery_mode — one of poll, ping, or push.
backchannel_client_notification_endpoint — required for ping and push modes. Must be a valid HTTPS URI capable of receiving POST callbacks from the DC Platform.

For poll mode, the Relying Party must respect the interval value returned in the CIBA response and must stop polling once the request reaches a final state or expires.

Setting up a test credential

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

Step 1 — Download the iD Wallet App

The test user can download the iD Wallet application and register a credential using a supported identity document.

Step 2 — Register a credential

This application requires registering through the Experience Portal. Sign up and request access. A partner manager will reach out to set you up and issue a QR code that will automatically set up the iD Wallet application.

Two options are available for registering a credential:

Option 1 — Using your own personal identity document

You will be able to use your own personal government IDs which will also allow you to experience the IDEMIA ID&V process through the mobile application.

Option 2 — Issue a test credential using the Direct Issuance Portal

Alternatively, the test user can receive a test Digital Credential through the Direct Issuance Portal.

For details, see: Direct Issuance Integration Guide

Summary

Online Authentication and CIBA both allow a Relying Party to use Digital Credentials for secure user authentication, but they are designed for different interaction models.

Online Authentication is best suited for browser-based journeys, where the user starts from the Relying Party page and returns with an authorization code. In this model, the Relying Party does not need to know the user in advance, as the authentication process is initiated by the user.

CIBA Authentication is best suited for asynchronous scenarios where the request is initiated by the Relying Party backend and the user confirms it separately in the iD Wallet application. In this model, the Relying Party must be able to identify the user upfront (for example using user_hint) in order to initiate the authentication request.

A Relying Party may implement one or both flows depending on the required user journey, channel, and business use case.

For step-by-step integration instructions, continue to the relevant flow guide:

Online Authentication — browser-based Authorization Code Flow
CIBA Authentication — backchannel flow for transaction confirmation and second-factor scenarios