TrustX Push Notifications

A TrustX push notification will send a push notification to an Identity Store (IDS) User with a registered Appkey on their device. When the User accepts the push notification, a child Process Instance can be started. The parent Process Instance (The Process Instance that initiated the push notification) will be paused using the 'Wait On Push Notification" activity until the child Process Instance is completed.

This flow can be summarized as follows:

1. Customer requests a push notification. This will happen either directly via an API on the Identity Store server, or indirectly via a TrustX Activity from a process instance. The request contains the details of the process definition & version or process definition tag, and process token parameters.
2. A limited duration Process Token is created for the push notification on the Identity Store server and provide the TrustX redirect URL as the payload for the push notification to all devices or a preferred device.
3. The user accepts the push notification on the device which redirects to the TrustX URL for the push notification process instance.
4. The 'Wait On Push Notification' activity in the parent Process Instance will react to these statuses.

This guide will demonstrate how to configure a standard TrustX push notification flow using the Process Designer and the TrustX API.

Prerequisites

Before configuring a TrustX push notification flow, the following prerequisites must be satisfied.

1. An Appkey Identity Store must already exist. See Managing Identity Stores for more information.
2. A User must be created in the Identity Store. See Managing Users for more information.
3. An Appkey policy must be created and the Identity Store User must have a registered Appkey registered to their device. See Managing Policies and Appkey Device Registration

Configure Push Notification Policy

A push notification policy is a form of Appkey Identity Store policy that can be configured for Apple Push Notifications (APN) for iOS applications or Firebase Cloud Messaging (FCM) for Android applications.

To create a new policy, follow the steps outlined below.

1. Select the Policies page found under the Identity Stores tab in the left-side navigation menu in the Backoffice application.

2. Using the 'Select a Store' dropdown menu, select an Appkey Identity Store. If an Identity Store that does not support Appkeys is selected, the option to create a push notification policy will be greyed out.

3. Click the blue 'New Policy Configuration' button at the top-right of the screen. A pop-up modal will appear with a list of available policy types. Select the 'Push Notification' policy.

Push Notification Policy Configuration Options

This section will describe the various configuration options available when defining a push notification policy.

APN Configuration

To configure iOS push notifications, you’ll need four pieces of information from your Apple Developer account.

1. Application Bundle ID

   1. Go to https://developer.apple.com/account/resources/identifiers/list.
   2. Under Identifiers, find your app.
   3. Copy the Bundle ID (e.g., com.yourcompany.yourapp).

2. Team ID

   1. Log in to https://developer.apple.com/account/.
   2. Click [Account Name] → Membership Details. in the top-right corner.
   3. Copy the Team ID listed there.

3. Key ID

   1. In your Apple Developer account, navigate to Certificates, Identifiers & Profiles → Keys
   2. Create a new key (or select an existing one) and enable Apple Push Notifications service (APNs).
   3. After creating the key, copy the Key ID.

4. Token Signing Key

   1. When you create the key, download the .p8 file immediately (Apple only allows one download).
   2. Open the .p8 file in a text editor.
   3. Copy the entire content (including -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----) and paste it into the Token Signing Key field.

FCM Configuration

To configure Android push notifications, you’ll need two pieces of information from your Firebase project.

