TouchID / Fingerprint (Verification)
This is a technical introduction how you can implement the Enrollment for TouchID by simply following the below steps.
What is TouchID
Touch ID is a fingerprint recognition feature provided by the mobile phone. A user can authenticate to any application on any device using TouchID/Fingerprint on your Authenticator App.
You can integrate it in any app, even your own apps, the user is already using and equip it to an Authenticator.
When is a user able to configure TouchID
| Criteria | Example | Configuration |
|---|---|---|
| Authentication | A user is able to configure any verification method, only if he is authenticated. So you need a valid token. | |
| Allowed Verification Methods | The verification method, the user want to setup, must be activated for your instance. It is a global setup. |
Understanding the Flow and APIs
| API | Description | Link |
|---|---|---|
| Get available verification methods | Tenant methods the user may enroll. | Link to API |
| Enrollment Initiation | Start TouchID enrollment (user token or trackId). | Link to API |
| Enrollment Status | Poll until the authenticator completes setup. | Link to API |
| List configured methods | Each device is a mediums[] item. Use device_id to delete one device. | Link to API |
| Remove one device | DELETE /verification-actions-srv/users/configurations/devices/TOUCHID/{device_id} | Link to API |
| Remove all TouchID devices | DELETE /verification-actions-srv/users/configurations/TOUCHID | Link to API |
Step 1: Allow TouchID in your Instance
Enable the TOUCHID verification method for your instance under Verification Methods (SecureOps).
Step 2: Present Verification Methods
The first page for enrollment should present all verification methods available.
Thereby you can use the below query to retrieve the available methods.
curl 'https://demo.cidaas.de/verification-srv/config/list' \
-H 'Authorization: Bearer eyJhbGciOiJxxx2Og' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
--compressed
The API returns all available methods as array:
[
{
"verificationType": "TOUCHID",
"active":true
},
{
"active": true,
"verificationType": "BACKUPCODE",
},
]
It returns a verificationType which can be used as input variable (path parameter) for the API in Step 3.
Step 3: Initiation of Enrollment
To start the enrollment, a QR Code will be displayed to the user. The QR code
The CURL command to initiate the enrollment will accept touchid as path parameter. Thereby you are defining the method to configure. Based on the token the user will be identified.
curl 'https://domain/verification-actions-srv/setup/{method}/initiation' \
-H 'authority: qc-v3.cidaas.de' \
-H 'accept: application/json, text/plain, */*' \
-H 'accept-language: en-US,en;q=0.9' \
-H 'authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImRiMDxxxH3CCQAZ246TjbEZvqQkNy_CM9YARxW7geGevv2Og' \
-H 'content-type: application/json' \
--data-raw '{"deviceInfo":{"deviceId":"","location":{"lat":"","lon":""}}}' \
--compressed
Using the response you can construct the QR-Code based on the below template.
`otpauth://totp/tenant_name:given_name family_name?t=type&d=given_name family_name&issuer=tenant_name&tk=tenant_key&l=logoURL&sub=sub&cid=client_id&burl=baseURL&eid=exchange_id`;
The response from the api contains exchange_id, sub and authenticator_client_id which is required as input.
{
"exchange_id": {
"exchange_id": "d5edcec1-d306-4cb8-8650-a3eb0330084d",
"expires_at": "2024-01-12T21:12:30.108Z",
},
"authenticator_client_id": "532542d2-c6b8-4921-86b6-bb1da13f941b",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"status_id": "04dca6fd-2cd7-4a9d-9d94-851be71d6344"
}
The final QR Code Link based on the above input, looks like this:
`otpauth://totp/demo:Poca Hontas?t=touchid&d=Poca Hontas&issuer=demo.cidaas.de&tk=cidaas-demo-prod&sub=da65eb32-d460-4355-8b94-ee061896712f&cid=532542d2-c6b8-4921-86b6-bb1da13f941b&burl=https://demo.cidaas.de&eid=d5edcec1-d306-4cb8-8650-a3eb0330084d`;
It returns a exchange_id which can be used as input variable (path parameter) for the API in Step 4.
Step 4: Check of Enrollment Status
Now, we are waiting for the users action, and the user performing a TouchID on his phone. This waiting states requires a polling. The recommended time interval is 4 seconds.
curl 'https://demo.cidaas.de/verification-srv/verificationstatus/04dca6fd-2cd7-4a9d-9d94-851be71d6344' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpxxQEZvqQkNy_CM9YARxW7geGevv2Og' \
´ -H 'content-type: application/json' \
--compressed
| 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 |
The API returns a status which can be
| State | Description |
|---|---|
INITIATED | The initiated status will show up as long as you are showing the QR Code. When the QR Code was scanned you should change the UI, so that it is clear there is no further action required |
SCANNED | After the user scanned the code, the state will change to SCANNED |
ENROLLED | The ENROLLED state will show as soon as the user successfully completed the enrollment on the authenticator app. |
{
"status": "INITIATED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID",
}
{
"status": "SCANNED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID"
}
```json
{
"status": "ENROLLED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID",
"ph_id": "79e52278-80f4-488f-8adc-5ef3d4c4869d",
"device_id": "dd7e81392ff7bbd3"
}
It returns a device_id and ph_id when status is ENROLLED. This is required for the user-friendly name Step 5.
Step 5: Complete Enrollment & Add user-friendly Name
The final step is to allow the user to set a user-friendly name.
curl 'https://demo.cidaas.de/verification-srv/v2/setup/users/configured/update/devicename' \
-X 'PUT' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer eyJhbGciOiJSUxxfdKh5Za4y-b2nU65v4egHW6RQ' \
-H 'content-type: application/json' \
--data-raw '{"device_id":"dd7e81392ff7bbd3","friendly_name":"My Loved Phone","id":"da552e03-cfc2-4461-92d3-f05b5e488a6c","ph_id":"79e52278-80f4-488f-8adc-5ef3d4c4869d","sub":"da65eb32-d460-4355-8b94-ee061896712f"}' \
--compressed
Developer Perspective
This Implementation Guide is based on the default demo pages which is using a angular framework based on Typescript. It can be implemented in any other programming language as well.
As a first step you will be redirected to the login&security page. This Section starts to show the verification methods:
Step 1: Present Verification Methods
The first page for enrollment should present all verification methods available.
Thereby you can use the below query to retrieve the available methods.
getMFAList(): Observable<IEnabledMFAResponse> {
return this.http.get<IEnabledMFAResponse>(this.baseUrl+ '/verification-srv/config/list', ({headers: URLHelper.getHeaders()}));
}
The API returns all available methods as array:
[
{
"verificationType": "TOUCHID",
"active":true
},
{
"active": true,
"verificationType": "BACKUPCODE",
},
]
It returns a verificationType which can be used as input variable (path parameter) for the API in Step 3.
Step 3: Initiation of Enrollment
To start the enrollment, a QR Code will be displayed to the user. The QR code
The CURL command to initiate the enrollment will accept touchid as path parameter. Thereby you are defining the method to configure. Based on the token the user will be identified.
const payload: ICommonPayload = {
deviceInfo: {
deviceId: this.fingerPrint,
location: this.location
}
};
let mfaData:IMFAData = setupVerification(type: string, payload: ICommonPayload): Observable<ICommonMFAResponse> {
return this.http.post<ICommonMFAResponse>(this.baseUrl + '/verification-srv/v2/setup/initiate/touchid', payload, ({headers: URLHelper.getHeaders()}));
}
Using the response you can construct the QR-Code based on the below template.
`otpauth://totp/tenant_name:given_name family_name?t=type&d=given_name family_name&issuer=tenant_name&tk=tenant_key&l=logoURL&sub=sub&cid=client_id&burl=baseURL&eid=exchange_id`;
The response from the api contains exchange_id, sub and authenticator_client_id which is required as input.
{
"exchange_id": {
"exchange_id": "d5edcec1-d306-4cb8-8650-a3eb0330084d",
"expires_at": "2024-01-12T21:12:30.108Z",
},
"authenticator_client_id": "532542d2-c6b8-4921-86b6-bb1da13f941b",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"status_id": "04dca6fd-2cd7-4a9d-9d94-851be71d6344"
}
The final QR Code Link can be created e.g. using this code snippet:
_constructQRData = (status: IMFAData, tenantInfo: ITenantInfo, type: string): string => {
let url = `otpauth://totp/${tenantInfo.tenant_name ? tenantInfo.tenant_name : '-'}:-?t=${type}&d=-&issuer=${
tenantInfo.tenant_name ? tenantInfo.tenant_name : '-'
}&tk=${tenantInfo.tenant_key ? tenantInfo.tenant_key : '-'}&l=${tenantInfo.logo_uri ? tenantInfo.logo_uri : '-'}&cid=${
status.authenticator_client_id ? status.authenticator_client_id : '-'
}&burl=${tenantInfo.base_url ? tenantInfo.base_url : '-'}&eid=${
status.exchange_id?.exchange_id ? status.exchange_id?.exchange_id : '-'
}`;
return url;
};
It returns a exchange_id which can be used as input variable (path parameter) for the API in Step 4.
Step 4: Check of Enrollment Status
Now, we are waiting for the users action, and the user performing a TouchID on his phone. This waiting states requires a polling. The recommended time interval is 4 seconds.
checkSocketStatus(statusId: string): Observable<ISocketResponse> {
return this.http.post<ISocketResponse>(this.baseUrl + 'verification-srv/verificationstatus/' + statusId, {}, ({headers: URLHelper.getHeaders()}));
}
| 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 |
The API returns a status which can be
| State | Description |
|---|---|
INITIATED | The initiated status will show up as long as you are showing the QR Code. When the QR Code was scanned you should change the UI, so that it is clear there is no further action required |
SCANNED | After the user scanned the code, the state will change to SCANNED |
ENROLLED | The ENROLLED state will show as soon as the user successfully completed the enrollment on the authenticator app. |
{
"status": "INITIATED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID",
}
{
"status": "SCANNED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID"
}
```json
{
"status": "ENROLLED",
"id": "da552e03-cfc2-4461-92d3-f05b5e488a6c",
"sub": "da65eb32-d460-4355-8b94-ee061896712f",
"type": "TOUCHID",
"ph_id": "79e52278-80f4-488f-8adc-5ef3d4c4869d",
"device_id": "dd7e81392ff7bbd3"
}
It returns a device_id and ph_id when status is ENROLLED. This is required for the user-friendly name Step 5.
Step 5: Complete Enrollment & Add user-friendly Name
The final step is to allow the user to set a user-friendly name.
let payload:IDeviceNamePayload = {
"device_id" : data.device_id,
"friendly_name" : data.friendly_name,
"id": data.id,
"ph_id": data.ph_id,
"sub" : data.sub
}
...
updateDeviceName(payload: IDeviceNamePayload): Observable<any> {
return this.http.put(this.baseUrl + '/verification-srv/v2/setup/users/configured/update/devicename', payload, ({ headers: URLHelper.getHeaders()}));
}
curl 'https://demo.cidaas.de/verification-srv/v2/setup/users/configured/update/devicename' \
-X 'PUT' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer eyJhbGciOiJSUxxfdKh5Za4y-b2nU65v4egHW6RQ' \
-H 'content-type: application/json' \
--data-raw '{"device_id":"dd7e81392ff7bbd3","friendly_name":"My Loved Phone","id":"da552e03-cfc2-4461-92d3-f05b5e488a6c","ph_id":"79e52278-80f4-488f-8adc-5ef3d4c4869d","sub":"da65eb32-d460-4355-8b94-ee061896712f"}' \
--compressed
Need Support?
Please contact us directly on our support page