Re-Authentication

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
Usage	The button for user to initiate the re-authentication flow.
Traditional Chinese	智方便認證
Simplified Chinese	智方便认证
English	Authentication with iAM Smart
Sample Button for Re-authentication
Traditional Chinese
Simplified Chinese
English

Open “iAM Smart”
Usage	The button for user open specific authorisation page in “iAM Smart” mobile app.
Traditional Chinese	開啟智方便
Simplified Chinese	开启智方便
English	Open 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.

Language	Link
English	https://www.iamsmart.gov.hk/en/
Traditional Chinese	https://www.iamsmart.gov.hk/tc/
Simplified Chinese	https://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

Parameter	Type	Presence	Description
ticketID	String	Required	TicketID 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.
source	String	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.
redirectURI	String	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.
state	String	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

Parameter	Type	Presence	Description
businessID	String	Required	businessID 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.
state	String	Optional	If 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.
isPassed	String	Required	Re-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.

Re-Authentication

Table of Contents