Workflows is a notification and action service that will allow you to augment your identity management experience. Workflows is a plug-in orchestration capability that helps customers easily solve complex business challenges by using existing or custom modules. With Workflows, you can choose configure the system to notify you when certain events happen, you can then perform additional processing on the request (either before the transaction completes as a supplement to the existing user journey, or after the transaction is done).

📘

What happened to Events and Actions?

Events and Actions are now called Workflows, we decided to combine this two functions to delivers even greater flexibility and customization options to meet even the most complex enterprise use cases.

Where do you use Workflows?

Here are common use cases for workflows:

• Notify downstream systems that a user has updated their profile
• Challenge a user with step-up authentication after processing signals through your external risk engine
• Enrich a token with additional customer data (claims) such as a user role, number of loyalty points, or program status
• Restrict access to an application after processing a login request through your own system and indicating user should be blocked.
• Trigger a custom email when a user requests a password reset or other transactional activity.

How do Workflows work?

To understand how Workflows work, we must first be familiar with the different components.

The Workflows feature includes the following components

Sources

Sources are where events originate.

The following sources are supported:

📘

Support for additional sources

Additional 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. Contact us if you'd like to discuss support for a new source to meet your workflow requirements.

Events

Events are what has happened either in the end user record or with the end user journey. Events such as when a user attempts to log in, resets their password, updates their profile data, or revokes an application's access to their data are just a few examples.

Please note that the available events are dependent on the source of the event. With third party sources for events, Workflows capabilities are limited to what is available from that specific source. For example, if a third party cannot send Workflows an alert about a user record change in that system, the Workflows service will be unable to pass that event notification along to your application.

Source: Next Identity Journeys

Source: Akamai Identity Cloud

Subscribing to Events

Currently, subscription to events can be configured as follows:

A listening endpoint can subscribe to all user data change events (ex. User Added, User Updated, User Deleted, and User Revoked) for a property. Data returned in those notifications will be from a standard set and cannot be customized (see samples in the notifications section below).

A listening endpoint can subscribe to all transactional email events (ex. forgot password, verify email, etc.) for a client id. Data returned in those notifications will be from a standard set and cannot be customized (see samples in the notifications section below).

A listening endpoint can subscribe to all enrich events for a client ID. Data returned in the notification will be from a standard set and cannot be customized (see samples in the notifications section below).

Actions

Action are what need to be done after an event occurs.

All actions will begin with a notification to a customer endpoint.

All actions will require a 200 OK response from the customer endpoint to indicate successful delivery.

Some actions will require an additional response from the customer endpoint to complete the user transaction.

Some actions will trigger an additional step or transaction, such as automatically configuring an email send on behalf of the customer (coming soon).

Actions are either asynchronous (Notify) when the target service only needs to be notified that an event occurred, or synchronous (Enrich) and require a response from the target system before the event can proceed (such as when processing signals from an external risk engine and determining a response before a user journey can proceed).

One or more actions can be configured for each event type.

Action types

Notify

Notify is a type of action within Workflows that sends a notification to a receiving endpoint when an event occurs. These notifications can be configured to be sent to one or more endpoints.

Notify actions are asynchronous which means that a response from the target system isn't needed in order for the event to proceed.

Enrich

Enrich is a type of action within Workflows where you can perform additional processing on the request after the event begins but before the transaction is complete. With the enrich feature, administrators can, for example, easily add custom modules to their authentication process and gain greater control over user access.

Enrich actions are synchronous requests, which means that a response is needed before the current transaction can proceed. For example, when a user logs in, there are multiple steps involved such as verifying the email, checking the password, and checking the risk score.

Notifications

Notifications are the messages that are sent to targets. Messages may include PII depending on the event type and action. For certain event types, notifications can be configured to send a verification URL (sometimes called a magic link) along with metadata that will allow the target to hook on to the event and send custom emails to end users.

Notification Payload Samples

Below are notification payload samples for common events such as User Created/Updated, Revoke Access, Login, Update Password and Registration, etc.

Notification Samples for changes to the user record

{
    "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",                 // property id
         "clientId": "2345j346h5h6456",                 // our client id
         "dataSourceInfo": {
                      "attributes": [
                    "familyName"
                  ],
                  "captureApplicationId": "aaabbbccc111222333",
                  "captureClientId": "abcd12345",
                  "entityType": "user",
                  "globalSub": "{{URL}}",
                  "sub": "00000000-46bd-4d85-91ee-bdeadd446c1e"
         }
       }
     }
   }

{
    "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": {
                  "captureApplicationId": "3vadba3vhqpkdgtsrqd4st76m3",
                  "captureClientId": "3fp4zt9t256jqk4tx35wuj4ap2e53hq9",
                  "entityType": "user",
                  "globalSub": "{{URL}}",
                  "sub": "00000000-46bd-4d85-91ee-bdeadd446c1e"
         }
      }
    }
  }

{
    "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/passwordUpdated": {
            "sub": "initialUserUuid",
            "email": "email",
            "firstName": "firstName",
            "propertyId": "propId",
            "clientId": "eventServiceClientId",
            "locale": "locale",
            "dataSourceInfo": {
                "sub": "e499ac24-46bd-4d85-91ee-bdeadd446c1e",
                                "entityType": "akamai_entity"
            }
        }
    }
}

Notification Samples for transactional email events

