Re-Authentication

Table of Contents

1. Introduction

This is a general walk-through for getting start iAM Smart APIs development of Re-Authentication.

Developers of Online Service adopting iAM Smart may find this guide useful when designing and developing application flows for Re-Authentication adopting “iAM Smart” functions.

In this guide we will provide guides on:

  • Setting up your iAM Smart development environment 
  • Request Re-authentication
  • Callback to Receive Re-authentication Result

2. User Journey

3. Flow

Please find below the sequence diagram for the whole re-authentication:

4. Request re-authentication

4.1 Click “Re-authentication by iAM Smart”

UI Display

Online service shall display the following buttons:

Re-authentication
UsageThe button for user to initiate the re-authentication flow.
Traditional Chinese智方便認證
Simplified Chinese智方便认证
EnglishAuthentication with iAM Smart
Sample Button for Re-authentication
Traditional Chinese
Simplified Chinese
English
Open “iAM Smart”
UsageThe button for user open specific authorisation page in “iAM Smart” mobile app.
Traditional Chinese開啟智方便
Simplified Chinese开启智方便
EnglishOpen iAM Smart
Sample Button for Open iAM Smart
Traditional Chinese
Simplified Chinese
English
Tip
Please note that the request shall be initiated after the user clicked the “Authentication with iAM Smart” button.

Online service is required to add a link / button, “More info” or “了解更多” in the initiation page. The link / button shall be linked to the “iAM Smart” thematic webpage based on language preference of user.  The initiation page refers to the page that initiates the “iAM Smart” service, which user clicks the “iAM Smart” button to initiate the interaction with “iAM Smart” mobile application.

LanguageLink
English https://www.iamsmart.gov.hk/en/
Traditional Chinese https://www.iamsmart.gov.hk/tc/
Simplified Chinesehttps://www.iamsmart.gov.hk/sc/

4.2 Composing Request Body

Online Service Website/app initiates Re-authentication request to Online Service Server with browser’s user agent value (for use as value for request parameter “source”);

Online Service Server initiates Re-authentication request to invoke iAM Smart API with the “businessID” of this request, accessToken, Tokenised ID, etc. The request parameter “source” will be the browser’s user agent value. 

Parameter

Type

Presence

Description

businessID

String

Required

businessID is a unique identifier for Online Service to differentiate different request. It should be ASCII string with length less than or equal to 36 chars.

accessToken

String

Required

accessToken value

openID

String

Required

Tokenised ID value

source

String

Required

Request initiator. The supported source values can be found in Appendix B of this specification.

redirectURI

String

Required

callback URI.

state

String

Optional

If state parameter is presented in the request message, the same state value will be returned to Online Service during callback. It is used to prevent the CSRF attack. The value of state is defined by Online Service and it should be a secure random string of any length less than or equal to 36 (UUID string length). Only ASCII letters, numbers, underscore and hyphen are accepted.

Your request body should look something like this:

				
					https://<iAM_Smart_domain>/api/v1/account/stepup/initiateRequest 
// Request Headers
clientID: "edae2e2529ff46228af1e4d18c8405d1"
signatureMethod: "HmacSHA256"
signature: "5X42Y1B7MEd8Mm%2BonwjiQz9VCZkkrntADskXsYntavU%3D"
timestamp: 1557048906183
nonce: "e893647dc4204eb9b7b8eddd527b687c"
// Request Body
{
 "businessID": "bbb8aae57c104cda40c93843ad5e6db8",
"accessToken": "xxxa42e76bf4cb0846a68e6d83d6096",
"openID": "liR14%2BvX%2F5hSum5uf4ERczu0KcDnIJA5BM7FoM1ag9c%3D",
"source": "Android_Chrome",
"redirectURI": "https://<rp_domain>/<rp_context>/<call_back_endpoint>",
"state": "eddd527b6"
}
				
			

As an additional layer of data encryption will be applied to all APIs POST request, please follow 4.5.1.1(Login with iAM Smart) to construct the encrypted request header and request body.

Upon success you should receive the encrypted response.

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
"content":"AAAADLzOxAK6KCtIQgl/BJRVECazUaNiaf13rfcGNApA3K0BI0qZkB5pMWAjcTF0z0PLOnsCyxCtVUytAbA/cm2U5W83FrRXvtZZ74SrCWY4cQiAlq38TLSeOY9B418Tc5dUr1JnbCVeHe8HNrEY81QyI3r7JMZfXGaWgRoz0os8C7zbzty88vPGPSmBE7WqZF5I84IJ7wzwpRs+ifz9DfpFqWzj55mftTHQERWDhcKRALgdZECoFCqtmNhRFERxAm+MrIkypZG/JAdcho0cLyIGTkw7KLqKT0/NmQgQ3vsi6IxGOF4u8gPfLHfRkLopZkU7sXXHNC5hVtEmGXz0zrp+Pq9diKIX6MyrAtwjhIxxKu5iI9MO7XB272hpeonpJYWA0dvh0F882tjNnN6oRJrQ1ZxPXfeA"
				
			

4.3 Decryption

Please refer to section 4.5.2.1 for decryption of the content data, and you should get the following result:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
    "authByQR": true
  }
}
				
			

5. Open iAM Smart Mobile App for Getting Context

When iAM Smart Mobile App is opened, Online Service Website should keep synchronizing with Online Service for re-authentication result, such as polling.

Online Service Website/app invokes iAM Smart Mobile App using URL Scheme with “ticketID” (set<Context> as “re-auth” in URL Scheme). 

5.1 Construct the URL Scheme

ParameterTypePresenceDescription
ticketIDStringRequiredTicketID is a unique identifier provided by iAM Smart Core System, Online Service retrieve ticketID while requesting the context (Profile / Signing / Form Filling / Re-authentication). It is ASCII string with length less than or equal 36 chars. 
sourceString

Required

(Conditional)

This parameter is required only in anonymous form filling or anonymous signing workflows. 

Request initiator (App_Scheme, App_Link).

The detail of supported source values can be found in Appendex B of this specification. 

redirectURIString

Required

(Conditional)

callback redirect URI. This parameter is required only in anonymous form filling or anonymous signing workflows and its value should be URL encoded.
stateString

Required

(Conditional)

If state parameter is presented in the request message, the same state value will be returned to Online Service during callback. It is used to prevent the CSRF attack. The value of state is defined by Online Service and it should be a secure random string of any length less than or equal to 36 (UUID string length). Only ASCII letters, numbers, underscore and hyphen are accepted.

Your request scheme should be something as following:

				
					hk.gov.ogcio://re-auth
?ticketID=bbb8aae57c104cda40c93843ad5e6db8
				
			

6. Callback to Receive Re-authentication result

After iAM Smart user logs in iAM Smart Mobile App, reviews the Re-authentication authorisation request (e.g. continue or reject the request) and authorizes the request. iAM Smart System invokes Online Service callback API to return the result with “businessID” of the Re-authentication request to Online Service server. 

6.1 Callback Parameters

ParameterTypePresenceDescription
businessIDStringRequiredbusinessID is a unique identifier for Online Service to differentiate different request, Online Service can use the businessID to relate the callback message with the original request. 
stateStringOptionalIf state parameter is present in the request message, the same state value will be returned. It is used to prevent the CSRF attack. The value of state is defined by Online Service and it should be a secure random value.
isPassedStringRequiredRe-authentication result. true – same person, otherwise false.

Upon success you should receive the encrypted response:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
    "businessID": "3e47be25-66a6-43fb-89f6-7e2dd138aff8",
"state": "unesidkd",
"isPassed": true
  }
}
				
			

6.2 Decryption

Please refer to section 4.5.2.1 for decryption of the content data, and you should get the following result:

				
					{
  "txID": "<T=938ffb193b4b4370b6c2584372c6a588>",
  "code": "D00000",
  "message": "SUCCESS",
  "content": {
    "businessID": "3e47be25-66a6-43fb-89f6-7e2dd138aff8",
"state": "unesidkd",
"isPassed": true
  }
}
				
			

Online Service Server processes and matches the result using the “businessID” and shows the result in the corresponding Online Service Website/app.

PHP Code Snippets Powered By : XYZScripts.com