Next Identity Events

Introduction

Terminology

Source: The place in which an event originates.

Target: Place in which the event is sent. This is either a publicly accessible endpoint or a pre-built integration to an external system.

Internal source: An event that originates from the Next Identity platform as a result of a user action. For example, a login or registration.

External source: An event that originates from an external system such as a software integration webhook.

Summary

Next Identity Events is a near-real-time integration service that allows external ‘targets’ to subscribe and receive events based on actions that are occurring. This has many benefits to external systems and downstream apps such as keeping a CRM updated, adding a user to a marketing service, unsubscribing a user from a marketing service, triggering custom emails, programmatically adding or deleting users, etc.

The events being emitted can be from either internal or external sources throughout the user journey. An example of an internal source is a user registration, a user revocation, etc. An example an external source might be an IDP webhook. These sources go through the Event Service in the Next Identity platform where it can then connect to any number of target systems. An example of a target system might be a downstream application or a CRM such as Salesforce.

Since events are asynchronous, when they are triggered they do not disrupt the current workflow. Events are then queued and retried based on the policy set described below.

Sources

Internal Sources

Different stages of the user journey trigger will trigger transactional events that a target system can listen to. These events are powerful ways for external targets to trigger custom emails or perform other custom actions. The core set of transactional events include:

  • Pre-registration
  • Registration
  • Forgot password
  • Resend verification
  • Password updated
  • New device

In the case of registration, pre-registration, forgot password, and resend verification, NI Events can also be configured to send a verification URL along with metadata that will allow the target to hook on and send custom emails. For the password updated event, only the first name and email is needed. And for the new device event, the first name, email, and device information will be needed. In either of those cases, the target will need to reach back to Next Identity to retrieve the scopes and claims that are needed.

Triggering a Custom Email

For pre-registration, registration, resend verification, and forgot password, a unique link is required to allow the target system to verify the authorization code either through an API integration or will be pointed at the hosted screens. Therefore the event will contain all of the relevant information to construct a link or one-time password (OTP). The information contained in the event is:

"path": "/verify", //some path based on the function that was called
"app_url": "https://someurl.com", //where the user will be taken
"client_id": "c8462jyq9dnupu2q4j7sfjzvn6c87j92",
"email_address": "[email protected]",
"first_name": "Jane",
"redirect_uri": "https://localhost.com",
"locale": "en-US",
"code": "abcdefg123456" //authorization code

The sender is responsible for preserving the state parameter.

In the case of resend verification and forgot password, the first name will need to be obtained by reaching into the user record.

Password Updated

When a password is updated either through the change password flow on the profile or through the forgot password flow, a password updated event will trigger along with the user’s name and email.

New Device

When a new device is detected, the system will trigger an event along with the user’s first name, email, and device information (device, date/time, and location). Here is an example:

`Device: iOS 16.0 (Chrome Mobile iOS 105.0)/AppleiPhone`

`Date and time: 2022-09-27 21:11:06 (America/Los_Angeles)`

`Location: Portland, Oregon, US`

Sending PII

Some of the event contain PII and therefore it will need to be an authenticated API call. So the subscribing service needs to provide either an OAuth bearer token or basic auth (id/secret) for authorization.

External Sources

Next Identity (NI) Events integrates with Akamai Identity Cloud Webhooks. An Akamai webhook is triggered anytime a user is created, updated, or deleted in the database. NI Events receives the webhook and applies filtering logic so that only targets associated with that user are notified of the event. This prevents downstream applications from being inundated with production volume level of events.

Additional external sources can be created either from a customer (self-hosted), a partner (self or Next Reason hosted), or by Next Reason based on roadmap and priority. Let us know if there is an integration that is important to determine the feasibility to offer it as a service.

The following is a schema for event payload that originated from Akamai Identity Cloud:

{
    "iss": "https://idp.example.com", //service provider publishing the SET
    "iat": 1458496025, //issued at dateTime
    "jti": "someuniqueeventidfb4e75b5411e4e19b6c0f", //unique id of this event
    "aud": [
      "https://receivingurl.example.com" //one or more audience identifiers
    ],
      "events": {
       "account/v1/userCreated": {
         "sub": "f3b24e35-5f34-4fef-aa6b-5e1f5067e5d8", //the subject of the SET (user UUID)
         "propertyId": "34345y3457y34", # our property id
         "clientId": "2345j346h5h6456", # our client id
         "dataSourceInfo": {
                      "attributes": [
                    "familyName"
                  ],
                  "captureApplicationId": "3vadba3vhqpkdgt112345",
                  "captureClientId": "abcdefqk4tx35wuj4ap2e53hq9",
                  "entityType": "user",
                  "globalSub": "capture-v1://app.capture.multi.dev.or.janrain.com/123456kdgtsrqd4st76m3/user/e499ac24-46bd-4d85-91ee-bdeadd446c1e",
                  "sub": "e499ac24-46bd-4d85-91ee-bdeadd446c1e"
         }
       }
     }
   }

Target

The target system is a publicly accessible endpoint that NI Events can hit. The event itself will not contain PII and therefore it will send without authorization. The receiving system must then verify the signature of the event to ensure it has originated from Next Identity and that it has not been intercepted. NI Events allows multiple targets to be configured.

Existing Target Integrations

NI Events integrates seamlessly with Salesforce as a target system. With this connection, NI Events can sync customer core profile data directly to Salesforce based on a configuration. For example if a record is created, NI Events will create the record in Salesforce and populate the record with the details that are needed, such as first name, last name, email, and others. In addition to creating or updating user details, NI Events will also facilitate the deletion of a record so that the platform remains GDPR compliant.

There are two options for delete events:

  1. NI Events facilitates the deletion ,or
  2. NI Events marks a specific field in the Salesforce record for deletion with a dateTime stamp so that the target service can facilitate the deletion.

Integration

Event Structure

The event payload is based on a Security Event Token (SET) - specification. To review the specification, visit <<https://www.rfc-editor.org/rfc/rfc8417.html>>.

Example payload for a user revocation event:

{
    "iss": "https://idp.example.com", //service provider publishing the SET
    "iat": 1458496025, //issued at dateTime
    "jti": "someuniqueeventidfb4e75b5411e4e19b6c0f", //unique id of this event
    "aud": [
      "https://receivingurl.example.com" //one or more audience identifiers
    ],
      "events": { //statements that describe a single logical event that has occurred
      "account/v1/userRevokedPropertyAccess": { 
          "sub": "f3b24e35-5f34-4fef-aa6b-5e1f5067e5d8", //the subject of the SET (user UUID)
          "dataSourceInfo": {
                      "attributes": [
                    "familyName"
                  ],
                  "idpAppId": "3kdjker3vhqpkdgtsrqd4st76m3",
                  "idpClientId": "12345t256jqk4tx35wuj4ap2e53hq9",
                  "idpEntityType": "user",
                  "idpSub": "e499ac24-46bd-4d85-91ee-bdeadd446c1e"
         }
      }
    }
  }

Queueing and Retrying

  • Events are handled in a first in, first out manner.
  • Property subscription traffic can affect another subscription inside the same environment however will not affect subscriptions in different environment.
    • Event service tenant is set at the environment level.
  • Requests will be aborted after 15 sec and retried based on the retry configuration
  • Failed events (after retries) are saved in a dead letter queue and can be retrieved.
  • All successful and failed events are auditable.
  • The number of retries and time period between them are configurable at any level (organization, environment, property, client).
    • Number of retries (default is 5) - so total number of sends is 1 (original) + 5 (retries)
    • Frequency of retries (default is [30, 60, 120, 300, 900] in seconds).