1. FCM URL

   1. Go to https://console.firebase.google.com/.
   2. Select your project.
   3. Navigate to Project Settings → Cloud Messaging.
   4. Copy the FCM endpoint URL (usually https://fcm.googleapis.com/fcm/send).
   5. Paste it into the FCM URL field.

2. Google Application Credentials

   1. In the same Cloud Messaging section, click Manage Service Accounts or go to https://console.cloud.google.com/.
   2. Create a Service Account for your Firebase project if one does not exist.
   3. Generate a JSON key for the service account.
   4. Open the downloaded .json file in a text editor.
   5. Copy the entire JSON content and paste it into the Google Application Credentials field.

Configure the Process Definition

This section will describe the steps necessary for configuring a standard Process Definition that integrates a TrustX push notification flow.

A typical Process Definition will follow the structure:

1. Get an IDS User.
2. Initiate a TrustX push notification.
3. Wait for the child Process Instance to complete.
4. Make a decision.

The Process Definition outlined above will be implemented in this section of the guide.

Create a New Process Definition

1. Create a new Process Definition by navigating to the Process Definitions page found in the left-side navigation bar of the Backoffice application.
2. On the top-right of the Process Definition page, click the 'New Process Definition' button.
3. Create a new Process Definition by clicking the 'New Process Definition' option.

Configure Process Definition

1. Add a 'Start' event at the beginning of the Process Designer.
2. Connect a 'Get User' activity to the 'Start' event. This will be used to retrieve information about the the Identity Store User who will be sent a push notification.

3. The 'Get User' activity supports the following input parameters.

4. Add a 'TrustX Push Notification' activity to the Process Designer and connect it to the 'Get User' activity using the global connect tool.

5. The 'TrustX Push Notification' activity supports the following activities.

6. The activity also includes the following error boundary events.

7. Set the Process Definition Name and version to the one that will be initiated when the push notification is selected.
8. The 'TrustX Push Notification' includes two output parameters.

It is also possible to send a TrustX push notification via API using the example query:

Permissions: TNT#{tenant}#IdentityStore:sendPushNotification

Example:

POST https://{{tenant}}.{{region}}.trustx.com/api/identity-store/stores/{{storeName}}/users/{{userExtId}}/pushNotifications/relyingParties/{{rpId}}/ext

Content-Type: application/json

Authorization: Bearer {{token}}

{

  "type": "TRUSTX",

  "ttlSeconds": 480,

  "content": {

    "title": "Authenticate purchase",

    "message": "You have made a purchase which requires authentication"

  },

  "trustXPushRequestParams": {

    "parentTrustXProcess": {

      "processDefnId": "Q3ARG7MUPBQUCK6WZH4AJAVTTI",

      "processDefnName": "regAuthCustomPage294",

      "processDefnVersion": 3,

      "processInstanceId": "PK243NGCII57EQP4CIO3KL7H2I"

    },

    "childTrustXProcess": {

      "processDefnName": "regAuthCustomPage294",

      "processDefnVersion": 3,

      "monitorStatus": true

    }

  }

}

Response:

{

 "trustXPushResponseParams": {

  "redirectUrl": "{string}",

  "pollingUrl": "{string}"

 }

}

Note that the response will including a pollingUrl which can be used to poll the status of the push notification.

9. After the 'TrustX Push Notification', add a 'Wait on Push notification' activity and connect them using the global connect tool. This activity will poll the server for a response from the child Process Instance that is initiated when the user taps the push notification.

10. The 'Wait on Push Notification' activity supports the following input parameters.

11. The activity also includes the following error boundary events.

12. Add a 'Simple Decider' to the Process Definition and connect each of the boundary events to the activity. This activity will determine the final outcome of the Process Instance.

13. Once the Process Definition has been configured, click the 'Save & Deploy' button.

Test and View Results

To test the Process Definition, create a new Process Token by navigating to the Process Definitions > Process Tokens page in the Backoffice application.

1. On the Process Tokens landing page, click the 'New Process Token' button.
2. A popup modal will appear where details of the Process Token can be entered.
3. Once the push notification is sent, a wait screen with be presented to the user in the Trust Web application.

Viewing Push Notifications Per User

Active push notifications associated with an IDS User can be viewed from the Users page in the Backoffice.

1. From the Backoffice application, navigate to Identity Store > Users.

2. Using the filter options available, chose the Identity Store and optional ID to find the desired IDS User.
3. Activity Push Notifications will be listed under the Active Push Notifications section.

4. This section will include the following information.

5. Selecting the magnifying glass under the 'Actions' column will expand to provide more details on the push notification.

Push Notification Details

The Push Notification Details page displays a list of details relating to a specific push notification.

Included in this page is the following information.

Delivery Information

This section presents information regarding the delivery of the push notification.

Information provided is described as follows: