Pattern (Authentication)

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

What is Pattern?

Pattern authentication typically refers to a method of user authentication that involves recognizing and verifying a specific pattern drawn or traced by the user.

It is one of multiple different authentication methods.

When is a user able to use PATTERN authentication?

Criteria	Example	Configuration
User Verification Setup	The user has to log in to the portal and can enroll the `PATTERN` using either the cidaas App or any other custom Authenticator App
Allowed Verification Methods	An app setting to configure `PATTERN` 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 `PATTERN` 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 `PATTERN` 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.	-
Finish up the authentication and continue login	Continue the login process once the authentication is successful.	Link to API

Step 1: Allow PATTERN in the App settings

In the Admin portal, you need to make the PATTERN verification type an allowed authentication method under App advanced settings.

To do that,

You can change your existing application, by navigating to Apps -> App Settings -> Edit -> Advanced Settings -> Authentication -> MFA -> Authentication -> PATTERN

app-otp

Step 2: Rendering the user verification methods

Before initiating the PATTERN 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

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 PATTERN 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 PATTERN authentication

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

const payload: IInitiateMFAPayload = {};
    
// pushIndex is the index of the type PATTERN 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 PATTERN 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 PATTERN 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 = "PATTERN"

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 = "PATTERN"

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 = "PATTERN"

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 draws a pattern on the mobile App, the 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

// user pattern
authenticateEntity.pass_code = "RED-000-100-111-1000-1001"

// verification type
pushRejectEntity.verificationType = "PATTERN"

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

warning

Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].

What is Pattern?​

When is a user able to use PATTERN authentication?​

Understanding the Flow and APIs​

Step 1: Allow PATTERN in the App settings​

Step 2: Rendering the user verification methods​

Implementation using Javascript SDK​

Step 1: Rendering the user verification methods​

Step 2: Initiating a PATTERN 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​