Relying Party Integration Guide 

This guide describes the OpenID Connect capabilities of the IDEMIA Mobile ID Solution by a Relying Party (Client/OpenID Connect Client) and its ability to authenticate or simply request identity attributes from a Mobile ID-credentialed user. This workflow leverages the OpenID Connect authorization-code flow which leverages HTTP redirects and simple REST requests.

Workflow Overview 

This guide demonstrates the various functional components associated with typical end-user/Relying Party interactions. An end user initiates some action with a Relying Party, who is being asked to authenticate, and then optionally shares identity attributes with the Relying Party in response to a consent request for these attributes to be shared. The following figure illustrates a sample end-to-end workflow:

RPIG Fig1 end-to-end workflow
Figure 1: End-to-end workflow

OpenID Connect Discovery 

OpenID Connect provides an endpoint to Relying Parties to locate the various service APIs. This allows a Relying Party to dynamically configure their client software to load these URIs without relying on hard-coded values.

The discovery endpoint for IDEMIA Mobile ID products is located at:

This API returns a JSON response.

OIDC Discovery Endpoint Response 

2 "issuer": "",
3 "authorization_endpoint": "",
4 "token_endpoint": "",
5 "userinfo_endpoint": "",
6 "end_session_endpoint": ""
7 // ...
8 // ...

This guide is primarily concerned with four OpenID Connect endpoints. These are:

  • /authorization
  • /token
  • /userinfo
  • /end_session

The APIs corresponding to the four endpoints above can be dynamically populated from the values returned by the discovery endpoint.


The Authentication/Authorization endpoint allows a user to log in to the Relying Party's system using the IDEMIA Mobile ID Solution, which gives a higher Level of Assurance (LOA) and more flexible authentication methods than a standard username/password combination. It can be tailored to include a multifactor authentication key, in addition to a pin code and/or a biometric modality to raise the level of trust if a transaction type requires it, as per the recommended trust levels that IDEMIA offers.

These are:

Trust Level
Authentication Factors Provided
App Request Card Handling
1: Repeat VisitorAuto-sign-on to a news site to anonymously post content in comments sectionHaving credential/app is enough authentication; only pairwise: Only a pseudonymous ID will be released to the Relying Party (RP). No other attributes are released when using only the openID scope.2FA: App can automatically handle the request if running.
2: Confirmed VisitorLog into government (state/federal) website to view account statusPossession of credential/app plus one other authentication factor of the user's choice; pairwise: A pseudonymous ID will be released to the RP in addition to any other attributes the RP is allowed to request.2FA: App should notify user of the request and allow them to respond. The user can respond right on the request card because the app is unlocked at TL2.
3: Identified PersonApply for government benefits providing full driver's license (DL) info; manage direct deposit of benefits funds; add family or change circumstances.Possession of credential/app plus one other authentication factor bound to provenance of proofing authority; pairwise: A pseudonymous ID will be released to the RP in addition to any other attributes the RP is allowed to request.MFA: Biometric input according to template of authoritative provenance and signed template is required.
4: Authentic IdentityTransfer e-title on a vehicle; drive a rental car off the lot.Possession of credential/app, one authentication factor bound to provenance of proofing authority, AND one additional factor of user's choice, plus freshness of record at proofing authority. Pairwise: A pseudonymous ID will be released to the RP in addition to any other attributes the RP is allowed to request.MFA: Add liveness to the biometric input, plus another cognitive or possession factor.

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

The main sequence for the use case has three phases:

  1. Authorization required -> Authorization Request
  2. Authentication
  3. Authorization granted

Figure 2 offers a detailed outline of interacting with the IDP's OIDC APIs, starting with the "authorization required" phase.

RPIG Fig2 Authorization granted
Figure 2: Authorization granted

Authorization Required 

When a user requests a secured resource from the RP, an authentication/authorization session is initiated. Figure 3 describes the initial setup of that session.

RPIG Fig3 Authorization required

Figure 3: Authorization required

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

<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; it was provided by the OP during RP enrollment and is associated with the <client_id>. Think of this as a password. This value is never passed to the authorization endpoint, nor used in any HTTP GET requests. Note: the client secret can not contain the '+' character.
<state>This is a secure random identifier associated with a single User Agent's authorization/authentication session. This opaque value is used to maintain the 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 to mitigate the risk of token substitution.
<nonce>This string value 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 the values.

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 of the <client_secret> on the RP server.
  • Securing of 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 other 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:
Parameter Value
Effect on User Authentication Process
"loa-2"Crypto-based Multifactor authN only.
"loa-3"Crypto-based Multifactor authN plus one additional factor.
"loa-4"Crypto-based Multifactor authN with the requirement that the user must also perform pin-based and biometric authentication

Additional parameter values may be added in the future to provide additional clarity and flexibility for RPs (such as "mfa","pin","face" in place of "loa-x"). When that happens, the new values will be published in the "acr_values_supported" section of Discovery API referenced earlier in this document.

Authorization Request 

RPIG Fig4 Authorization request

Figure 4: Authorization request

The RP produces a HTTP redirect and provides it to the User Agent. That 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, in which an OP host of and RP host of are assumed. (Line wraps within values are for display purposes only. Query parameters are URL encoded.)

1HTTP/1.1 302 Found
3 response_type=code&acr_values=loa-2
4 &scope=openid%20name%20address
5 &
7 &nonce=39ewiy1zxs
8 &state=af0ifjsldkj
9Set-Cookie: s_hash=cc9e6s1iuutoxza9he3e

The User Agent is redirected to the OP authorization page. (Details around identity verification performed by the OP are not in scope for this section.) Once authentication is completed, an authorization code is provided to the User Agent.

RPIG Fig5 Authorization request authentication
Figure 5: Authorization request - authentication


The interactions in this portion of the flow occur only between the end user and the IDP. The end-user authenticates themselves to the Mobile ID App and to the IDP and then chooses to grant consent to the RP for the requested attributes.

Authorization Granted 

RPIG Fig6 Authorization granted

Figure 6: Authorization granted

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:

1HTTP/1.1 302 Found
3 code=SplxlOBeZQQYbYS6WxSbIA
4 &state=af0ifjsldkj

Along with the query parameters, the cookie (or locally saved data) <s_hash> is included.

RPIG Fig7 Submit authorization code

Figure 7: Submit authorization code

Upon receiving the authorization code and 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 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.

With that security principal established, the OP is now able to apply their own authorization rules and grant the user access to protected resources.

RPIG Fig8 Authorized access granted

Figure 8: Authorized access granted

Access 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.

Token Request 

The token request is posted to the token endpoint. For the following, it is assumed that the OP's token endpoint is located at 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:

1POST /token HTTP/1.1
3ContentType: application/x-www-form-urlencoded
4Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Token Response 

A success response follows. This response contains a number of security features.

1HTTP/1.1 200 OK
2ContentType: application/json
3CacheControl: nostore Pragma: nocache
5 "access_token": "SlAV32hkKG",
6 "token_type": "Bearer",
7 "refresh_token": "8xLOxBtZp8",
8 "expires_in": 3600,
9 "id_token":
10 "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
11 yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
12 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
13 fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
14 AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
15 Jp6IcmD3HP99Obi1PRscwh3LOp146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
16 NqeGpegccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
17 QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
18 K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
19 XUVrWOLrLl0nx7RkKU8NXNHqrvKMzqg"

The <id_token> is parsed as follows:

  1. Split the string at char '.' - this results in three different strings:

    1. eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ

    2. ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEy ODA5NzAKfQ

    3. ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRscwh3LOp146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpegccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHqrvKMzqg

  2. String 1a above is Base64-decoded to reveal the signature algorithm and key ID. For this example, algorithm "RS256" is used and a private key is used for the signature. That key is the client_secret (known by both the client and the OP).

  3. String 1c above is the Base64-encoded signature of String 1b.

  4. String 1b above is the Base64-encoded claim.

  5. Decoding 1b results in something like the following:

2 "iss": "[](",
3 "sub": "248289761001",
4 "aud": "@!40EA.D454.9D4F.E876!0001!ECE8.BBEF!0008!0068.3E20",
5 "nonce": "39ewiy1zxs",
6 "exp": 1311281970,
7 "iat": 1311280970

Validation of the id_token includes the following rules:

  1. The claims should include a <nonce>. That <nonce> must match the <nonce> originally supplied by the RP in the authorization request to the OP.
  2. The issuer (<iss>) must match the expected OP.
  3. The audience includes the <client_id> originally used when the authorization code was requested.

In addition, the <iat> (time at which the JSON Web token was issued) claim can be used to reject tokens that were issued too far from the current time, limiting the amount of time that nonces are stored to prevent attacks. The acceptable range is client-selected.

The <sub> claim is the Pairwise Pseudonymous Identifier (PPID or PPUID) and is used by the RP to uniquely identify this user in IDEMIA's Mobile ID core services. This value is only ever returned to the client that it was issued to. It should be associated with the user in the RP's local system of record.

