TOUCHID (Authentication)

This is a technical guide on how to implement the TOUCHID authentication by simply following the steps below.

What is TOUCHID?

Touch ID is a fingerprint recognition feature provided by the mobile phone.

It is one of multiple different authentication methods.

When is a user able to use TOUCHID authentication?

Criteria	Example	Configuration
User Verification Setup	The user has to log in to the portal and can enroll the `TOUCHID` using either the cidaas App or any other custom Authenticator App
Allowed Verification Methods	An app setting to configure `TOUCHID` authentication as a login method.

Understanding the Flow and APIs

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods of a user	Link to API
Initiate the authentication	This API is used to initiate the configured authentications, e.g., when a user clicks on the Backup code authentication, it initiates the Backup code authentication.	Link to API
Acknowledge the notification	Acknowledges the notification received in the mobile App when the user initiates the `TOUCHID` authentication request.	-
Allow the authentication	Allow the authentication request which is received in the mobile App when the user acknowledges the notification.	-
Deny the authentication	Deny the authentication request which is received in the mobile App when the user acknowledges the notification.	-
Cancel the authentication	Cancel the authentication request at any point of time either from the web or from the mobile App, when the user initiates the `TOUCHID` authentication.	-
Perform the authentication	After successfully authenticating by entering the Backup code, the enrollment completion will finally enroll the user.	Link to API
Check the authentication status	Check the current status of the authentication request and it has to be polled continuously.	Link to API
Finish up the authentication and continue login	Continue the login process once the authentication is successful.	Link to API

Step 1: Allow TOUCHID in the App settings

In Admin portal, make the TOUCHID verification type an allowed authentication method under App advanced settings

Apps -> App Settings -> Edit -> Advanced Settings -> Authentication -> MFA -> Authentication -> TOUCHID

app-otp

Step 2: Rendering the user verification methods

Before initiating the TOUCHID authentication, perform an Authorization (Authz) call and generate the requestId, then use it in the upcoming API calls.

The first call will be to get the configured verification methods for a user. Based on the response, you provide a selection of verification methods for your user. Below is a demo of how this can look by presenting different verification icons.

Call the configured verification methods of a user. This will filter the user configured verification methods and the app level configuration.

API	Description	Link
Get the configured authentication methods	Displays the configured authentication methods of a user	Link to API

This API requires you to provide the user identifier(could be an email, mobile number or any other identifiers) and the requestId. It returns the type and mediums which can be used to display the device details during authentication in step 3.

Request

curl --location '{{base_url}}/verification-srv/public/graph/user/setup' \
--header 'content-type: application/json' \
--data-raw '{
    "request_id": "df08cabb-4b8c-4181-9f6f-f6948802ebf7",
    "identifier": "[email protected]"
}'

This will return the list of all verification methods available for the user to authenticate.

Response

{
    "success": true,
    "status": 200,
    "data": {
        "configured_list": [
            {
                "type": "TOUCHID",
                "mediums": [
                    {
                        "id": "c0220c65-7c2c-47a8-98a0-8ad1161a0844",
                        "key_name": "Pixel 7(Google, Pixel 7)"
                    }
                ]
            },
            {
                "type": "PUSH",
                "mediums": [
                    {
                        "id": "cd7e9166-99d1-4d36-bc8f-3c8ffb2ad011",
                        "key_name": "Pixel 7(Google, Pixel 7)"
                    }
                ]
            },
            {
                "type": "TOUCHID",
                "mediums": [
                    {
                        "id": "86244c28-6b95-4b2b-922e-4b21e58bf45f",
                        "key_name": "Pixel 7(Google, Pixel 7)"
                    }
                ]
            }
        ]
    }
}

Here, type specifies the verification method, mediums -> id specifies the device id where the notification request has to be sent and mediums -> key_name specifies the friendly name of the configured device.

Step 3: Initiating a TOUCHID authentication

When the user selects TOUCHID in the list of authentication methods, the initiate API needs to be called. The medium_id finally determines to which device the notification has to be sent if a user has configured TOUCHID in multiple devices.

API	Description	Link
Initiate the authentication	Initiates the login authentication process via TOUCHID verification method	Link to API

This API initiates the TOUCHID authentication. It returns an exchange_id, status_id and masked sub which is required as input for the Step 4

Request

curl --location '{{base_url}}/verification-srv/authentication/touchid/initiation' \
--header 'content-type: application/json' \
--data-raw '{
    "usage_type": "PASSWORDLESS_AUTHENTICATION",
    "request_id": "df08cabb-4b8c-4181-9f6f-f6948802ebf7",
    "medium_id": "cd7e9166-99d1-4d36-bc8f-3c8ffb2ad011",
    "email": "[email protected]"
}'

This will return a status_id, exchange_id and masked sub which are unique for this process and the following steps will rely on this being provided.

Response

{
  "success": true,
  "status": 200,
  "data": {
    "exchange_id": {
      "exchange_id": "455fd20d-837d-43a6-a212-a02eeea1a46b",
      "expires_at": "2024-01-10T20:45:51.781Z"
    },
    "medium_text": "[email protected]",
    "sub": "6837c08e-d748-4091-8d8e-a3e24f30e0f8",
    "status_id": "710792ba-32f9-4d2d-8584-fefa3a6d94b8"
  }
}

Step 4: Taking relevant action on the mobile App

Once the user initiates the authentication using TOUCHID, they will receive a notification in the mobile app where they need to take necessary action to proceed further with authentication process.

4.1: Acknowledge the notification

The user needs to acknowledge the notification by clicking on the notification in the mobile App. When the user clicks on the notification, the following API needs to be called from the mobile App.

This API requires you to provide the device_id (mobile device unique id), client_id (client_id of the mobile App), push_id (firebase token) and exchange_id (exchange id received from the notification)

API	Description	Link
Acknowledge the notification	Acknowledges the notification received in the cidaas App when the user initiates the `TOUCHID` authentication request.	-

This API acknowledges the notification received in the mobile App. It returns a new exchange_id and status_id which is required as input for the Step 4.2.

Request

curl --location '{{base_url}}/verification-srv/authentication/touchid/push/acknowledge' \
--header 'Content-Type: application/json' \
--data '{
    "exchange_id": "455fd20d-837d-43a6-a212-a02eeea1a46b",
    "push_id": "cXYndALySjO",
    "device_id": "96d62010e",
    "client_id": "b77de608-6646-4916-8fa9"
}'

This will return a new exchange_id which is unique for this process and the following steps will rely on this being provided.

Response

{
  "success": true,
  "status": 200,
  "data": {
    "exchange_id": {
      "exchange_id": "71dee9c0-5b9d-4ed1-aeaa-b37d721665d6",
      "expires_at": "2024-01-12T08:13:56.052Z"
    },
    "sub": "6837c08e-d748-4091-8d8e-a3e24f30e0f8",
    "status_id": "710792ba-32f9-4d2d-8584-fefa3a6d94b8"
  }
}

4.2: Allow / Deny / Cancel the authentication request

Once the user acknowledges the notification, hey need to either allow or deny the request to confirm that the authentication request is initiated by them. The user can cancel the authentication at any point of time. All these can be achieved by the following APIs

These APIs require you to provide the device_id (mobile device unique id), client_id (client_id of the mobile App), push_id (firebase token) and exchange_id (exchange id received from Step 4.1)

API	Description	Link
Allow the authentication	Allow the authentication request from the mobile App when the user acknowledges the notification.	-
Deny the authentication	Deny the authentication request from the cidaas App when the user acknowledges the notification.	-
Cancel the authentication	Cancel the authentication request at any point of time either from the web or from the mobile App, when the user initiates the `TOUCHID` authentication.	-

These APIs allow/deny/cancel the authentication request from the mobile App. It returns a new exchange_id and status_id which is required as input for the Step 5.

Request

Allow the authentication:

curl --location '{{base_url}}/verification-srv/authentication/touchid/allow' \
--header 'Content-Type: application/json' \
--data '{
    "exchange_id": "71dee9c0-5b9d-4ed1-aeaa-b37d721665d6",
    "push_id": "cXYndALySjO",
    "device_id": "96d62010e",
    "client_id": "b77de608-6646-4916-8fa9"
}'

Deny the authentication:

