Push (Authentication)

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

What is Smart PUSH?

The Smart PUSH is a verification method, where the user receives 4 different numbers on the mobile App and they need to select the number which is displayed on the web.

It is one of the multiple different authentication methods.

When is a user able to use PUSH authentication?

Criteria	Example	Configuration
User Verification Setup	The user has to log in to the portal and can enroll the `PUSH` using either the cidaas App or any other custom Authenticator App
Allowed Verification Methods	An app setting to configure `PUSH` 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 `PUSH` 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 `PUSH` 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 PUSH in the App settings

In the Admin portal, you need to make the PUSH 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 -> PUSH

app-otp

Step 2: Rendering the user verification methods

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

Implementation using Javascript SDK

To authenticate the user via PUSH 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 PUSH authentication

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

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

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

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

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 selects any number on the mobile App for the PUSH authentication, 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 selected push number
authenticateEntity.pass_code = "55"

// verification type
pushRejectEntity.verificationType = "PUSH"

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 Smart PUSH?​

When is a user able to use PUSH authentication?​

Understanding the Flow and APIs​

Step 1: Allow PUSH 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 PUSH 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​