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:

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: https://idp.samplehostname.com/.well-known/openid-configuration.

This API returns a JSON response.

OIDC Discovery Endpoint Response 

JSON
1{
2  "issuer": "https://idp.host.com",
3  "authorization_endpoint": "https://idp.host.com/oxauth/restv1/authorize",
4  "token_endpoint": "https://idp.host.com/oxauth/restv1/token",
5  "userinfo_endpoint": "https://idp.host.com/oxauth/restv1/userinfo",
6  "end_session_endpoint": "https://idp.host.com/oxauth/restv1/end_session"
7  // ...
8  // ...
9}

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.

Authentication/Authorization 

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:

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.

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.

Figure 3: Authorization required

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

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:

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 

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 mid.com and RP host of relyingparty.com are assumed. (Line wraps within values are for display purposes only. Query parameters are URL encoded.)

HTTP
1HTTP/1.1 302 Found
2Location: https://mid.com/oxauth/restv1/authorize
3  response_type=code&acr_values=loa-2
4  &scope=openid%20name%20address
5  &redirect_uri=https%3A%2F%2Frelyingparty.com%2Flogin
6&client_id=%40%2140EA.D454.9D4F.E876%210001%21ECE8.BBEF%210008%210068.3E20
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.

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 

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:

HTTP
1HTTP/1.1 302 Found
2Location: https://relyingparty.com/login?
3  code=SplxlOBeZQQYbYS6WxSbIA
4  &state=af0ifjsldkj

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

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.

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 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
1POST /token HTTP/1.1
2Host: mid.com
3ContentType: application/x-www-form-urlencoded
4Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
5grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Frelyingparty.com%2Flogin

Token Response 

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

HTTP
1HTTP/1.1 200 OK
2ContentType: application/json
3CacheControl: nostore Pragma: nocache
4{
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"
20}

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:

JSON
1{
2  "iss": "[http://mid.com](http://eid.morphotrust.com/)",
3  "sub": "248289761001",
4  "aud": "@!40EA.D454.9D4F.E876!0001!ECE8.BBEF!0008!0068.3E20",
5  "nonce": "39ewiy1zxs",
6  "exp": 1311281970,
7  "iat": 1311280970
8}

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 "mid.com" the endpoint would be: https://mid.com/oxauth/seam/resource/restv1/oxauth/userinfo

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:

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

The following is an example of a complete request:

HTTP
1POST /userinfo HTTP/1.1
2Host: [mid.com](http://eid.morphotrust.com/)
3ContentType: application/x-www-form-urlencoded
4Authorization: Bearer 1962e492-a070-4f8d-bdb1-2f464bea77a1
5access_token=1962e492-a070-4f8d-bdb1-2f464bea77a1

A successful response is returned as:

HTTP
1HTTP/1.1 200 OK
2ContentType: application/json CacheControl: nostore Pragma: nocache
3{
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  "address.country": ""
22}

NOTES:

• In many states the country value is not encoded in the 2D barcode on the license. As such, it is not uncommon for the <address.country> 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 https://openid.net/specs/openid-connect-session-1_0.html#RPLogout.

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.

Example

This example assumes a redirect after the IdP session logout to https://service.relyingparty.com/logged_out.

Shell
1curl -X GET \
2  'https://iam360-idp.idemia.com/oxauth/restv1/end_session?id_token_hint=idtoken_value_here&post_logout_redirect_uri= https%3A%2F%2Fservice.relyingparty.com%2Flogged_out &state=state_string' \
3  -H 'cache-control: no-cache'

Consent 

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:

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.

Consent Request 

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.

Sample Consent Request 

HTTP
1POST http://localhost:8080/api/v1/consent
2POST data:
3{
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  }
17}
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).

Consent Callback 

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

HTTP
1PUT http://localhost:8080/dorsimulator/rest/consent/callback PUT data:
2{
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"
10}
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: