Integration Guide for OpenID Connect Application

Overview

Identity Proofing Application (IPA) is IN GROUPE’s unified identity verification application designed to deliver trusted identities through the OpenID Connect (OIDC) standard. It consolidates multiple identity sources into a single, seamless interface for Relying Parties (RP) to integrate, providing a consistent user experience and standard-based interoperability.

Key goals

Provide a single integration point for RPs to obtain a trusted identity of their End Users.
Support multiple identity sources (physical and digital) without requiring separate implementations.
Ensure compliance with OpenID Connect standard for security and interoperability.
Propose best in class User Experience to get through the identity verification process.

Supported Identity Sources

Physical ID
- Uses Physical Identity Document remote verification and User verification including liveness and biometric checks.
Digital IDs
- IN GROUPE Identity Server – mobile app-based verified digital identity.

Creation of OpenID Connect Application

The configurator guides you through the necessary steps to adapt the application to your requirements. Once the application is created, the necessary identifiers and secrets are generated and made available through the Experience portal.

Go to Access → OpenID Connect App and click “Create new app”.

Configuration

Choose application name.
Select environment. If none is available, contact your IN Groupe Partner Manager to create one.
Select country and document types.
Choose face capture option:
- none – no face verification
- Passive Video Liveness – recommended for seamless UX
- Active Liveness – recommended for high security applications only as it may reduce the End User's success rate
Select a minimum Level of Assurance (LoA).
Set at least one Redirect URL. Example of redirect url:
```
Language not specified
1  https://client.example.org/cb
2
```
NOTE: At least one redirect URL must be provided. This URL is where the response is sent once the Identity proofing process is complete.
Customize look & feel of your application
Confirm on summary screen. The "Digital ID verification" capability has been automatically added to your configuration.
After the application is created, you can access the OAuth information through the Endpoint menu of the application configuration.

Item	Example
Client ID	`63ajnhdarkpg445up9bcj7v522`
Client Secret	`examplesecretvalue`
OpenID Identity Provider URL	`https://idhub.idplatform.idemia.com`

Experience your Open ID Application Configuration

You can test the “Physical ID verification” user journey of the application you have just configured by clicking on “Test app”.

Integrate OpenID Connect Application in your business process flow

Step 0: Learn about our OpenID Identity Provider service

OpenID Connect Discovery Document endpoint - https://idhub.idplatform.idemia.com/.well-known/openid-configuration

This is the OpenID Connect metadata endpoint. It provides all necessary configuration data to interact with IN Groupe’s OpenId Connect App, such as:

Authorization endpoint URL
Token endpoint URL
Supported response types
Supported scopes
Public keys (jwks_uri)
Token signing algorithms
Issuer identifier
And other relevant capabilities

Step 1: Start Business Process

The End User requests a service from the Relying Party (RP) that requires Identity Verification.

Step 2: Build the authorization request

RP creates an OIDC authorize request that corresponds to the configured IN Groupe’s OpenID Connect Application.
RP redirects the End User to IN Groupe’s OpenID Connect Application with its client_id , scopes, and redirect_uri.

Example of initiation request, call to /authorize endpoint:

Shell
1         curl -X GET 'https://idhub.idplatform.idemia.com/oauth2/authorize?response_type=code\
2         &client_id=63ajnhdarkpg445up9bcj7v522\
3         &scope=openid%20name%20portrait%20address%20birthdate%20email\
4         &state=5NmMiBA2oFcyjmuG5jAgEDQZ5o4H4ms0TZKMumleuHw%3D\
5         &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb\
6         &nonce=GvQoaG3yTlTsCEWPWK-6WHaRbK2dNB03HMGqyEI7gIY'
7

Variable	Type	Mandatory/Optional	Description	Example
`response_type`	`string`	Mandatory	Authorization Code Flow. Expected value is `code`.
`client_id`	`string`	Mandatory	OAuth 2.0 Client Identifier valid at the Authorization Server. This value can be retrieved from the Endpoint menu of the application configuration.	`63ajnhdarkpg445up9bcj7v522`
`scope`	`string`	Mandatory	OpenID Connect requests MUST contain the `openid` scope value, along with other scopes that are required by the RP. See section Supported scopes.	`openid portrait age_over_21 email`
`state`	`string`	Mandatory	It is a random value (string) that your app generates and sends with the authorization request. When the Authorization Server (OpenID Provider) sends the user back to your app (the callback/redirect), it includes the same `state` value in the response.	`5NmMiBA2oFcyjmuG5jAgEDQZ5o4H4ms0TZKMumleuHw=`
`redirect_uri`	`string`	Mandatory	Redirection URI to which the response will be sent. This URI MUST exactly match one of the Redirection URI values for the Client pre-registered at the OpenID Provider. The Redirection URI SHOULD use the `https` scheme	`https://client.example.org/cb`
`nonce`	`string`	Mandatory	It is a high entropy random string (a “number used once”) that the client (your app) sends in its authentication request to the OpenID Provider. The OpenID Provider includes exactly the same `nonce` value inside the ID Token (in the `nonce` claim) when it returns it to the client. The client must then verify that the `nonce` in the token matches the one it originally sent.	`GvQoaG3yTlTsCEWPWK-6WHaRbK2dNB03HMGqyEI7gIY`

