Feature Overview

The following capabilities will be supported with the Moveworks Sailpoint approvals integration.

1. Access Request Approvals - notify approvers about access requests and let approvers complete them in chat.

• Approve - Approves the work item
• Deny - Denies the work item
• View Detail - Redirects to Sailpoint for additional details and line item approval

2. Access Review Approvals - notify approvers about access reviews that are pending their action. Note that these are based on CertificationEntities.

• Start access review - takes the user to Sailpoint to complete the access review

3. Approval Looping - Both approvals will be also available in the approvals queue. This means when the user gets notified for any other approval, they will be reminded that there are additional approvals to complete.

4. Approval Lookups - Approvals in the approval queue will be retrievable any time the user asks for their latest approvals.

General Prerequisites

Concept: Sailpoint Plugin

Sailpoint IIQ has limited out-of-the-box APIs which fail to serve the needs of our system. As a result, we have built a Sailpoint Plugin which installs a few APIs needed in your Sailpoint instance.

All authentication with these endpoints is done over an Oauth client whose capabilities are bound to the same permissions as our proxy user (see Sailpoint’s docs).

Moveworks Object List API (GET /object/{objectType})

This API allows us to retrieve SailpointObjects of a given class from your Sailpoint instance. Only the following Sailpoint Objects are accessible through this API.

• WorkItem
• IdentityRequest

With this API, we can:

• Filter Records - we use the same filter language defined on Sailpoint’s community site: https://community.sailpoint.com/t5/Technical-White-Papers/Filters-and-Filter-Strings/ta-p/76012
• Enforce Ordering - Ensure a deterministic response order for records like user identities
• Perform Paging - Basic limit offset control

Internally, we use various methods from the QueryOptions class of the sailpoint.object package to build a query and then use the search method present under the sailpoint.api package to fetch a list of SailpintObjects based on the class and query provided. This method interacts with the server where the plugin was installed to fetch the objects from the database.

Moveworks Object by ID API (GET /object/{objectType}/{id})

This API allows us to retrieve SailpointObjects of a given class from your Sailpoint instance. Only the following Sailpoint Objects are accessible through this API.

• WorkItem
• IdentityRequest

Internally, we use the getObjectById method present under the sailpoint.api package to fetch a SailpointObject by id. This method interacts with the server where the plugin was installed to fetch the objects from the database.

Moveworks Table List API (GET /table/{objectType})

This API lets us fetch Identity data and additional details for specific SailpointObjects. Only the following Sailpoint Object is being accessed through this API.

• Identity
• CertificationEntity

Internally, we use various methods from the QueryOptions class of the sailpoint.object package to build a query and then use the search method present under the sailpoint.api package to perform a projection search for selected object properties, here CertificationEntity.

Moveworks Object Action API (PUT /object/{objectType}/{id})

This API allows us to take action on a SailpointObject. It is only implemented for the following Sailpoint Objects

• WorkItem
• CertificationEntity

This will be how we approve work items & certification entities from chat.

Internally, we use the following methods present under the WorkItem class of the sailpoint.object package to take action on a SailpointObject:

• setState - To update the state of the SailpointObject
• setCompleter - To set the approver by ID
• addComment - To add a comment with a timestamp and person that made the comment.
• setCompletionComments - To add comments upon completion of the approval request

Moveworks Workgroup API (GET /object/workgroup/{identity_id}/members)

This API lets us fetch all the members of a specific workgroup in SailPoint. The identity_id of the workgroup is specified in the URL of the request. If the identity_id represents a workgroup, it fetches the members of the workgroup and returns a list of the workgroup users.

Internally, we use the following methods:

• isWorkgroup method from the Identity class under the sailpoint.object package to check if an Identity object is an workgroup or not.
• getWorkgroupMembers method from the ObjectUtil class under the sailpoint.api package to get the members of the workgroup

API Logging

We follow the recommended approach of adding custom logging to your Sailpoint server based on the following libraries:

• org.apache.commons.logging.Log
• org.apache.commons.logging.LogFactory

Please look for com.moveworks.plugin.RequestInterceptor in the logs as shown below:

Concept: Agent

Given Sailpoint IdentityIQ is hosted on-prem, you likely have it locked down within your VPN. To preserve your network integrity, we install an agent on a HA cluster which is able to interact with your Sailpoint instance, and only communicate with Moveworks’ platform in the outbound direction.

Identity Map

Since Moveworks takes a number of actions on behalf of a user, we rely on an identity layer to ensure the user is still kept in the loop. To reduce end-user latency & avoid rate-limits against your instance, we will store an offline copy of your identity every 4 hours.

We will do this using the Moveworks Table API.

curl --location -g --request GET '{{**sailpoint_instance_url**}}/table/Identity?limit=100&offset=0&orderby=-id&filter=active == true' \
--header 'Authorization: Bearer {{**bearer_token**}}'

Moveworks already has the user’s email from your core identity system (e.g. Okta, Active Directory, One Login). With this process, Moveworks will be able to associate users with their Sailpoint IDs.

(e.g. [email protected] = 8a8080824df45873014df45bdd9300dd)

Access Request Architecture

The below diagram represents how Moveworks will integrate with Access Requests. Any network security concepts (e.g. Agent) or authentication are excluded for simplification purposes.

To walk through the above diagram:

1. Approval Detection Server - checks for new approvals in Sailpoint every 60 seconds.

   1. The Table API retrieves Work Items that were updated in the last 60 seconds

      Bash

      curl --location -g --request GET '{{**sailpoint_instance_url**}}/object/WorkItem?limit=100&offset=0&filter=(modified>=DATE$1318884600000)' \
      --header 'Authorization: Bearer {{**bearer_token**}}'
      

2. Approval Processor - get details for approval notifications where appropriate

   1. Approval processor filters out Work Item updates that do not result in notifications
   2. Approval processor fetches entitlement details for the notification card from the Details API.

   Group approvals are also supported by Moveworks wherein any one user from a group of eligible approvers can approve. The request is sent to all approvers in the group simultaneously and soon as any one of them approves it, access is granted to the user.

   

   Bash

   curl --location -g --request GET '{{**sailpoint_instance_url**}}/object/WorkItem/8a8080824df45873014df45bdd9300dd' \
   --header 'Authorization: Bearer {{**bearer_token**}}'
   

   1. Details API fetches the Work Item of interest, then uses Sailpoint’s JDK accessors to retrieve the approval set, its approval items, and entitlement descriptions for each approval item.

3. Conversation Engine - notifies the user & collects their response

   1. Prepares a notification based on the results from the details API

   2. Follows up with the user through our “Approval Looping” experience.

   3. Upon user action, uses the Action API to update the Work Item status in Sailpoint.

      Bash

      curl --location --request POST '{{**sailpoint_instance_url**}}/object/WorkItem/8a8080824df45873014df45bdd9300dd' \
      --header 'Authorization: Bearer {{**bearer_token**}}'
      
      --data-raw '{
      		"approver": "{{approver_user_id}}",
          "state": "Finished",
          "comment": "Approving this request"
      }'
      

      📘

      Currently, Moveworks’ updates will be applied to the Work Item as a bulk certify or bulk deny action. In the future, granular decisions may be made, in which case we will alter the Approval Items instead.

Access Review Architecture

The below diagram represents how Moveworks will integrate with Access Reviews. Any network security concepts (e.g. Agent) or authentication are excluded for simplification purposes.

To walk through the above diagram:

1. Approval Detection Server - checks for new approvals in Sailpoint every 60 seconds.

   1. The Table API retrieves Certification Entities that were updated in the last 60 seconds

      Bash

      curl --location -g --request GET '{{**sailpoint_instance_url**}}/table/CertificationEntity?limit=100&offset=0&filter=updated_at>DATE$1318884600000' \
      --header 'Authorization: Bearer {{**bearer_token**}}'
      

2. Approval Processor - get details for approval notifications where appropriate

   1. Approval processor filters out Certification Entity updates that do not result in notifications

   2. Approval processor fetches certification item details for the notification card from the Details API.

      Bash

      curl --location -g --request GET '{{**sailpoint_instance_url**}}/table/CertificationEntity/8a8080824df45873014df45bdd9300dd' \
      --header 'Authorization: Bearer {{**bearer_token**}}'
      

   3. Details API fetches the Certification Entity of interest, then uses Sailpoint’s JDK accessors to retrieve the associated Certification Items.

3. Conversation Engine - notifies the user & collects their response

   1. Prepares a notification based on the results from the details API
   2. Follows up with the user through our “Approval Looping” experience.