How we designed a scalable and extensible framework for bringing event-driven integrations to our customers
Event Driven Integration with SailPoint
Many modern software architectures are implemented using event-driven programming. An event-driven program is designed to receive and react to events such as user clicks in a UI, object changes in a database, or messages originating from other subsystems in a distributed architecture. A state owner broadcasts predefined events when something changes in their system, and downstream consumers listen to those events and update their state accordingly. This allows decoupled, highly reactive, independent subsystems to all work in concert.
Event-driven programming lends itself well to integration use cases between SaaS applications from different vendors. State changes in one application can be emitted, often in the form of webhooks, and received by a multitude of downstream applications. A canonical example is wanting to see a Slack notification every time a Jira ticket changes. A webhook is the perfect vehicle for communicating that state change. Want to auto-invite new employees to your #welcome Slack channel every time a new user is added to your directory? A webhook makes the perfect vehicle here too.
At SailPoint, we think deeply about identities, how they’re governed, and how they can be more widely used in your business processes. For a long time, SailPoint has provided REST APIs which allow our customers to build their own applications, web sites, and tools that take advantage of data, features, and flows from SailPoint products. The APIs follow a familiar RESTful standard, using query and path parameters, request/response headers, and JSON request/response bodies.
Hearing frequently how customers want to integrate identity events and data with 3rd party applications and custom workflows, we’ve added event-driven integration with all your identity data. For example, you may wish to notify a system administrator when a new employee joins the company, or invoke a targeted certification campaign when an employee’s manager changes. SailPoint now emits relevant, timely, actionable events, letting you extend identity governance deeper into your application ecosystem.
By using either our user-friendly Administration UI or configuration REST API, identity governance administrators are able to subscribe their own custom webhook receiver endpoints or AWS EventBridge integrations. Once subscribed to events, SailPoint will start streaming identity events into their custom integrations.
State Change Events
SailPoint currently emits events for these different state changes:
- Identity Created
- Identity Deleted
- Identity Attributes Changed
- Saved Search Complete
- Identity Aggregation Completed
- Access Request Submitted
- Access Request Dynamic Approval
- Access Request Decision
- Provisioning Action Completed
These are the core events necessary to implement custom Joiner-Mover-Leaver and scheduled reporting integrations.
Event Trigger types
Event subscribers fall into two categories: those that need to receive notice of an event only, and those that need to implement some custom business logic and reply to the event (e.g. query an external system for an approval, and respond with that approval). To address both types of receivers, SailPoint emits two types of events.
FIRE_AND_FORGET
This type of event is used to notify the custom application of a particular occurrence of a state change. This integration is not bi-directional, and it does not require a response from the custom application.
REQUEST_RESPONSE
This type of event is used to give the custom application an ability to answer back to an event sent by SailPoint. This integration is bi-directional – a response from the custom application is required for an event invocation to be considered complete and successful.
All available events provide expected JSON payload schema definitions in Avro format. Input and output schema define the data schema for a record’s value. This schema describes the fields allowed in the value, along with their data types and example input and output payload. You can find all available events for your IdentityNow account in the Administrator UI or via REST API calls.
Subscribing to an Event
Once your custom integration is ready to receive and process events from SailPoint, you can create a subscription for an event. Once a subscription is created, your custom application will start receiving event invocations. All subscriptions can be configured using a SailPoint REST API. Many subscriptions can also be configured in your IdentityNow Administrator UI.
HTTP vs AWS EventBridge Subscription Type
SailPoint can send events to two types of receivers: HTTP (webhooks), or to AWS EventBridge for processes integrated there.
HTTP event triggers
The HTTP event trigger makes outbound calls to the URL specified in your event subscription. The outbound call is an HTTP POST with a predefined event payload and extra metadata as JSON objects. Before using HTTP subscription, you will have to implement a custom integration web service with an HTTP endpoint accessible via the Internet. It is your responsibility to implement and host your custom integration web service and handle HTTP events. When a REQUEST_RESPONSE trigger invocation request is received by the custom application, it must respond to the request with the output payload as specified in the trigger’s output schema. For HTTP, we support the following expected responses:
Synchronous – The custom application responds within 10 seconds to the trigger invocation with the output payload.
Asynchronous – The custom application only needs to acknowledge (2xx Success) that it has received the trigger invocation request and complete the invocation at a later time.
Dynamic – The custom application determines arbitrarily whether to respond to the trigger invocation synchronously or asynchronously.
AWS EventBridge event triggers
If you host your custom integrations in AWS, you can take advantage of using Amazon EventBridge for integration with IdentityNow. Amazon EventBridge is an event bus service which consumes event data streaming from SailPoint. Events received in Amazon EventBridge can be redirected to AWS services such as AWS Lambda, Amazon SNS, Amazon SQS, and Amazon Kinesis streams. Based on the nature of EventBridge for REQUEST_RESPONSE trigger invocation you can implement only ASYNC response for event triggers.
How to respond to a Trigger Invocation
For a REQUEST_RESPONSE trigger type, your custom integrations will need to provide appropriate response HTTP status code and payload. For REQUEST_RESPONSE, SYNC invocation your integrations need to respond with appropriate JSON payload defined in the output schema for the trigger. REQUEST_RESPONSE (ASYNC, DYNAMIC) trigger metadata will include a callback URL and unique secret. Custom integrations will need to perform a final HTTP POST to SailPoint at the provided callback URL, appropriate output JSON, and provided secret.
Conclusion
With initial set of emitted events and more to come in the near future, you can start integrating your custom workflows and applications, powered by identity.
References