Step 3: Prompt authentication and consents

User is requested to agree to the Terms and Conditions of the Service.

Step 4: Identity Verification Process

User’s Identity is verified using the Identity factor they selected (Mobile Id or Physical Identity document). If successful, claims are extracted and added to the Identity Token.

Step 5: Redirect user and provide the authorization code

After user submitted their credentials they are redirected to redirect_uri with one-time authorization code that will later be used to exchange it for an ID Token.

Callback parameters returned after a call to ‘redirect_uri’:

Variable	Example	Description
`code`	`Rvjkp9P17OU20Ih7Q2pUiDG9PK4AqG-PNLyeQnDd_kJS-3ZnMQGG`	`response_type` value. Authorization Code is returned after a call to `redirect_uri`.
`state`	`5NmMiBA2oFcyjmuG5jAgEDQZ5o4H4ms0TZKMumleuHw`	A context token used to verify that the callback matches the initiating request.

Step 6: Save the code

Relying Party application keeps one-time authorization code in memory and prepares to call /token endpoint.

Step 7 & 8: Retrieve Id Token

Example of a request to /oauth2/token endpoint to retrieve the id_token & scope:

Shell
1         curl -X POST 'https://idhub.idplatform.idemia.com/oauth2/token' \
2         --header 'Content-Type: application/x-www-form-urlencoded' \
3         --data-urlencode 'grant_type=authorization_code' \
4         --data-urlencode 'code=SplxlOBeZQQYbYS6WxSbIA' \
5         --data-urlencode 'redirect_uri=https://client.example.org/cb' \
6         --data-urlencode 'client_id=cfc26298-f31c-49a3-bbec-2b154838191f' \
7         --data-urlencode 'client_secret=examplesecretvalue'
8

Variable	Type	Mandatory/Conditional	Description	Example
`grant_type`	string (enum)	Mandatory	Must be `authorization_code` for exchanging the auth code at the Token Endpoint.	`authorization_code`
`code`	string	Mandatory	The authorization code previously returned from the Authorization Endpoint.	`Rvjkp9P17OU20Ih7Q2pUiDG9PK4AqG-PNLyeQnDd_kJS-3ZnMQGG`
`redirect_uri`	string	Conditional	Required if it was included in the original Authorization Request. It must exactly match one of the redirect_uri defined in the App configuration on Experience Portal.	`client.example.org/cb`
`client_id`	string	Conditional	Identifies the Client. Obtained through the Endpoint menu of the application configuration on Experience Portal.	`63ajnhdarkpg445up9bcj7v522`
`client_secret`	string	Conditional	Used when the registered client authentication method is `client_secret_post`. Obtained through the Endpoint menu of the application configuration on Experience Portal.	`examplesecretvalue`

Response example:

JSON
1         {
2         "access_token": "exampleaccess_token",
3         "token_type": "Bearer",
4         "expires_in": 3600,
5         "scope": "address birthdate openid name email",
6         "id_token": "exampleid_token"
7         }
8

Variable	Type	Mandatory/Optional	Description	Example
`access_token`	string	Mandatory	OAuth 2.0 access token issued by the Authorization Server (idHub); Returned in all successful token responses.	`exmpleaccess_token`
`token_type`	string	Mandatory	Token type per OAuth 2.0; typically `Bearer`. Case-insensitive.	`Bearer`
`expires_in`	integer	Recommended	Lifetime (in seconds) of the access token.	`3600`
`scope`	string	Optional	Space-separated scopes granted to the access token. For OIDC, `openid` indicates an OpenID request; other values map to user claims or provider-specific scopes (e.g., `address`, `email`; custom scopes like `ial1` may appear). See section Supported scopes.	`address birthdate openid name email`
`id_token`	string (JWT)	Mandatory	A signed JWT carrying identity claims about the End-User (e.g., `iss`, `sub`, `aud`, `exp`, `iat`, and possibly `nonce`). Returned alongside the access token in a successful OIDC token response. Must be validated as per OIDC standard (see below).	`exampleid_token`

