Adding push notifications

This document demonstrates how to send a push notification to a user's authentication device to include an extra layer of validation before permitting the user to, for example, access sensitive personal data or change payment methods.

How does it work?

For this scenario, we assume that the user has enrolled an authentication device as part of the registration flow and they are logged in to your website.

The process for accessing a sensitive feature that is secured by a push notification can be seen below.

1. The user accesses a sensitive feature.
2. You send a push notification and ask the user to confirm.
3. The user receives the notification and confirms.
4. You wait for the user to confirm.
5. You redirect the user to the requested page.

The process for sending the push notification to a specific device adds another step.

1. The user accesses a sensitive feature.
2. You ask the user which authentication device they want to use.
3. You send a push notification and ask the user to confirm.
4. The user receives the notification and confirms.
5. You wait for the user to confirm.
6. You redirect the user to the requested page.

Which parts of the API do you need?

If you want to send a push notification to a specific device you need the following endpoints:

• GET /omi/users/{userId}/devices to retrieve a list of the user's devices.
• POST /omi/push/user/{userId}/device/{deviceId} to send a push notification to a specific device.
• GET /omi/push/confirmation to check if the user has confirmed the push notification.

Example implementation

The following is an example of adding push notification to an access flow.

Obtain an access token

To call the IDAAS-core endpoints, you need to obtain an access token. The application requires an access token to authenticate to the OneWelcome Identity Platform. We recommend using the OAuth2 client credentials flow to generate your access token.

You must specify the following scopes for the access token:

• credential:omi:devices:get
• credential:omi:push-notification:device:post
• credential:omi:push-notification:status:get

Send a push notification to a device

To obtain a list of registered authentication devices, you can use the /omi/push/user/{userId}/device/{deviceId} endpoint. In the event that the user has multiple registered devices, you can provide a list of their authentication devices and have them choose one.

When you have identified the device to target, you can compose the push notification and send it using the /omi/push/user/{userId}/device/{deviceId} endpoint. You will need to provide the content of the push notification as the message value.

• Message represents the message that will be displayed on the push notification on the user’s device.

With that information and the access token you obtained earlier, you can send the push notification.

Check for a response

You can view if the user has approved the push notification you sent them using the /omi/push/confirmation endpoint. We recommend calling this API at fixed time intervals, from two to three seconds, in order to not overload the server with unnecessary requests.

When checking the status, you must provide the nonce that was generated when sending the push notification to identify the device and user you are validating.

When you have received confirmation that the user has approved the push notification, you can redirect the user to the requested material.