Relying Party Integration Guide

Introduction

This guide describes the OpenID Connect capabilities of the IDEMIA Mobile ID platform used by a Relying Party, also known as the "Client/OpenID Connect Client." It covers the platform's ability to authenticate users or request identity attributes from a Mobile ID-credentialed user. The IDEMIA Mobile ID platform addresses two principal use cases supported by OpenID Connect:

Access to Resources:
This use case supports login and attribute sharing using the OpenID Connect authorization-code flow. It leverages HTTP redirects and simple REST requests to facilitate authentication and attribute sharing.
Transaction Confirmation:
Formerly known as the IDEMIA Consent API, this feature utilizes the OpenID Client-Initiated Backend Authentication (CIBA) protocol to confirm user transactions.

Workflow Overview

OpenID Connect Authorization-Code Flow

The majority of this guide demonstrates the various functional components associated with a typical end-user/Relying Party interaction—an end-user initiating some action with a Relying Party who is being asked to authenticate, and then optionally sharing identity attributes with the Relying Party in response to a consent request for these attributes to be shared.

This workflow, dedicated to resource access, ensures—through user agent redirection (HTTP 302)—that the authenticated end-user is present in front of the user agent that accesses the Relying Party.

The following figure illustrates a sample authorization code flow:

Lucidchart Authorization Code Flow Diagram

Open ID Connect Client Initiated Backend Authentication

As indicated by its name, the CIBA (Client Initiated Backchannel Authentication) workflow starts from the Relying Party’s backend server, even though some user interaction may occur beforehand. The goal of this protocol is to authenticate the end-user and obtain consent in the relevant context (binding message), which can be securely exchanged server-to-server. This approach is ideal for addressing confirmation transaction use cases, such as payment approvals or Helpdesk user authentication.

The following figure illustrates a sample Client Initiated Backchannel Authentication flow:

Lucidchart CIBA Flow Diagram

MOBILE ID OpenID Connect Endpoint

Mobile ID exposes 4 different endpoints to a Relying Party:

OpenID Connect Discovery: Used to get Mobile ID OpenID Connect details.
OpenID Connect Dynamic Registration: To register a client.
OpenID Connect /authorize: For the authorization code flow, or /bc-authorize for CIBA (Client Initiated Backchannel Authentication).
OpenID Connect /token: To retrieve the authentication result.

Note: By design, with an "Identity on the Edge" approach, Mobile ID does not store any personal data, even temporarily, on the server side.

Additionally:

/userinfo endpoint, typically available in OpenID Connect IDPs, is not available in Mobile ID. Instead, Mobile ID provides the requested claims directly in the IDToken.
/end_session endpoint, typically available in OpenID Connect IDPs, is not available in Mobile ID as SSO is not supported due to the lack of claims on the server side.

OpenID Connect Discovery

OpenID Connect provides an endpoint that relying parties can use to discover various service APIs. This enables relying parties to dynamically configure their client software by loading these URIs without the need for hard-coded values. The discovery endpoint for IDEMIA Mobile ID products is located at:

https://idp.samplehostname.com/.well-known/openid-configuration.

Mobile ID /.well-known/openid-configuration

Request

Language not specified
11. GET https://idp.samplehostname.com/.well-known/openid-configuration

Response

JSON
11. HTTP/1.1 200 OK
22. ContentType: application/json

Body

JSON
11. {
22. "request_parameter_supported": true,
33. "claims_parameter_supported": false,
44. "issuer": "https://idp.samplehostname.com",
55. "id_token_encryption_enc_values_supported": [
66. "A128CBC+HS256",
77. "A256CBC+HS512",
88. "A128GCM",
99. "A256GCM"
1010. ],
1111. "authorization_endpoint": "https://idp.samplehostname.com/oxauth/restv1/authorize",
1212. "service_documentation": "https://developer.idemia.com",
1313. "claims_supported": [
1414. "street_address",
1515. "country",
1616. "zoneinfo",
1717. "role",
1818. "birthdate",
1919. "gender",
2020. "user_name",
2121. "formatted",
2222. "phone_mobile_number",
2323. "preferred_username",
2424. "inum",
2525. "locale",
2626. "personIdentityCodeSample",
2727. "updated_at",
2828. "surname",
2929. "post_office_box",
3030. "nickname",
3131. "email",
3232. "midUid",
3333. "preferred_language",
3434. "personalIdentityCode",
3535. "rp_PCR",
3636. "website",
3737. "email_verified",
3838. "profile",
3939. "locality",
4040. "phone_number_verified",
4141. "room_number",
4242. "dateOfBirth",
4343. "given_name",
4444. "middle_name",
4545. "picture",
4646. "names",
4747. "name",
4848. "phone_number",
4949. "postal_code",
5050. "region",
5151. "family_name"
5252. ],
5353. "scope_to_claims_mapping": [
5454. {
5555. "email": [
5656. "email_verified",
5757. "email"
5858. ]
5959. },
6060. {
6161. "phone": [
6262. "phone_number_verified",
6363. "phone_number"
6464. ]
6565. },
6666. {
6767. "user_name": [
6868. "user_name"
6969. ]
7070. },
7171. {
7272. "pcr": [
7373. "rp_PCR"
7474. ]
7575. },
7676. {
7777. "mid_uid": [
7878. "midUid"
7979. ]
8080. },
8181. {
8282. "address": [
8383. "formatted",
8484. "postal_code",
8585. "street_address",
8686. "locality",
8787. "country",
8888. "room_number",
8989. "region",
9090. "post_office_box"
9191. ]
9292. },
9393. {
9494. "clientinfo": [
9595. "name",
9696. "inum"
9797. ]
9898. },
9999. {
100100. "mobile_phone": [
101101. "phone_mobile_number"
102102. ]
103103. },
104104. {
105105. "permission": [
106106. "role"
107107. ]
108108. },
109109. {
110110. "profile": [
111111. "name",
112112. "family_name",
113113. "given_name",
114114. "middle_name",
115115. "nickname",
116116. "preferred_username",
117117. "profile",
118118. "picture",
119119. "website",
120120. "gender",
121121. "birthdate",
122122. "zoneinfo",
123123. "locale",
124124. "updated_at",
125125. "preferred_language"
126126. ]
127127. }
128128. ],
129129. "token_endpoint_auth_methods_supported": [
130130. "client_secret_basic",
131131. "client_secret_post",
132132. "client_secret_jwt",
133133. "private_key_jwt",
134134. "tls_client_auth",
135135. "self_signed_tls_client_auth"
136136. ],
137137. "tls_client_certificate_bound_access_tokens": true,
138138. "response_modes_supported": [
139139. "form_post",
140140. "query",
141141. "fragment"
142142. ],
143143. "backchannel_logout_session_supported": true,
144144. "token_endpoint": "https://idp.samplehostname.com/oxauth/restv1/token",
145145. "backchannel_authentication_request_signing_alg_values_supported": [
146146. "RS512",
147147. "ES256",
148148. "ES384",
149149. "ES512",
150150. "PS256",
151151. "PS384",
152152. "PS512"
153153. ],
154154. "response_types_supported": [
155155. "token id_token code",
156156. "token",
157157. "id_token code",
158158. "id_token",
159159. "token id_token",
160160. "code",
161161. "token code"
162162. ],
163163. "backchannel_token_delivery_modes_supported": [
164164. "ping",
165165. "poll"
166166. ],
167167. "request_uri_parameter_supported": true,
168168. "backchannel_user_code_parameter_supported": false,
169169. "grant_types_supported": [
170170. "urn:ietf:params:oauth:grant-type:device_code",
171171. "urn:openid:params:grant-type:ciba",
172172. "password",
173173. "client_credentials",
174174. "authorization_code",
175175. "implicit",
176176. "urn:ietf:params:oauth:grant-type:uma-ticket"
177177. ],
178178. "ui_locales_supported": [
179179. "en",
180180. "bg",
181181. "de",
182182. "es",
183183. "fr",
184184. "it",
185185. "ru",
186186. "tr"
187187. ],
188188. "auth_level_mapping": {
189189. "-1": [
190190. "simple_password_auth"
191191. ]
192192. },
193193. "require_request_uri_registration": false,
194194. "id_token_encryption_alg_values_supported": [
195195. "RSA1_5",
196196. "RSA-OAEP",
197197. "A128KW",
198198. "A256KW"
199199. ],
200200. "frontchannel_logout_session_supported": true,
201201. "claims_locales_supported": [
202202. "en"
203203. ],
204204. "request_object_signing_alg_values_supported": [
205205. "none",
206206. "HS256",
207207. "HS384",
208208. "HS512",
209209. "RS256",
210210. "RS384",
211211. "RS512",
212212. "ES256",
213213. "ES384",
214214. "ES512",
215215. "PS256",
216216. "PS384",
217217. "PS512"
218218. ],
219219. "request_object_encryption_alg_values_supported": [
220220. "RSA1_5",
221221. "RSA-OAEP",
222222. "A128KW",
223223. "A256KW"
224224. ],
225225. "scopes_supported": [
226226. "oxd",
227227. "openid",
228228. "profile",
229229. "phone",
230230. "mid_uid",
231231. "user_name",
232232. "clientinfo",
233233. "mobile_phone",
234234. "email",
235235. "pcr",
236236. "address",
237237. "permission"
238238. ],
239239. "backchannel_logout_supported": true,
240240. "acr_values_supported": [
241241. "simple_password_auth"
242242. ],
243243. "request_object_encryption_enc_values_supported": [
244244. "A128CBC+HS256",
245245. "A256CBC+HS512",
246246. "A128GCM",
247247. "A256GCM"
248248. ],
249249. "device_authorization_endpoint": "https://idp.samplehostname.com/oxauth/restv1/device_authorization",
250250. "display_values_supported": [
251251. "page",
252252. "popup"
253253. ],
254254. "claim_types_supported": [
255255. "normal"
256256. ],
257257. "end_session_endpoint": "https://idp.samplehostname.com/oxauth/restv1/end_session",
258258. "backchannel_authentication_endpoint": "https://idp.samplehostname.com/oxauth/restv1/bc-authorize",
259259. "token_endpoint_auth_signing_alg_values_supported": [
260260. "HS256",
261261. "HS384",
262262. "HS512",
263263. "RS256",
264264. "RS384",
265265. "RS512",
266266. "ES256",
267267. "ES384",
268268. "ES512",
269269. "PS256",
270270. "PS384",
271271. "PS512"
272272. ],
273273. "frontchannel_logout_supported": true,
274274. "jwks_uri": "https://idp.samplehostname.com/oxauth/restv1/jwks",
275275. "subject_types_supported": [
276276. "pairwise"
277277. ],
278278. "id_token_signing_alg_values_supported": [
279279. "none",
280280. "HS256",
281281. "HS384",
282282. "HS512",
283283. "RS256",
284284. "RS384",
285285. "RS512",
286286. "ES256",
287287. "ES384",
288288. "ES512",
289289. "PS256",
290290. "PS384",
291291. "PS512"
292292. ],
293293. "registration_endpoint": "https://idp.samplehostname.com/oxauth/  restv1/register",
294294.  "id_token_token_binding_cnf_values_supported": [
295295.    "tbh"
296296.  ]
297297. }

