Online Authentication Rest API

Digital Credential exposes 4 different endpoints to a Relying Party:

OpenID Connect Discovery: Used to get Digital Credential 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, Digital Credential 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 Digital Credential. Instead, Digital Credential provides the requested claims directly in the IDToken.
/end_session endpoint, typically available in OpenID Connect IDPs, is not available in Digital Credential as SSO is not supported due to the lack of claims on the server side.

Know where is user during online authentication process

In order to make use of the API, please log in

Download dc-authenticate\oxAuth-openapi.json

Besides the standard oxAuth REST API endpoints, there are also OpenID Connect Discovery endpoints exposing service configuration. These allow relying parties to dynamically retrieve endpoint URIs and other OIDC settings, avoiding hard-coded client configuration. The discovery endpoint is available for IDEMIA Digital Credential products.

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 Digital Credential products is located at:

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

Digital Credential /.well-known/openid-configuration

Request

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

Response

JSON
11. HTTP/1.1 200 OK
22. ContentType: application/json
3
4Body
5
61. {
72. "request_parameter_supported": true,
83. "claims_parameter_supported": false,
94. "issuer": "https://idp.samplehostname.com",
105. "id_token_encryption_enc_values_supported": [
116. "A128CBC+HS256",
127. "A256CBC+HS512",
138. "A128GCM",
149. "A256GCM"
1510. ],
1611. "authorization_endpoint": "https://idp.samplehostname.com/oxauth/restv1/authorize",
1712. "service_documentation": "https://developer.idemia.com",
1813. "claims_supported": [
1914. "street_address",
2015. "country",
2116. "zoneinfo",
2217. "role",
2318. "birthdate",
2419. "gender",
2520. "user_name",
2621. "formatted",
2722. "phone_mobile_number",
2823. "preferred_username",
2924. "inum",
3025. "locale",
3126. "personIdentityCodeSample",
3227. "updated_at",
3328. "surname",
3429. "post_office_box",
3530. "nickname",
3631. "email",
3732. "midUid",
3833. "preferred_language",
3934. "personalIdentityCode",
4035. "rp_PCR",
4136. "website",
4237. "email_verified",
4338. "profile",
4439. "locality",
4540. "phone_number_verified",
4641. "room_number",
4742. "dateOfBirth",
4843. "given_name",
4944. "middle_name",
5045. "picture",
5146. "names",
5247. "name",
5348. "phone_number",
5449. "postal_code",
5550. "region",
5651. "family_name"
5752. ],
5853. "scope_to_claims_mapping": [
5954. {
6055. "email": [
6156. "email_verified",
6257. "email"
6358. ]
6459. },
6560. {
6661. "phone": [
6762. "phone_number_verified",
6863. "phone_number"
6964. ]
7065. },
7166. {
7267. "user_name": [
7368. "user_name"
7469. ]
7570. },
7671. {
7772. "pcr": [
7873. "rp_PCR"
7974. ]
8075. },
8176. {
8277. "mid_uid": [
8378. "midUid"
8479. ]
8580. },
8681. {
8782. "address": [
8883. "formatted",
8984. "postal_code",
9085. "street_address",
9186. "locality",
9287. "country",
9388. "room_number",
9489. "region",
9590. "post_office_box"
9691. ]
9792. },
9893. {
9994. "clientinfo": [
10095. "name",
10196. "inum"
10297. ]
10398. },
10499. {
105100. "mobile_phone": [
106101. "phone_mobile_number"
107102. ]
108103. },
109104. {
110105. "permission": [
111106. "role"
112107. ]
113108. },
114109. {
115110. "profile": [
116111. "name",
117112. "family_name",
118113. "given_name",
119114. "middle_name",
120115. "nickname",
121116. "preferred_username",
122117. "profile",
123118. "picture",
124119. "website",
125120. "gender",
126121. "birthdate",
127122. "zoneinfo",
128123. "locale",
129124. "updated_at",
130125. "preferred_language"
131126. ]
132127. }
133128. ],
134129. "token_endpoint_auth_methods_supported": [
135130. "client_secret_basic",
136131. "client_secret_post",
137132. "client_secret_jwt",
138133. "private_key_jwt",
139134. "tls_client_auth",
140135. "self_signed_tls_client_auth"
141136. ],
142137. "tls_client_certificate_bound_access_tokens": true,
143138. "response_modes_supported": [
144139. "form_post",
145140. "query",
146141. "fragment"
147142. ],
148143. "backchannel_logout_session_supported": true,
149144. "token_endpoint": "https://idp.samplehostname.com/oxauth/restv1/token",
150145. "backchannel_authentication_request_signing_alg_values_supported": [
151146. "RS512",
152147. "ES256",
153148. "ES384",
154149. "ES512",
155150. "PS256",
156151. "PS384",
157152. "PS512"
158153. ],
159154. "response_types_supported": [
160155. "token id_token code",
161156. "token",
162157. "id_token code",
163158. "id_token",
164159. "token id_token",
165160. "code",
166161. "token code"
167162. ],
168163. "backchannel_token_delivery_modes_supported": [
169164. "ping",
170165. "poll"
171166. ],
172167. "request_uri_parameter_supported": true,
173168. "backchannel_user_code_parameter_supported": false,
174169. "grant_types_supported": [
175170. "urn:ietf:params:oauth:grant-type:device_code",
176171. "urn:openid:params:grant-type:ciba",
177172. "password",
178173. "client_credentials",
179174. "authorization_code",
180175. "implicit",
181176. "urn:ietf:params:oauth:grant-type:uma-ticket"
182177. ],
183178. "ui_locales_supported": [
184179. "en",
185180. "bg",
186181. "de",
187182. "es",
188183. "fr",
189184. "it",
190185. "ru",
191186. "tr"
192187. ],
193188. "auth_level_mapping": {
194189. "-1": [
195190. "simple_password_auth"
196191. ]
197192. },
198193. "require_request_uri_registration": false,
199194. "id_token_encryption_alg_values_supported": [
200195. "RSA1_5",
201196. "RSA-OAEP",
202197. "A128KW",
203198. "A256KW"
204199. ],
205200. "frontchannel_logout_session_supported": true,
206201. "claims_locales_supported": [
207202. "en"
208203. ],
209204. "request_object_signing_alg_values_supported": [
210205. "none",
211206. "HS256",
212207. "HS384",
213208. "HS512",
214209. "RS256",
215210. "RS384",
216211. "RS512",
217212. "ES256",
218213. "ES384",
219214. "ES512",
220215. "PS256",
221216. "PS384",
222217. "PS512"
223218. ],
224219. "request_object_encryption_alg_values_supported": [
225220. "RSA1_5",
226221. "RSA-OAEP",
227222. "A128KW",
228223. "A256KW"
229224. ],
230225. "scopes_supported": [
231226. "oxd",
232227. "openid",
233228. "profile",
234229. "phone",
235230. "mid_uid",
236231. "user_name",
237232. "clientinfo",
238233. "mobile_phone",
239234. "email",
240235. "pcr",
241236. "address",
242237. "permission"
243238. ],
244239. "backchannel_logout_supported": true,
245240. "acr_values_supported": [
246241. "simple_password_auth"
247242. ],
248243. "request_object_encryption_enc_values_supported": [
249244. "A128CBC+HS256",
250245. "A256CBC+HS512",
251246. "A128GCM",
252247. "A256GCM"
253248. ],
254249. "device_authorization_endpoint": "https://idp.samplehostname.com/oxauth/restv1/device_authorization",
255250. "display_values_supported": [
256251. "page",
257252. "popup"
258253. ],
259254. "claim_types_supported": [
260255. "normal"
261256. ],
262257. "end_session_endpoint": "https://idp.samplehostname.com/oxauth/restv1/end_session",
263258. "backchannel_authentication_endpoint": "https://idp.samplehostname.com/oxauth/restv1/bc-authorize",
264259. "token_endpoint_auth_signing_alg_values_supported": [
265260. "HS256",
266261. "HS384",
267262. "HS512",
268263. "RS256",
269264. "RS384",
270265. "RS512",
271266. "ES256",
272267. "ES384",
273268. "ES512",
274269. "PS256",
275270. "PS384",
276271. "PS512"
277272. ],
278273. "frontchannel_logout_supported": true,
279274. "jwks_uri": "https://idp.samplehostname.com/oxauth/restv1/jwks",
280275. "subject_types_supported": [
281276. "pairwise"
282277. ],
283278. "id_token_signing_alg_values_supported": [
284279. "none",
285280. "HS256",
286281. "HS384",
287282. "HS512",
288283. "RS256",
289284. "RS384",
290285. "RS512",
291286. "ES256",
292287. "ES384",
293288. "ES512",
294289. "PS256",
295290. "PS384",
296291. "PS512"
297292. ],
298293. "registration_endpoint": "https://idp.samplehostname.com/oxauth/  restv1/register",
299294.  "id_token_token_binding_cnf_values_supported": [
300295.    "tbh"
301296.  ]
302297. }

OpenID Relying Party Onboarding

Digital Credential platform proposes 2 methods to onboard a Relying Party.

1. Platform Administrator Method

A platform administrator registers the OIDC client using the Administration Console based on input data.

2. Relying Party Method

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

Digital Credential /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:

Relying Party Integration Guide

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
1GET /oxauth/restv1/authorize?
2    response_type=code&
3    scope=openid%20name%20address&
4    client_id=s6BhdRkqt3&
5    state=af0ifjsldkj&
6    redirect_uri=https%3A%2F%2Frelyingparty.com%2Flogin HTTP/1.1
7Host: idp.samplehostname.com

Authorization/Authentication code response example:

Language not specified
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.