User Info 

The /userinfo endpoint provides the claims for the scope(s) requested in the authorization request. For the <mt_scope> this includes such claims as First Name, Last Name, and Driver's License Number, among other items.

The claims set for any given scope is published in the "scope_to_claims_mapping" section of the discovery API.

A single POST request is made to the /userinfo endpoint. For example, given a hostname of "" the endpoint would be:

NOTE: The hostname may be different.

There is only a single parameter passed into the /userinfo endpoint as part of the request. It is posted as a content-type application/x-www-form-urlencoded body:

<access_token> - This is the <access_token> value that was returned in the response from the /token endpoint.

The /userinfo endpoint requires a bearer token for authentication. The value of this bearer token is the <access_token> returned from the /token response.

For example, if the access_token value returned in the id_token was “1962e492-a070-4f8d-bdb1-2f464bea77a1”, the following would be the value for the authorization header:

Authorization: Bearer 1962e492-a070-4f8d-bdb1-2f464bea77a1

In addition to BASIC authentication, the /userinfo endpoint also requires the following header:

1Content-Type: application/x-www-form-urlencoded

The following is an example of a complete request:

1POST /userinfo HTTP/1.1
2Host: [](
3ContentType: application/x-www-form-urlencoded
4Authorization: Bearer 1962e492-a070-4f8d-bdb1-2f464bea77a1

A successful response is returned as:

1HTTP/1.1 200 OK
2ContentType: application/json CacheControl: nostore Pragma: nocache
4 "sub": "38c54321-2212-42cf-1234-56e2890e2b70",
5 "nonce": "sameNonceFromAuthandTokenRequests",
6 "family_name": "Smith",
7 "address.street_address": "123 ABC Lane",
8 "dl_number": "1234567890",
9 "phone_number": "5555555555",
10 "gender": "M",
11 "address.region": "MN",
12 "birthdate": "1990-06-21",
13 "phone_number_verified": false,
14 "updated_at": false,
15 "email_verified": false,
16 "address.locality": "MINNEAPOLIS",
17 "given_name": "JERRY",
18 "address.postal_code": "55401-3041",
19 "claims_denial": false,
20 "middle_name": "BERRY",
21 "": ""


  • In many states the country value is not encoded in the 2D barcode on the license. As such, it is not uncommon for the <> claim value to be empty.
  • The Relying Party should verify that the <nonce> returned in the /userinfo response is equal to what the relying party provided in the /authorization request. Likewise it should also be equal to the <nonce> value returned in the /token response.
  • The <sub> claim is the Pairwise Pseudonymous Identifier (PPID or PPUID) and is used by the RP to uniquely identify this user in IDEMIA's Mobile ID back-end. This identifier should be associated with the user in the RP's local system of record.

End Session 

The /end_session endpoint is used by the Relying Party to engage a Relying Party-initiated logout as defined in the OpenID connect session management (draft) spec located at

Relying Party-Initiated Logout 

A Relying Party can notify the OP that the end-user has logged out of the site and might want to log out of the OP as well. In this case, the Relying Party, after having logged the end-user out of the Relying Party, redirects the end-user's User Agent to the OP's logout endpoint URL. This URL is obtained via the end_session_endpoint element of the OP's discovery response.

The following parameters are passed as query parameters in the logout request:

  • id_token_hint

    REQUIRED. This is the previously issued ID Token passed to the logout endpoint as a hint about the end-user's current authenticated session with the client. This is used as an indication of the identity of the end-user that the Relying Party is requesting be logged out by the OP.

  • post_logout_redirect_uri

    REQUIRED. This is the URL which the Relying Party has previously registered with the OP for the purpose of redirecting the end-user's User Agent to after a logout has been performed.

  • state

    OPTIONAL. This is an opaque value used by the Relying Party to maintain the state between the logout request and the callback to the endpoint specified by the post_logout_redirect_uri query parameter. If it's included in the logout request, the OP passes this value back to the Relying Party using the state query parameter when redirecting the User Agent back to the RP.


This example assumes a redirect after the IdP session logout to

1curl -X GET \
2 ' &state=state_string' \
3 -H 'cache-control: no-cache'

The consent API is designed to allow the RP to send a consent request and receive user approval via HTTP callback.

The basic flow is presented in Figure 9 below:

RPIG Fig9 Consent workflow
Figure 9: Consent workflow
  1. The client sends a consent request to the IDEMIA IDP Consent REST endpoint.
  2. IDEMIA Consent Service retrieves the person's push notification attributes (device token and platform) from IDP.
  3. IDEMIA Consent Service creates and sends a push notification request to the Notification Service, which sends a consent push notification to the mobile device.
  4. User receives push notification, reviews the content of the consent request, and either approves or refuses it.
  5. If approved, the Mobile ID App sends a consent approval message to IDEMIA Consent Service using Consent Approve REST endpoint.
  6. IDEMIA Consent Service creates a callback request and sends it back to the client's Callback REST endpoint.

IDEMIA IDP consent REST API is an HTTP POST operation:

\<host url\>/api/v1/consent

The body contains the following properties in the form of a JSON string:

  1. ppId - Relying Party sends a PPID to identify the user. The Pairwise Pseudonymous Identifier (PPID or PPUID), is used to uniquely identify this user in IDEMIA's Mobile ID back-end, and should be associated with the user in the Client's local system of record.
  2. state - This is a secure random identifier associated with a single User Agent's authorization/authentication session. This is used to verify that the responses received are from their expected sources.
  3. consentId - This is the unique consent identifier issued by the consent client.
  4. expirationTs - Consent response expiration date and time. The user must submit consent approval no later than this value otherwise, it will be rejected. Accepted format: yyyy-MM-dd hh:mm
  5. clientId - This is the unique identifier provided by the OP during RP enrollment.
  6. callbackUrl - This is URL for consent approval callback.
  7. message - Message to be sent over to the Mobile ID App. a. header - Message header. b. subject - Subject of this message. Example: Tax Approve c. body - Message body containing information required for consent approval by the user. The example is: Tax return information. d. loa - Level of Assurance. Number between 1 and 4.
1POST http://localhost:8080/api/v1/consent
2POST data:
4 "ppId": "\@!D126.8353.EE13.B16B!0001!F4DE.964F!0000!D81D.D5A4",
5 "state": "720c767238fbfeaeb47e962c0f36bf330e0e0afcb8b260811a93ee7d8bddee63",
6 "consentId": "FkZHJlc3MxIjoiMTExIFNvbWUgc3RyZWV0IiwiYWRkc",
7 "expirationTs": "2016-12-11 12:08:56 -0700",
8 "clientId": "\@!FF0F.7600.90F1.5E8F!0001!40EF.B8FC!0008!7538.261E",
9 "callbackUrl":"http://localhost:8080/dorsimulator/rest/consent/callback",
10 "message":
11 {
12 "header":"",
13 "subject":"Tax Approve",
14 "body":"here is your tax return info: blah, blah, blah",
15 "loa":"1"
16 }
18[no cookies]
19Request Headers:
20Connection: keep-alive
21Accent: application/json
22Content-Type: application/json
23apikey: 02d040a6-5365-4e15-88e9-4c48dd1f6396

NOTE: IDEMIA IDP Consent API is an asynchronous operation, which will return HTTP request codes 200 (OK), 400 (invalid request), or 500 (server error).

IDEMIA IDP sends the Consent Approval result to the Client using the provided REST endpoint. The proposed callback API looks like this:

1PUT http://localhost:8080/dorsimulator/rest/consent/callback PUT data:
3 "state": "720c767238fbfeaeb47e962c0f36bf330e0e0afcb8b260811a93ee7d8bddee63",
4 "consentId": "FkZHJlc3MxIjoiMTExIFNvbWUgc3RyZWV0IiwiYWRkc",
5 "result": {
6 "code": "TRUE",
7 "description": "Tax return approval response"
8 },
9 "ppId": "@!D126.8353.EE13.B16B!0001!F4DE.964F!0000!D81D.D5A4"
11[no cookies]
12Request Headers:
13Connection: keep-alive
14Accent: application/json
15Content-Type: application/json
16Content-Length: 318
17Host: localhost:8080
18User-Agent: Apache-HttpClient/4.2.6 (java 1.5)

For test purposes, a mock web service is available for the consent callback. It comes in the form of a WAR file which can be deployed on the web container of your choice.

(Deployable WAR file provided on request.)

Glossary of Terms 

Common terminology referenced in this guide:

IDPIdentity ProviderThis is IDEMIA's Identity & Access Management Platform.
OPOpenID Connect ProviderIDEMIA's OpenID Connect compliant Identity Provider.
RPRelying PartyThe party relying on the IDP for user authentication and attributes.
ClientGenerally 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/SubGenerally refers to the end-user.The subject/user performing the authentication and authorizing the release of their attributes to the RP.
OIDCOpenID ConnectA widely used identity federation protocol.