OpenID Relying Party Onboarding

Mobile ID platform proposes 2 methods to onboard a Relying Party.

A platform administrator registers the OIDC client using the Administration Console based on input data.
A Relying Party registration authority registers the OIDC client using the Dynamic Registration endpoint to provide a “Software Statement” that corresponds to the Relying Party "ID card":

2.1 Dynamic Client Registration

2.2 Software Statements

OpenID Connect Code Flow

The following provides an overview of the sequence for authenticating and authorizing a user through our IDP using OpenID Connect. This conforms to the OpenID Connect Spec 1.0's Authorization Code Flow.

Sequence Diagram

Mobile ID /authorize

The authorization endpoint performs end-user authentication. This is done by sending the user agent to the authorization server using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect.

Request

OIDC Authorization request [03] & [04]

A few security attributes will either already exist, or be created:

Attribute	Definition
`<client_id>`	This is the unique identifier provided by the OP during RP enrollment. Think of this as the RP’s “username”.
`<client_secret>`	This is the OP-issued client_secret, provided by the OP during RP enrollment and associated with the `<client_id>`. Think of it as a password. This value is never passed to the authorization endpoint nor used in any HTTP GET requests.
`<state>`	This is a secure, random identifier associated with a single User Agent’s authorization/authentication session. This opaque value is used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF/XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.
`<s_hash>`	This is a cryptographic hash of the `<state>` attribute. The hash is generated using a secret key known only to the RP, mitigating the risk of token substitution.
`<nonce>`	This string value is used to associate a Client session with an ID Token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing them.