Step 9: Validate token

Relying Party app must validate the ID Token per OIDC Core:

Verify the JWS signature using the OIDC Provider’s jwks_uri.
Check iss equals the issuer from discovery.
Check aud includes your client_id (and azp if multiple audiences).
Check time-based claims: exp, iat (and often auth_time if you require recent sign-in).
Check nonce equals what you sent.
(If present) verify at_hash (ties the access token to the ID Token). All of this is explained in details in the OpenId connect core specifications: IDToken Validation

Step 10 & 11: Continue with business process flow

Continue your business flow as needed.

Error Management

The following errors can be expected during the process. Errors corresponding to OAuth 2.0 and OIDC standards.

Authorization / Authentication Endpoint Error Codes

Error	HTTP Status	Description
	`200 OK`	Process is successful
`server_error`	`500 Internal Server Error`	The authorization server encountered an unexpected internal error preventing it from fulfilling the request.
`unmet_authentication_requirements`	`302 Found`	The authorization server cannot meet the authentication requirements requested by the client.
`login_required`	`302 Found`	The End-User is not logged in or their session has expired; a login is required to continue.
`interaction_required`	`302 Found`	The request cannot be completed without additional End-User interaction (e.g., login or consent).
`invalid_request`	`302 Found`	The request is missing a required parameter, includes an unsupported parameter or value, repeats a parameter, or is otherwise malformed.
`unauthorized_client`	`401 Unauthorized`	The client is not authorized to request an authorization code using this method.
`access_denied`	`302 Found`	The resource owner or authorization server denied the request.
`unsupported_response_type`	`302 Found`	The authorization server does not support the requested `response_type`.
`invalid_scope`	`302 Found`	The requested scope is invalid, unknown, malformed, or exceeds what the client is permitted to request.
`temporarily_unavailable`	`503 Service Unavailable`	The authorization server is temporarily unable to handle the request due to overload or maintenance.
`account_selection_required`	`302 Found`	The End-User has multiple accounts and must select one before the request can proceed.
`consent_required`	`302 Found`	The End-User has not yet given consent for the requested scopes or claims.
`invalid_request_uri`	`400 Bad Request`	The `request_uri` parameter is invalid, expired, or not supported by the authorization server.
`invalid_request_object`	`400 Bad Request`	The `request` object (JWT) is invalid, malformed, expired, or has an invalid signature.
`request_not_supported`	`400 Bad Request`	The authorization server does not support the use of the request parameter to pass a `request` object.
`request_uri_not_supported`	`400 Bad Request`	The authorization server does not support the use of the `request_uri` parameter to reference a request object.
`registration_not_supported`	`400 Bad Request`	The authorization server does not support the `registration` parameter in the authentication request.

Error response:

Language not specified
1     HTTP/1.1 302 Found
2     Location: https://client.example.org/cb?\
3     error=invalid_request&\
4     error_description=Unsupported%20response_type%20value&\
5     state=af0ifjsldkj
6

Value	Mandatory/Optional	Dsscription	Example
`error`	Mandatory	Error code	`invalid_request`
`error_description`	Optional	Human readable description of an error	`Unsupported response_type value`
`error_uri`	Optional	URI of a web page that includes additional information about the error.
`state`	Conditional	OAuth 2.0 state value. Mandatory if the Authorization Request included the `state` parameter. Set to the value received from the Client.	`af0ifjsldkj`

Token Endpoint Error Codes

OpenID Connect does not introduce any new error codes for the Token Endpoint - it simply inherits OAuth 2.0 set, enforces JSON response format, and mandates HTTP 400 (except for invalid_client, which remains 401).

Error Code	HTTP Status	Description
`invalid_request`	`400 Bad Request`	The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats a parameter, or is otherwise malformed.
`invalid_client`	`401 Unauthorized (with WWW-Authenticate header)`	Client authentication failed (e.g., unknown client, invalid credentials, or mismatched authentication method). The authorization server must return the HTTP 401 status with the `WWW-Authenticate` header.
`invalid_grant`	`400 Bad Request`	The provided authorization grant is invalid, expired, revoked, does not match the redirect URI, or was issued to another client.
`unauthorized_client`	`400 Bad Request`	The authenticated client is not authorized to use this grant type.
`unsupported_grant_type`	`400 Bad Request`	The authorization grant type is not supported by the authorization server.
`invalid_scope`	`400 Bad Request`	The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