curl --location '{{base_url}}/verification-srv/authentication/touchid/deny' \
--header 'Content-Type: application/json' \
--data '{
    "exchange_id": "71dee9c0-5b9d-4ed1-aeaa-b37d721665d6",
    "push_id": "cXYndALySjO",
    "device_id": "96d62010e",
    "client_id": "b77de608-6646-4916-8fa9"
}'

Cancel the authentication:

curl --location '{{base_url}}/verification-srv/authentication/touchid/cancel' \
--header 'Content-Type: application/json' \
--data '{
    "exchange_id": "71dee9c0-5b9d-4ed1-aeaa-b37d721665d6",
    "push_id": "cXYndALySjO",
    "device_id": "96d62010e",
    "client_id": "b77de608-6646-4916-8fa9"
}'

This will return a new exchange_id which are unique for this process and the following steps will rely on this being provided.

Response

{
  "success": true,
  "status": 200,
  "data": {
    "exchange_id": {
      "exchange_id": "9af1c4a3-619d-4e40-a4e8-ad5ea089cf2e",
      "expires_at": "2024-01-12T08:13:56.052Z"
    },
    "sub": "6837c08e-d748-4091-8d8e-a3e24f30e0f8",
    "status_id": "710792ba-32f9-4d2d-8584-fefa3a6d94b8"
  }
}

Step 5: Perform the authentication from the mobile App

When the user confirms the identity on the mobile App using biometric / fingerprint verification, the following API needs to be called from the mobile App.

API	Description	Link
Perform the authentication	Complete the authentication process using the mobile App on `TOUCHID` authentication method.	Link to API

This API performs the authentication in the mobile App when the user verifies their identity using biometric authentication. It returns a new exchange_id and status_id which is required as input for the Step 7.

Request

curl --location '{{base_url}}/verification-srv/authentication/touchid/verification' \
--header 'Content-Type: application/json' \
--data '{
    "exchange_id": "9af1c4a3-619d-4e40-a4e8-ad5ea089cf2e",
    "push_id": "cXYndALySjO",
    "device_id": "96d62010e",
    "client_id": "b77de608-6646-4916-8fa9",
    "passcode": "RED-000-100-111-1000-1001"
}'

This will return a new exchange_id which are unique for this process and the following steps will rely on this being provided.

Response

{
  "success": true,
  "status": 200,
  "data": {
    "exchange_id": {
      "exchange_id": "dab51b25-2ae9-4bbe-ad5a-6f1d8c554dd5",
      "expires_at": "2024-01-12T08:13:56.052Z"
    },
    "sub": "6837c08e-d748-4091-8d8e-a3e24f30e0f8",
    "status_id": "710792ba-32f9-4d2d-8584-fefa3a6d94b8"
  }
}

Step 6: Checking the authentication status from the web

When the user starts initiating the authentication process, the following API needs to be called continuously to check the current status of the request.

The following status can come in the response, perform any UI action based on the status.

INITIATED
PUSH_ACKNOWLEDGED
ALLOWED
DENIED
CANCELLED
AUTHENTICATED

API	Description	Link
Check the authentication status	Check the current status of the authentication request and it has to be polled continuously.	Link to API

curl --location '{{base_url}}/verification-srv/verificationstatus/{status_id}' \
--header 'content-type: application/json'

Response

{
    "success": true,
    "status": 200,
    "data": {
        "status": "INITIATED",
        "sub": "6837c08e-d748-4091-8d8e-a3e24f30e0f8",
        "type": "TOUCHID"
    }
}

Once the user has successfully completed the authentication, finish the login process by calling the following API. This will redirect when the authentication is successful to the provided redirect_uri including a code or an access_token depending on the OAuth2 Flow used. Link to API

curl --location '{{base_url}}/login-srv/verification/login' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'requestId=df08cabb-4b8c-4181-9f6f-f6948802ebf7' \
--data-urlencode 'verificationType=TOUCHID' \
--data-urlencode 'sub=6837c08e-d748-4091-8d8e-a3e24f30e0f8' \
--data-urlencode 'status_id=710792ba-32f9-4d2d-8584-fefa3a6d94b8' \

API	Description	Link
Continue Login After Passwordless Authentication	Continue the login process once the authentication is successful.	Link to API