The following additional non-functional security requirements should be met:

Use of TLS version 1.2 or stronger encryption on the communication channels between the User Agent and the RP Server, as well as the backend communication channels between the RP and the IDP.
Securing the <client_secret> on the RP server.
Securing the secret key used to hash the <scope>.
Generation of <state> and <nonce> values using a secure random technique.

The security attributes will be available as follows:

The <client_id>, <state>, and <nonce> should be supplied in an authorization request’s URI.
The <s_hash> should be installed on the User Agent as a cookie or another locally stored item.

The following attributes will also be available for initiating the OpenID Connect Authorization Request:

<scope>: For OpenID Connect, the minimum requirement is that the scope parameter be set to “openid.” Additional scopes may be appended as a space-delimited list.
<redirect_uri>: This defines where the User Agent is to send the authorization code.
<response_type>: For the Authorization Code Flow, this should be set to “code.”
<acr_values>: This parameter controls the authentication methods that the user is required to perform during the authentication process. One of the following values must be selected:

The RP produces an HTTP redirect and provides it to the User Agent. This redirect includes the following query parameters as defined above:

<scope>
<response_type>
<redirect_uri>
<state>
<client_id>
<nonce>
<acr_values>

In addition, a cookie containing the cryptographically hashed <s_hash> is also provided to the User Agent. An example redirect follows, assuming an OP host of mid.command and an RP host of relyingparty.com (Line wraps within values are for display purposes only. Query parameters are URL-encoded.)

Authorization/Authentication request example:

HTTP
11. GET /oxauth/restv1/authorize?
22.   response_type=code&
33.   scope=openid%20name%20address&
44.   client_id=s6BhdRkqt3&
55.    state=af0ifjsldkj&
66.   redirect_uri=https%3A%2F%2Frelyingparty.com%2Flogin HTTP/1.1
77. Host: idp.samplehostname.com

Authorization/Authentication code response example:

HTTP
1HTTP/1.1 302 Found
2Location: https://idp.samplehostname.com/oxauth/restv1/authorize?
3  response_type=code&
4  acr_values=loa-2&
5  scope=openid%20name%20address&
6  redirect_uri=https%3A%2F%2Frelyingparty.com%2Flogin
7    &client_id=%40%2140EA.D454.9D4F.E876%210001%21ECE8.BBEF%210008%210068.3E20
8    &nonce=39ewiy1zxs
9    &state=af0ifjsldkj
10Set-Cookie: s_hash=cc9e6s1iuutoxza9he3e

Response

OIDC Authorization Response [17] & [18]

Upon authentication, the authorization code is provided back to the RP through the User Agent as a redirect. An example redirect from the RP follows below. Notice that we’re redirecting back to the <redirect_uri> provided in the original request:

Upon receiving the authorization code and the associated <state> value, the RP verifies that the provided <state>’s cryptographically hashed value matches the <s_hash> cookie sent along with the request from the User Agent. It is at this point that the RP is able to assemble a security principal by submitting the authorization code to the OP's Access Token endpoint, as detailed later in this guide.

Authorization/Authentication response example:

Language not specified
11.HTTP/1.1 302 Found
22.Location: https://relyingparty.com/login?
33. code=SplxlOBeZQQYbYS6WxSbIA

Mobile ID/ Token

Having received an authorization code, the RP must now retrieve the Access Token and ID Token for the user. This is done in a single call to the OP's token endpoint. The following describes that call.

OIDC Token Request [19]

The token request is posted to the token endpoint. For the following, it is assumed that the OP's token endpoint is located at https://mid.com/oxauth/restv1/token. The following parameters are posted as a content-type application/x-www-form-urlencoded body:

<grant_type> - This is set to authorization_code.
<code> - This is the code received during the authentication/authorization step.
<redirect_uri> - This is the exact <redirect_uri> that was provided in the authorize call made during the authentication/authorization step. (This will be validated by the OP as being the same URI that the authorization code was originally submitted to.)

The <client_id> and <client_secret> are used for authenticating the service request. These are provided as HTTP Basic Access Authentication parameters.

Here is a sample request using the same values in the original authorization/authentication step:

HTTP
1Token request example:
2
3
41.POST /oxauth/restv1/token HTTP/1.1
52.Host:idp.samplehostname.com
63.ContentType: application/x-www-form-urlencoded
74.Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

body:

HTTP
11.grant_type=authorization_code&
22.code=SplxlOBeZQQYbYS6WxSbIA&
33.redirect_uri=https%3A%2

OIDC Token Response [20]

A success response follows. This response contains a number of security features that will be explained later.

Token response example:

HTTP
11.HTTP/1.1 200 OK
22.ContentType: application/json
33.CacheControl: nostore 
44.Pragma: nocache

HTTP
1body:
2
31.{
42.  "access_token": "SlAV32hkKG",
53. "token_type": "Bearer",
64. "refresh_token": "8xLOxBtZp8",
75. "expires_in": 3600,
86.  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRscwh3LOp146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpegccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHqrvKMzqg"
9}

Note: The /Userinfo endpoint, typically available in OpenID Connect IDP, is not available on Mobile ID. By design, "Identity on the Edge," Mobile ID does not store data, even temporarily, on the server side. Mobile ID provides the requested claims directly in the IDToken.

OpenID Connect Client-Initiated Backend Authentication

CIBA Flow

Client-Initiated Backchannel Authentication (CIBA) is an authentication flow in which the Relying Party (RP) can obtain a valid identifier for the user it wants to authenticate without requiring end-user interaction from the consumption device. The flow involves direct communication from the Client to the OpenID Provider without redirecting through the user's browser (consumption device). The Mobile ID CIBA implementation relies on OpenID Client-Initiated Backchannel Authentication Core 1.0.

The Main Technical Impacts of Out-Of-Band Authentication:

The need to provide a user’s identifier (login_hint or id_token_hint) in the authentication request to trigger the flow.
The need to set an asynchronous interface (ping, poll, or push mode) to manage the session through an authentication request ID.
The ability to securely provide (back-end to back-end) a context (binding_message) to address transaction confirmation use cases.

Sequence Diagram

Mobile ID `/bc-authorize`

The /bc-authorize endpoint returns an HTTP 200 OK response to the Client to indicate that the authentication request has been accepted and is in process. The body of this response will contain:

auth_req_id (required): A unique identifier for the authentication request made by the Client.
expires_in (required): A positive integer value indicating the expiration time of the auth_req_id in seconds since the authentication request was received.
interval (optional): A positive integer value indicating the minimum amount of time in seconds that the Client must wait between polling requests to the token endpoint.

OIDC Authorization request [01]

Request

HTTP
1POST /oxauth/restv1/bc-authorize HTTP/1.1
2Host: idp.samplehostname.com
3Content-Type: application/x-www-form-urlencoded

Body

HTTP
11. scope=openid%20email%20example-scope&
2  2. client_notification_token=8d67dc78-7faa-4d41-aabd-67707b374255&
3  3. binding_message=W4SCT&
4  4. login_hint_token=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IkVTMjU2In0.ey
5  5. JzdWJfaWQiOnsiZm9ybWF0IjoicGhvbmUiLCJwaG9uZSI6IisxMzMwMjgxODAwN
6  6. CJ9fQ.GSqxJsFbIyojdfMBDv3MOyAplCViVkwQWzthCWuu9_gnKIqECZilwANt1
7  7. HfIh3x3JFjaEq-5MZ_B3qeb11NAvg&
8  8. client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
9  9. client-assertion-type%3Ajwt-bearer&
10  10.client_assertion=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IkVTMjU2In0.eyJ
11  11. pc3MiOiJzNkJoZFJrcXQzIiwic3ViIjoiczZCaGRSa3F0MyIsImF1ZCI6Imh0dHB
12  12.zOi8vc2VydmVyLmV4YW1wbGUuY29tIiwianRpIjoiYmRjLVhzX3NmLTNZTW80RlN
13  13.6SUoyUSIsImlhdCI6MTUzNzgxOTQ4NiwiZXhwIjoxNTM3ODE5Nzc3fQ.Ybr8mg_3
14  14.E2OptOSsA8rnelYO_y1L-yFaF_j1iemM3ntB61_GN3APe5cl_-5a6cvGlP154XAK
15  15.7fL-GaZSdnd9kg