Error response:

Language not specified
1     HTTP/1.1 400 Bad Request
2      Content-Type: application/json
3      Cache-Control: no-store
4      {
5        "error": "invalid_request"
6      }
7

Supported scopes

The Relying Party can request claims by composing different scopes in their authorize request.

Multiple scope values MAY be used by creating a space-delimited, case-sensitive list of ASCII scope values. The openid scope is mandatory.

Language not specified
1     scope=openid email name birthdate portrait
2

The following scopes are supported by the IN Groupe’s OIDC App.

Scope Name:

scope value : name

Claim Name	Mandatory/Optional	Type	Desciption
`name`	Mandatory	string	End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.
`family_name`	Mandatory	string	Last name or surname of the user. Could be NONE in case of mononym
`given_name`	Mandatory	string	First name(s) or given name(s) of the user. Could be NONE in case of mononym
`middle_name`	Optional	string	Middle name(s) of the End-User. Append all names except [0] with a space between each element
`name_suffix`	Optional	string	User’s name suffix if any
`name_prefix`	Optional	string	User’s name prefix if any

Scope Birthdate:

scope value : birthdate

Birthdate of the end-user.

Claim Name	Mandatory/Optional	Type	Desciption
`birthdate`	Optional	string	End-User's birthday, represented in `YYYY-MM-DD` format (standard ISO 8601-1) The year MAY be `0000`, indicating that it is omitted. To represent only the year, `YYYY` format is allowed. Note that depending on the underlying platform's date related function, providing just year can result in varying month and day, so when integrating this needs to be taken into account to correctly process the dates.

Scope age_over_XX:

scope value : age_over_XX

This is a scope defined within the IN Groupe’s OIDC App context to provide information related to user’s age in regard to an age limit.

There are multiple age over scopes with one claim each.

XX values may be : 13, 15, 16, 18, 21, 25.

Claim Name	Mandatory/Optional	Type	Value	Desciption
`age_over_xx`	Optional	string	true/false	true / false if user’s age is over XX. No claim returned if unknown or enable to determine.

Scope age_in_years:

scope value : age_in_years

This is a scope defined within theIdemia’s OIDC App context to provide information related to user’s age without disclosing their date of birth.

Claim Name	Mandatory/ Optional	Type	Value example	Description
`age_in_years`	Optional	string	45	Current age in years of the End user.

Scope Address:

scope value : address

This is a scope defined within the IN Groupe’s OIDC App context to provided information related to user’s address.

It is based on the OpenId Connect Standard, Address claims.

Claim Name	Mandatory/Optional	Type	Description
`street_address`	Optional	string	Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").
`postal_code`	Optional	string	Postal code (ZIP code).
`locality`	Optional	string	City or locality component.
`region`	Optional	string	State, province, prefecture, or region component
`country`	Optional	string	Country

Scope Portrait:

scope value : portrait

This is a scope defined within the IN Groupe’s OIDC App context to provide the user’s facial portrait image.

Claim Name	Mandatory/Optional	Type	Description
`portrait`	Optional	string	Base 64 encoded image of user’s facial portrait (PNG or JPG)

Scope Email:

scope value : email

This is a scope defined within the IN Groupe’s OIDC App context to provide information related to user’s email.

Note: Adding this scope to the authorize request triggers an email verification sequence between the End User and IN Groupe’s OIDC App.

Claim Name	Mandatory/Optional	Type	Description
`email`	Optional	string	End-User’s email address
`email_verified`	Optional	boolean	Present only if email parameter is provided. `True` if the End-User's e-mail address has been verified; otherwise `False`.

Scope Document:

scope value: document

This is a scope defined within the IN Groupe's OIDC App context to provide information related to user's primary physical document used as source of identity.

Claim Name	Mandatory/Optional	Type	Description
`document_number`	Optional	string	Documents unique reference number
`document_type`	Mandatory	string	Document type (`PASSPORT`, `DRIVING_LICENSE`, `RESIDENT_CARD`, `IDENTITY_CARD`)
`document_issuing_country`	Mandatory	string	Issuing country as ISO 2 letter country code
`document_issuing_state`	Optional	string	Issuing state if any
`document_issuing_authority`	Optional	string	Organization issuing the document
`document_issue_date`	Optional	string	Date of issue. `YYYY-MM-DD` format. ISO 8601-1
`document_expiry_date`	Optional	string	Date of expiry. `YYYY-MM-DD` format. ISO 8601-1