Workflows
Simplifying Complex Business Challenges with Next Identity
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
Component | Description |
---|---|
Sources | Sources are where events originate. Examples are Next Identity Journeys, Akamai Identity Cloud or a user directory. |
Events | Events are triggers. Transactions such as when a user successfully logs in, resets their password, or revokes an application's access to their data are just a few examples of an event. |
Actions | Actions are what need to be done after an event occurs. Common actions include notifying an endpoint or sending an email or SMS. Actions can be asynchronous (Action Type: Notify) or synchronous (Action Type: Enrich). |
Notifications | Notifications are the messages that are sent to targets. Messages may include <glossary:PII> depending on the event type and action. |
Targets | Targets are URL endpoints or Next Identity Connect integrations that receive and process notifications and send responses. |
Responses | Responses are sent by targets after processing the notification. Responses are expected to be either HTTP response codes or payloads depending on the action type. |
Sources
Sources are where events originate.
The following sources are supported:
Source | Description |
---|---|
Next Identity Journeys | User events from Next Identity Journeys API such as Pre-Registration, Registration, Resend Verification, and more are available to trigger workflows. |
Akamai Identity Cloud | Next Identity Workflows integrates with Akamai Identity Cloud Webhooks. An Akamai webhook is triggered anytime a user is created , updated , or deleted in the database. Next Identity Workflows receives the webhook and applies filtering logic so that only properties associated with that user are notified of the event. |
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
Event Name | Description | Actions Supported | Event Filters Supported |
---|---|---|---|
Pre-Registration | Triggers after a user is successfully invited to activate their account, but before they receive an email or SMS. | Notify (includes link and data for email trigger) | Configured per client ID |
Registration (traditional & social) | Triggers after a user successfully registers an account, but before they are sent a verification method such as email or SMS link. | Notify (includes link and data for email trigger) | Configured per client ID |
Resend Verification | Triggers after a user has triggered the resent verification flow. | Notify (includes link and data for email trigger) | Configured per client ID |
Forgot Password | Triggers after the user has successfully requested to reset their password, but before they receive an email or SMS. | Notify (includes link and data for email trigger) | Configured per client ID |
Password Updated | Triggers after a user's password has been successfully updated. | Notify | Configured per client ID |
User Access Revoked | A user has revoked access to an application. | Notify | Next Identity property |
Login | A user has successfully entered a username/password combination through the hosted journeys or the login API. | Enrich (requires response from target system to proceed with login event) | Configured per client ID |
Source: Akamai Identity Cloud
Event Type | Description | Actions Supported | Event Filters supported |
---|---|---|---|
User Created | A new user profile has been created in Akamai Identity Cloud. | Notify | Next Identity property |
User Updated | A user profile has been updated in Akamai Identity Cloud. | Notify | Next Identity property, By End user Attribute (coming soon) |
User Deleted | A user has been deleted in Akamai Identity Cloud. | Notify | Next Identity property |
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
Action Type | Description | Execution | Configuration Options | Events Supported |
---|---|---|---|---|
Notify | Send a notification to one or more endpoints. | Asynchronous | No custom configuration at this time. Notifications will include standard data depending on the type of event. User Data Change events will include standard set of user details. Transactional email events will include basic user data as well as a verification URL | User Update, User Created, User Deleted, User Revoked, Pre-Register, Register, Forgot Password, Resend Verification |
Enrich | Send a notification to an endpoint. Customer endpoint needs to respond with data to enrich the transaction before it can proceed. | Synchronous | No custom configuration at this time. Notifications will include standard data depending on the type of event. Transactional enrich events will include limited user information. | Login |
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).
- Number of retries (default is
- 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 proceedblock : The user should be blockedchallenge : 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.
Updated about 1 month ago