JWT payload:

HTTP
1{
2"iss": "s6BhdRkqt3",
3"aud": "https://idp.samplehostname.com",
4"exp": 1537820086,
5"iat": 1537819486,
6"nbf": 1537818886,
7"jti": "4LTCqACC2ESC5BWCnN3j58EnA",
8"scope": "openid email example-scope",
9"client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
10"binding_message": "W4SCT",
11"login_hint_token": "eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IkVTMjU2In0.
12  eyJzdWJfaWQiOnsiZm9ybWF0IjoicGhvbmUiLCJwaG9uZSI6IisxMzMwMjgxODA
13  wNCJ9fQ.GSqxJsFbIyojdfMBDv3MOyAplCViVkwQWzthCWuu9_gnKIqECZilwAN
14  t1HfIh3x3JFjaEq-5MZ_B3qeb11NAvg"
15}

Response

OIDC Authorization response [02]

HTTP
11. HTTP/1.1 200 OK
22.Content-Type: application/json
33.Cache-Control: no-store

body

HTTP
1{
2  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
3  "expires_in": 120,
4  "interval": 2
5}

Mobile Id Token

Similarly to the Code Flow, the Relyng Party gets the authentication results at the end of the authentication process perform on the smartphone.

Note: The /Userinfo endpoint typically available in OpenID Connect IDPs is not accessible on Mobile ID. As per the "Identity on the Edge" design, Mobile ID does not store data on the server side, not even temporarily. Instead, Mobile ID directly provides the requested claims within the ID Token.

Three back-channel token delivery methods (token_endpoint_auth_method) are available and must be defined during the registration of the Relying Party:

Ping Mode (recommended)

The Authentication service pings a Relying Party’s notification endpoint with the authentication Request ID as soon as the authentication process is completed on the smartphone. Then, the Relying Party requests the authentication results from the /token endpoint, providing the Authentication Request ID (auth_req_id).

Client Notification

OIDC CIBA client notification [10]

example of a Ping callback

HTTP
11.POST /cb HTTP/1.1
22.Host: client.example.com
33.Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
44.Content-Type: application/json

body:

HTTP
11.{
22. "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1"
33.}

Token Request

OIDC Token request [11]

example of a token request for PING mode

HTTP
11.POST /oxauth/restv1/token HTTP/1.1
22.Host: idp.samplehostname.com
33.Content-Type: application/x-www-form-urlencoded

Body

HTTP
11. grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
22. auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1&
33. client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
44.client-assertion-type%3Ajwt-bearer&
55.client_assertion=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IkVTMjU2In0.ey
66.Jpc3MiOiJzNkJoZFJrcXQzIiwic3ViIjoiczZCaGRSa3F0MyIsImF1ZCI6Imh0d
77.HBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwianRpIjoiLV9wMTZqNkhj
88.aVhvMzE3aHZaMzEyYyIsImlhdCI6MTUzNzgxOTQ5MSwiZXhwIjoxNTM3ODE5Nzg
99.yfQ.BjaEoqZb-81gE5zz4UYwNpC3QVSeX5XhH176vg35zjkbq3Zmv_UpHB2ZugR
1010.Va344WchTQVpaSSShLbvha4yziA

JWT playload

HTTP
11.{
22.  "iss": "s6BhdRkqt3",
33. "sub": "s6BhdRkqt3",
44. "aud": "https://idp.samplehostname.com/token",
55. "jti": "-_p16j6HciXo317hvZ312c",
66. "iat": 1537819491,
77. "exp": 1537819782
88.}

Token response

OIDC Token response [12]

example of a token response for PING mode

HTTP
11.HTTP/1.1 200 OK
22.Content-Type: application/json
33.Cache-Control: no-store

body

HTTP
11.{
22.    "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
33.   "token_type": "Bearer",
44.   "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
55.   "expires_in": 120,
66.   "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJo
77.   dHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIs
88.   ImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20i
99.   LCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJ
1010.   LjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynv
1111.  MHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8iczD16A5gNjSD7yenT5fslrrW-NU
1212.   _vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LH
1313.   fW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1
1414.   EFWtjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCw
1515.   DQrVlg"
1616. }

a base64url decoded ID Token from the example above:

HTTP
11.{
22.  "iss": "https://idp.samplehostname.com",
33. "sub": "248289761001",
44.  "aud": "s6BhdRkqt3",
55. "email": "janedoe@example.com",
66. "exp": 1537819803,
77. "iat": 1537819503
88.}

Poll Mode.

The Relying Party polls the /token endpoint to get the authentication results (ID Token and Access Token) using the Authentication Request ID (auth_req_id).

Token request

OIDC Token request [13]

example of a token request for POLL mode

HTTP
11. POST /oxauth/restv1/token HTTP/1.1
22. Host: idp.samplehostname.com
33. Content-Type: application/x-www-form-urlencoded

body:

HTTP
11. grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&
22. auth_req_id=1c266114-a1be-4252-8ad1-04986c5b9ac1&
33. client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A
44. client-assertion-type%3Ajwt-bearer&
55. client_assertion=eyJraWQiOiJsdGFjZXNidyIsImFsZyI6IkVTMjU2In0.ey
66. Jpc3MiOiJzNkJoZFJrcXQzIiwic3ViIjoiczZCaGRSa3F0MyIsImF1ZCI6Imh0d
77. HBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwianRpIjoiLV9wMTZqNkhj
88. aVhvMzE3aHZaMzEyYyIsImlhdCI6MTUzNzgxOTQ5MSwiZXhwIjoxNTM3ODE5Nzg
99. yfQ.BjaEoqZb-81gE5zz4UYwNpC3QVSeX5XhH176vg35zjkbq3Zmv_UpHB2ZugR
1010. Va344WchTQVpaSSShLbvha4yziA

JWT payload:

HTTP
11.{
22.  "iss": "s6BhdRkqt3",
33. "sub": "s6BhdRkqt3",
44. "aud": "https://idp.samplehostname.com/token",
55. "jti": "-_p16j6HciXo317hvZ312c",
66.  "iat": 1537819491,
77. "exp": 1537819782
88.}

Token Response

OIDC Token response [14]

example of a token response for POLL mode

HTTP
11.HTTP/1.1 200 OK
22.Content-Type: application/json
33. Cache-Control: no-store

body

HTTP
11.{
22.    "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
33.   "token_type": "Bearer",
44.   "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
55.   "expires_in": 120,
66.    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJo
77.   dHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMSIs
88.    ImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb20i
99.   LCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwM30.aVq83mdy72ddIFVJ
1010.   LjlNBX-5JHbjmwK-Sn9Mir-blesfYMceIOw6u4GOrO_ZroDnnbJXNKWAg_dxVynv
1111.   MHnk3uJc46feaRIL4zfHf6Anbf5_TbgMaVO8iczD16A5gNjSD7yenT5fslrrW-NU
1212.   _vtmi0s1puoM4EmSaPXCR19vRJyWuStJiRHK5yc3BtBlQ2xwxH1iNP49rGAQe_LH
1313.    fW1G74NY5DaPv-V23JXDNEIUTY-jT-NbbtNHAxnhNPyn8kcO2WOoeIwANO9BfLF1
1414.   EFWtjGPPMj6kDVrikec47yK86HArGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCw
1515.   DQrVlg"
1616.}

a base64url decoded ID Token from the example above:

HTTP
11.{
22. "iss": "https://idp.samplehostname.com",
33. "sub": "248289761001",
44. "aud": "s6BhdRkqt3",
55. "email": "janedoe@example.com",
66. "exp": 1537819803,
77. "iat": 1537819503
88.}

PUSH mode

As soon as the authentication process on the smartphone is completed, the authentication service sends the authentication results (ID token and access token) to the Relying Party.

Client notification

OIDC CIBA Client Notification

Example of push callback

HTTP
11.POST /cb HTTP/1.1
22.Host: client.example.com
33.Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
44.Content-Type: application/json

Body