{
    "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/register": {                           //Also preregister, forgotPassword, resendVerification
            "sub": "f3b24e35-5f34-4fef-aa6b-5e1f5067e5d8", //the subject of the SET (user UUID)
            "propertyId": "34345y3457y34",
            "clientId": "2345j346h5h6456", 
            "link": "<BASE URL>?a=CODE&client_id=CLIENTID&ui_locales=LOCALE",
            "email": "email",
            "firstName": "firstName",
            "locale": "locale",
            "dataSourceInfo": {
                "sub": "e499ac24-46bd-4d85-91ee-bdeadd446c1e"
            }
        }
    }
}

Notification Samples for transactional user events that support enrich actions

{
    "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/userAuthenticationAction": { 
            "sub": "f3b24e35-5f34-4fef-aa6b-5e1f5067e5d8", //the subject of the SET (user UUID)
            "propertyId": "34345y3457y34", 
            "clientId": "2345j346h5h6456",
            "dataSourceInfo": {
                "sub": "e499ac24-46bd-4d85-91ee-bdeadd446c1e"
            }
        }
    }
}

Queueing and Retrying

Notifications have queueing, retrying, and performance considerations:

Queueing

• Notifications are handled in a first in, first out manner.
• Requests will be aborted after 5 seconds and retried based on the retry configuration.

Retrying

• Failed notifications (after retries) are saved in a dead letter queue and can be retrieved.
• 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).
• All notifications are auditable.

Performance Considerations

• Property subscription traffic can affect another subscription inside the same environment however will not affect subscriptions in different environment.

Targets

Targets are URL endpoints or Next Identity Connect integrations that receive and process notifications and send responses. Targets should support signed and encrypted JWT (JWS and JWE) formats.

Target systems are publicly accessible endpoints or Next Identity Connect integration. The event itself will not contain PII and therefore it will send without authorization. In case the target opts for receiving events that could possibly contain PII (like transactional emails) we recommend them to support encrypted JWT (JWE) on their end.

Once the target system receives event notification it must verify the signature of the event to ensure it has originated from Next Identity and that it has not been intercepted.

Workflows allows multiple targets to be configured to receive event notifications.

Responses

Once a target system has gotten a workflow notification from Next Identity, a response is expected in order to prevent a retry or a logged failure. In the case of the synchronous actions, a response is needed to proceed with the user workflow.

Responses are expected to always be 200 OK HTTP response codes. If the system receives an invalid url response it will be logged as a failure and will not be retried. Http error responses will be retried. Any other responses else that is not a 2XX response or one of the above is marked as a failure and will not be retried.

In the case of the asynchronous enrich actions, where a response message is needed to determine next steps for the user workflow, the response back to the Next Identity workflows service is expected to contain a signed JWT in the body with the needed information to proceed. When a receiving endpoint is configured for workflows, the JWS source must be provided to the configuration team in order for the service to decode the JWT.

A sample payload response for an enrich action from the target system back to the Next Identity Workflows service might look like this after the JWT is decoded:

{  
    "iss": "https://system.example.com",                     //service provider publishing the SET (optional) 
    "iat": 1458496025,                                                         //issued at dateTime (optional)  
    "jti": "someuniqueeventidfb4e75b5411e4e19b6c0f", //unique id of this event  
    "action": "allow",                               //parameter indicating whether to allow block or challenge the attempt
    "custom_claims": {                                               //parameter indicating whether the token will be enriched  
        "some_key1": "some_value1",  
        "some_key2": "some_value2"  
    }  
} 
 

Target System Response Message Components

Attribute	Description	Required	Value Restrictions
action	What action should Next Identity take with this transaction? This should be from customer system based on whatever processing was done based on the original Next Identity notification for this transaction.		Accepted value allowed are: allow: The user can proceed block: The user should be blocked challenge: The user should be provided a security challenge
custom_claims	Claims from an external service that are included in the id_token for the user at the end of the login process		This is appended to the id_token as is and does not go through any validation or changes in the service.
iss	Service provider publishing the SET		None
iat	Issued at dateTime		None
jti	Uniqe ID of the event		None

📘

How to configure Workflows?

Workflows are configured by Next Reason. Contact your Next Reason Solutions Architect to discuss your workflow requirements.

In a Nutshell

Workflows is a Next Identity feature that helps businesses solve complex challenges using existing or customized modules. It is a plug-in orchestration capability that allows you to configure the system to perform additional processing on requests after the customer authenticates but before the transaction is complete.

Workflows combines Events and Actions and offers greater flexibility and customization options to meet even the most complex enterprise use cases.

Workflows has several common use cases, such as :

• Restricting access to an application based on certain attributes,
• Notifying downstream systems that a user has revoked access or updated their profile,
• Triggering custom emails after a user registers a new device,
• Enriching a token with additional customer data
• Challenging a user with step-up authentication after processing signals through an external risk engine.

Workflows consists of five components: Sources, Events, Actions, Notifications, and Targets.

Sources are where events originate. Currently, there are two sources: Next Identity Journeys and Akamai Identity Cloud.

Events are triggers that occur after a user performs a transaction, such as successfully logging in or revoking an application's access to their data.

Actions are what need to be done after an event occurs. Common actions include notifying an endpoint or sending an email or SMS.

Notifications are the messages that are sent to targets, which are URL endpoints or Next Identity Connect integrations that receive and process notifications and send responses.

Targets are URL endpoints or Next Identity Connect integrations that receive and process notifications and send responses.

Responses are sent by targets after processing the notification and are expected to be either HTTP response codes or payloads depending on the action type.