Push Notification Authentication using Firebase and MAS

In this tutorial we will configure DIGIPASS Gateway and Mobile Authenticator Studio to be able to perform push notification authentications. Here we assume you have configured MAS, USW, DP Gateway and OAS.

We will extend the MAS configuration to include the end points for updating the push notification registration identifier and configuring firebase for our project.

Configuring Firebase for push notifications

You will need to login to the Firebase console and start a new project. Once created we will want to setup cloud messaging, to do this we have to find Cloud Messaging in the left hand menu drawer:

Once we click on Cloud Messaging we will be redirected to a page with a header that will ask us to add an app. Click on android to continue.
This will prompt a form where we will have to enter our application package name (the one we use during the build process). Make sure that your package starts with com.
Here we can download the google-services.json and move it to MAS_X.XX.X\Tools\Customization Tool\input\conf.

Configuring DIGIPASS Gateway for push notifications

In Firebase we will have to generate a service account in order to retrieve the administrative json configuration file which will be used by the server to send push notifications.

In the project we can create service accounts under the Service Accounts tab by clicking on the Generate new private key button. This will prompt a file for download.

Once downloaded we have to move it to our DIGIPASS Gateway server and place it in a directory where the DIGIPASS Gateway has permissions to access the file. In this example we will copy it to the installation directory and change the owner of the file (I renamed the downloaded file to firebase-adminsdk.json):

root@ubuntu:/home/administrator# cp firebase-adminsdk.json /opt/onespan/dpgateway/firebase-adminsdk.json
root@ubuntu:/home/administrator# chown onespan-dpgateway:onespan /opt/onespan/dpgateway/firebase-adminsdk.json

Now we have to configure DIGIPASS Gateway to use this file:

root@ubuntu:/home/administrator# cd /opt/onespan/dpgateway/
root@ubuntu:/opt/onespan/dpgateway# ./admintool type dpgateway push-notification android-fcm /opt/onespan/dpgateway/firebase-adminsdk.json
OneSpan Web Configuration Tool
Copyright (C) 2020 OneSpan. All rights reserved.

The push notification settings for Android were updated.

We will also want to generate a front-end and backend API key:

root@ubuntu:/opt/onespan/dpgateway# ./admintool type dpgateway api-key-frontend generate

OneSpan Web Configuration Tool
Copyright (C) 2020 OneSpan. All rights reserved.

DIGIPASS Gateway front-end API key was set to <7D44F79B4EA391058D164D9C9D766E08BDA11CCF1995FC5C6EA28CB269E36AFD>.
root@ubuntu:/opt/onespan/dpgateway# ./admintool type dpgateway api-key-backend generate

OneSpan Web Configuration Tool
Copyright (C) 2020 OneSpan. All rights reserved.

DIGIPASS Gateway back-end API key was set to <9BEC7D390D7B5D2A16E6D1489FEC256062680085F1DB33F6974C7680F5C0CBCE>.

Remember to restart the service, otherwise our changes do not take effect!

service onespan-dpgateway restart

Configuring MAS for push notifications

After moving google-services.json to MAS_X.XX.X\Tools\Customization Tool\input\conf we will open DIGIPASS.xml and add the Notifications section as follows:

<Notifications>
	<NotificationRegistration>
		<URL method="POST" contentType="json"  value="https://{{server_url}}:{{port}}/rest/v2/notification/push/updateNotificationID">
			<PayloadParameter key="userID" value="%_UserIdentifier_%"/>
			<PayloadParameter key="domain" value="%_Domain_%"/>
			<PayloadParameter key="digipassInstanceID" value="%_SerialNumber_%-%_SequenceNumber_%"/>
			<PayloadParameter key="encryptedNotificationID" value="%_VascoNotificationIdentifier_%"/>
		</URL>
	</NotificationRegistration>

	<NotificationsList>

		<!-- Secure channel Action with push and login -->
		<SecureChannelAction id="03">
			<SecureChannelDetails>
				<URL method="POST" contentType="json" value="https://{{server_url}}:{{port}}/rest/v2/authentication/push/getPreparedSecureChallenge">
					<PayloadParameter key="serialNumber" value="%_SerialNumber_%-%_SequenceNumber_%"/>
					<PayloadParameter key="challengeKey" value="%_Challenge_%"/>
				</URL>
			</SecureChannelDetails>
			<SecureChannelValidation>
				<URL method="POST" contentType="json" value="https://{{server_url}}:{{port}}/rest/v2/authentication/push/authUser">
					<PayloadParameter key="userID" value="%_UserIdentifier_%"/>
					<PayloadParameter key="domain" value="%_Domain_%"/>
					<PayloadParameter key="challengeKey" value="%_Challenge_%"/>
					<PayloadParameter key="signature" value="%_OTP_%"/>
				</URL>
			</SecureChannelValidation>

			<SecureChannelRejection>
				<URL method="POST" contentType="json" value="https://{{server_url}}:{{port}}/rest/v2/authentication/push/cancelAuthUser">
					<PayloadParameter key="serialNumber" value="%_SerialNumber_%-%_SequenceNumber_%"/>
					<PayloadParameter key="challengeKey" value="%_Challenge_%"/>
				</URL>
			</SecureChannelRejection>
			<View title="Login Request">
				<Labels>
					<Label id="ConfirmationMessage" value="Do you want to login to ‘%_ServiceName_%’ as %_UserIdentifier_%?" class="infoLabel"/>
					<Label id="DetailsWaitMessage" value="Fetching Login request" />
					<Label id="RejectionWaitMessage" value="Rejecting login..." />
					<Label id="ValidationWaitMessage" value="Accepting login..." />
				</Labels>
				<Buttons>
					<Button id="Accept" value="Accept"/>
					<Button id="Deny" value="Reject"/>
				</Buttons>
			</View>
		</SecureChannelAction>
	</NotificationsList>
</Notifications>

We will also have to add a gatewayAPIKey attribute to the Functional tag, the key will be the front-end API key we generated earlier:

<Functional authorizeCopyPaste="true" passwordConfirmation="true" passwordFormat="any" closeInBackground="false" restoreDataFieldsOnResume="false" reactivateOnSVUpdate="false" allowPasswordFallback="true" gatewayAPIKey="7D44F79B4EA391058D164D9C9D766E08BDA11CCF1995FC5C6EA28CB269E36AFD">
    ....
</Functional>

Now we need to build the application using the package name we defined on Firebase (without com.).

Configuring MDC to use DP Gateway

Now we have to go to MDC and configure the push notification service. We will set the url and port explicitly in the configuration GUI:

https://{{dpgateway_host}}/rest/v2/notification/push/sendNotification

Configure OAS

Start off by going to the Web Administration Service and selecting Servers->Global Configuration. Then go to the Push Notifications tab and enter the API key that we generated on the DIGIPASS Gateway:

Finally we will create a policy (which inherits from Identikey Local Authentication) and client component.

In the new policy we will configure the Push Notification tab to use the application id we configured in Firebase:

For the next test, we set the request method to keyword only so that we only need to enter push to try and trigger the push notification.

Testing

Now we will activate the token using the User Self-Management Websites and after activation will use the Manage->Login Test page. We will enter the user id and keyword in the password field (we defined the keyword as push).

If everything went well, you should have received a push notification:

Clicking on the push notification will open the application.
We will then be able to accept or decline.
Upon accepting we will see that the authentication on USW succeeded.

Conclusion

By building upon the online activation procedure we managed to enable push notification authentication in MAS.

Show Comments