HTTP
11.{
22.   "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
33.   "access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
44.   "token_type": "Bearer",
55.   "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
66.   "expires_in": 120,
77.   "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2NzcyNiJ9.eyJpc3MiOiJ
88.   odHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsInN1YiI6IjI0ODI4OTc2MTAwMS
99.   IsImF1ZCI6InM2QmhkUmtxdDMiLCJlbWFpbCI6ImphbmVkb2VAZXhhbXBsZS5jb
1010.   20iLCJleHAiOjE1Mzc4MTk4MDMsImlhdCI6MTUzNzgxOTUwMywiYXRfaGFzaCI6
1111.   Ild0MGtWRlhNYWNxdm5IZXlVMDAwMXciLCJ1cm46b3BlbmlkOnBhcmFtczpqd3Q
1212.  6Y2xhaW06cnRfaGFzaCI6InNIYWhDdVNwWENSZzVta0REdnZyNHciLCJ1cm46b3
1313.  BlbmlkOnBhcmFtczpqd3Q6Y2xhaW06YXV0aF9yZXFfaWQiOiIxYzI2NjExNC1hM
1414.   WJlLTQyNTItOGFkMS0wNDk4NmM1YjlhYzEifQ.SGB5_a8E7GjwtoYrkFyqOhLK6
1515.   L8-Wh1nLeREwWj30gNYOZW_ZB2mOeQ5yiXqeKJeNpDPssGUrNo-3N-CqNrbmVCb
1616.   XYTwmNB7IvwE6ZPRcfxFV22oou-NS4-3rEa2ghG44Fi9D9fVURwxrRqgyezeD3H
1717.   HVIFUnCxHUou3OOpj6aOgDqKI4Xl2xJ0-kKAxNR8LljUp64OHgoS-UO3qyfOwIk
1818.   IAR7o4OTK_3Oy78rJNT0Y0RebAWyA81UDCSf_gWVBp-EUTI5CdZ1_odYhwB9OWD
1919.    W1A22Sf6rmjhMHGbQW4A9Z822yiZZveuT_AFZ2hi7yNp8iFPZ8fgPQJ5pPpjA7u
2020.   dg"
2121.}

a base64url decoded ID Token from the example above:

HTTP
11.{
22.   "iss": "https://idp.samplehostname.com",
33.   "sub": "248289761001",
44.   "aud": "s6BhdRkqt3",
55.   "email": "janedoe@example.com",
66.   "exp": 1537819803,
77.   "iat": 1537819503,
88.   "at_hash": "Wt0kVFXMacqvnHeyU0001w",
99.    "urn:openid:params:jwt:claim:rt_hash": "sHahCuSpXCRg5mkDDvvr4w",
1010.   "urn:openid:params:jwt:claim:auth_req_id":
1111.   "1c266114-a1be-4252-8ad1-04986c5b9ac1"
1212.}

Glossary of Terms

Common terminology referenced in this guide:

Term	Definition
IDP	Identity Provider	This is IDEMIA's Identity & Access Management Platform.
OP	OpenID Connect Provider	IDEMIA's OpenID Connect compliant Identity Provider.
RP	Relying Party	The party relying on the IDP for user authentication and attributes.
Client	Generally refers to the RP's client account registered in the IDP.	The account that the RP utilizes to authenticate themselves to the IDP for the purposes of user authentication, retrieval of authorized user attributes, and other OpenID Connect transactions.
Subject/Sub	Generally refers to the end-user.	The subject/user performing the authentication and authorizing the release of their attributes to the RP.
OIDC	OpenID Connect	A widely used identity federation protocol.

Relying Party Integration Guide

Introduction

Workflow Overview

OpenID Connect Authorization-Code Flow

Open ID Connect Client Initiated Backend Authentication

MOBILE ID OpenID Connect Endpoint

OpenID Connect Discovery

Request

Response

OpenID Relying Party Onboarding

2.1 Dynamic Client Registration

2.2 Software Statements

OpenID Connect Code Flow

Sequence Diagram

Mobile ID /authorize

Request

OIDC Authorization request [03] & [04]

Authorization/Authentication request example:

Response

OIDC Authorization Response [17] & [18]

Authorization/Authentication response example:

Mobile ID/ Token

OIDC Token Request [19]

OIDC Token Response [20]

OpenID Connect Client-Initiated Backend Authentication

CIBA Flow

Sequence Diagram

Mobile ID /bc-authorize

Request

Response

Mobile Id Token

Ping Mode (recommended)

Client Notification

Token Request

Token response

OIDC Token response [12]

Poll Mode.

Token request

OIDC Token request [13]

Token Response

OIDC Token response [14]

PUSH mode

Client notification

OIDC CIBA Client Notification

Body

Glossary of Terms

Mobile ID `/bc-authorize`