Continue the login process by performing the login call. This API will redirect when the authentication was successful to your provided redirect_uri including a code or an access_token depending on the OAuth2 Flow used. Link to API

curl --location '{base_url}/login-srv/verification/login' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'requestId=df08cabb-4b8c-4181-9f6f-f6948802ebf7' \
--data-urlencode 'exchange_id=e8896cfe-8371-4d79-b8d5-ae8f14c5666c' \
--data-urlencode 'verificationType=email' \
--data-urlencode 'sub=b0dd23-1a2d-40eb-9gb-2ba3cc1942b' \
--data-urlencode 'status_id=710792ba-32f9-4d2d-8584-fefa3a6d94b8' \
--data-urlencode 'rememberMe=true' 

API	Description	Link
Finish up the authentication and continue login	Continue the login process once the authentication is successful.	Link to API

Implementation using Javascript SDK

To authenticate the user via TOUCHID using Javascript SDK, follow the below steps

To install the cidaas-sdk please perform the following command

npm install cidaas-javascript-sdk

The import to your webapp will be done by using:

const cidaas = new CidaasSDK.WebAuth(options);

Step 1: Rendering the user verification methods

const mfaList = await this.cidaas.getMFAList({
    email: e.email,
    request_id: this.route.snapshot.queryParams['requestId'],
});

The UI will be rendered based on this response by displaying all configured verification methods.

Step 2: Initiating a TOUCHID authentication

When the user selects TOUCHID in the list of authentication methods, the initiateMFA method needs to be called.

const payload: IInitiateMFAPayload = {};
    
// pushIndex is the index of the type TOUCHID in the list and deviceIndex is the index of the device in the mediums list
const medium_id = mfaList[pushIndex]['mediums'][deviceIndex]['id']; 
    
// usage_type should be PASSWORDLESS_AUTHENTICATION or MULTIFACTOR_AUTHENTICATION or INITIAL_AUTHENTICATION
payload['usage_type'] = 'PASSWORDLESS_AUTHENTICATION';
    
// requestId should come in the login hosted page query param
payload['request_id'] = this.route.snapshot.queryParams['requestId'];

payload['medium_id'] = medium_id;
payload['type'] = this.verificationType;
    
const initResp = await this.cidaas.initiateMFA(payload);

Step 3: Checking the authentication status from the web

When the user starts initiating the authentication process, the getEnrollmentStatus method needs to be called continuously to check the current status of the request.

const currentStatus = this.cidaas.getEnrollmentStatus(initResp.status_id)

Once the user successfully completed the authentication, finish the login process by calling the passwordlessLogin method. This will redirect to the provided redirect_uri including a code or an access_token depending on the OAuth2 flow used.

let options = {
  requestId: this.route.snapshot.queryParams['requestId'],
  verificationType: this.verificationType,
  sub: this.sub,
  status_id: this.status_id
};
    
this.cidaas.passwordlessLogin(options);

Implementation using Android SDK

To authenticate the user via TOUCHID using Android SDK, follow the below steps

To install the cidaas-sdk, refer the document here

The import to your webapp will be done by using:

CidaasVerification cidaas = CidaasVerification.getInstance(getContext())

Step 1: Acknowledge the notification

Once the user initiates the TOUCHID authentication, the notification will be received in the mobile device and they need to acknowledge it using pushAcknowledge method

PushAcknowledgeEntity pushAcknowledgeEntity = new PushAcknowledgeEntity()

// fetch exchange_id from firebase push notification request
pushAcknowledgeEntity.exchange_id = this.exchange_id

// firebase token
pushAcknowledgeEntity.push_id = this.push_id

// device unique id
pushAcknowledgeEntity.device_id = this.device_id

// mobile client id (this can be received during enrolment and save it in the local db)
pushAcknowledgeEntity.client_id = this.client_id

// verification type
pushAcknowledgeEntity.verificationType = "TOUCHID"

cidaas.pushAcknowledge(pushAcknowledgeEntity, new EventResult<PushAcknowledgeResponse>() {
    @Override
    public void success(PushAcknowledgeResponse result) {  }
            
    @Override
    public void failure(WebAuthError error) {}
});

Step 2: Allow or reject the authentication request

Once the user acknowledges the notification, they need to either allow or deny the request using pushAllow or pushReject method

Allow authentication

PushAllowEntity pushAllowEntity = new PushAllowEntity()

// fetch exchange_id from firebase push notification request
pushAllowEntity.exchange_id = this.exchange_id

// firebase token
pushAllowEntity.push_id = this.push_id

// device unique id
pushAllowEntity.device_id = this.device_id

// mobile client id (this can be received during enrolment and save it in the local db)
pushAllowEntity.client_id = this.client_id

// verification type
pushAllowEntity.verificationType = "TOUCHID"

cidaas.pushAllow(pushAllowEntity, new EventResult<PushAllowResponse>() {
    @Override
    public void success(PushAllowResponse result) {  }
            
    @Override
    public void failure(WebAuthError error) {}
});

Reject authentication

PushRejectEntity pushRejectEntity = new PushRejectEntity()

// fetch exchange_id from firebase push notification request
pushRejectEntity.exchange_id = this.exchange_id

// firebase token
pushRejectEntity.push_id = this.push_id

// device unique id
pushRejectEntity.device_id = this.device_id

// mobile client id (this can be received during enrolment and save it in the local db)
pushRejectEntity.client_id = this.client_id

// rejected reason
pushRejectEntity.reason = "Not initiated by me"

// verification type
pushRejectEntity.verificationType = "TOUCHID"

cidaas.pushReject(pushRejectEntity, new EventResult<PushRejectResponse>() {
    @Override
    public void success(PushRejectResponse result) {  }
            
    @Override
    public void failure(WebAuthError error) {}
});

Step 3: Perform the authentication

When the user confirms their identity on the mobile App using biometric verification, authenticate method should be called.

AuthenticateEntity authenticateEntity = new AuthenticateEntity()

// fetch exchange_id from firebase push notification request
authenticateEntity.exchange_id = this.exchange_id

// firebase token
authenticateEntity.push_id = this.push_id

// device unique id
authenticateEntity.device_id = this.device_id

// mobile client id (this can be received during enrolment and save it in the local db)
authenticateEntity.client_id = this.client_id

// verification type
pushRejectEntity.verificationType = "TOUCHID"

cidaas.authenticate(pushRejectEntity, new EventResult<AuthenticateResponse>() {
    @Override
    public void success(AuthenticateResponse result) {  }
            
    @Override
    public void failure(WebAuthError error) {}
});

Need Support?

Please contact us directly on our support page.

What is TOUCHID?​

When is a user able to use TOUCHID authentication?​

Understanding the Flow and APIs​

Step 1: Allow TOUCHID in the App settings​

Step 2: Rendering the user verification methods​

Step 3: Initiating a TOUCHID authentication​

Step 4: Taking relevant action on the mobile App​

4.1: Acknowledge the notification​

4.2: Allow / Deny / Cancel the authentication request​

Step 5: Perform the authentication from the mobile App​

Step 6: Checking the authentication status from the web​

Step 7: Finish up the login process​

Implementation using Javascript SDK​

Step 1: Rendering the user verification methods​

Step 2: Initiating a TOUCHID authentication​

Step 3: Checking the authentication status from the web​

Step 4: Continue the Login Process​

Implementation using Android SDK​

Step 1: Acknowledge the notification​

Step 2: Allow or reject the authentication request​

Step 3: Perform the authentication​

Need Support?​

What is TOUCHID?

When is a user able to use TOUCHID authentication?

Understanding the Flow and APIs

Step 1: Allow TOUCHID in the App settings

Step 2: Rendering the user verification methods

Step 3: Initiating a TOUCHID authentication

Step 4: Taking relevant action on the mobile App

4.1: Acknowledge the notification

4.2: Allow / Deny / Cancel the authentication request

Step 5: Perform the authentication from the mobile App

Step 6: Checking the authentication status from the web

Step 7: Finish up the login process

Implementation using Javascript SDK

Step 1: Rendering the user verification methods

Step 2: Initiating a TOUCHID authentication

Step 3: Checking the authentication status from the web

Step 4: Continue the Login Process

Implementation using Android SDK

Step 1: Acknowledge the notification

Step 2: Allow or reject the authentication request

Step 3: Perform the authentication

Need Support?