Deprovisioning Webhooks

Background

Your company needs to be capital-efficient and secure, and you obviously want to automate everything. Removing user access and cleaning up licenses when they’re no longer needed are crucial activities when it comes to maintaining least-privilege and keeping down costs. But this can get time-consuming quickly. In Lumos, you can use deprovisioning webhooks to automate removal of access or licenses for virtually any app, resource, or permission. This article describes some common scenarios where deprovisioning webhooks are useful and how to set them up.

Common use cases

If you’re looking for inspiration, below are some sample scenarios where Lumos customers have used deprovisioning webhooks to eliminate manual work, save costs, and improve security.

Removing time-based access Let’s say you want to assign someone an app license for 30 days via a provisioning webhook. At the end of that 30 days — how should access be removed? See Provisioning Webhooks You can set a deprovisioning webhook that automatically removes the access that was created after the timeframe expires.
Automating removals for audits Removing access that’s no longer needed is often a time-consuming and error-prone part of the Access Review process. While Lumos has integrations to your IdP and many service providers, internal tools or complex entitlements may need a more bespoke solution. You can call a deprovisioning workflow at the end of an Access Review to remove access automatically in the exact way that’s needed. See Using Lumos for Access Reviews
Removing inactive accounts If someone is no longer using their access to an app, you can create an inactivity workflow that asks them (or the system owner) whether they still need it. If it’s no longer needed, you can run a deprovisioning webhook to automatically remove that access with no human intervention. See Creating an Inactivity Workflow

What’s sent in the webhook?

Lumos sends a JSON payload of data about the user’s access when the webhook is triggered. The format of this payload is below.

{
  "application": {
    "app_id": "demo_app",
    "instance_id": "0ob3ggjlhx892dc4abcde",
    "user_friendly_label": "Demo App"
  },
  "permissions": [
    {
      "label": "Permission One Label",
      "value": "Permission One",
      "type": "PERMISSION",
      "source": "MANUAL"
    },
    {
      "label": "Permission Two Label",
      "value": "Permission Two",
      "type": "PERMISSION",
      "source": "MANUAL"
    },
     ...
  ],
  "user": {
    "email": "peterparker@lumos.com",
    "given_name": "Peter",
    "family_name": "Parker"
  },
  "target_user": {
     "email": "peterparker@lumos.com",
     "given_name": "Peter",
     "family_name": "Parker"
  },
  "request_comment": "Give me access!",
  "custom_fields": {
     "username": "pparker"
  }
}

How should my script or workflow respond?

Please follow the general guidance on how to format your webhook responses here: Creating Webhooks The allowed “response” values for deprovisioning webhooks can be found below. If the user was deprovisioned (Success)

{
"response": "SUCCESS",
"msg": "The message you want the requester to see if deprovisioning was successful"
}

If the user was not deprovisioned (Failure)

{
"response": "FAILURE",
"msg": "The message you want the requester to see if deprovisioning was unsuccessful"
}

Deprovisioning webhooks will also be considered successful if your script/workflow returns an HTTP 204 response.

Where can I use deprovisioning webhooks?

Deprovisioning webhooks can be triggered in any of the following scenarios:

To remove access when a time-based access request expires. See Requesting Access to an App
To remove access when an account is marked as rejected in an access review. See Using Lumos for Access Reviews
To remove access when an account is flagged for removal in an inactivity workflow. See Inactivity Workflows 101

The diagram below shows when a deprovisioning webhook fires after a time-based access request expires.

Configuring an AppStore Deprovisioning Webhook

Follow these steps if you want to configure a deprovisioning webhook that runs when time-based access expires for that app. Make sure you’re setting the webhook up at the right layer (Provisioning Type = App). Guidance is at the “Where can I use deprovisioning webhooks?” section of this article.

1. Go to your AppStore apps and find the app in question.

2. Click “Settings”.

3. Find the “Deprovisioning” section, click “Add Step” and select “Run Webhook”.

Configuring an Access Review deprovisioning webhook

Follow these steps if you want to make a deprovisioning webhook the default removal method for one of your access reviews.

1. Find your access review.

2. Scroll to the Default Removal Method column, click on the arrow, then choose the “Webhook” option.

See Editing Access Review App Settings

3. Select the correct webhook to save your settings.

More information on the Default Removal Method behavior can be found here: Editing Access Review App Settings

Configuring an Inactivity Workflow deprovisioning webhook

Follow these steps if you want to run a deprovisioning webhook when a user is flagged for removal in an Inactivity Workflow.

1. Find your app and click on the Inactivity Workflowstab.

2. In the Remove section, choose the “Run Webhook” option.

3. Choose the webhook and click “Save Changes” to save your workflow.

Read here to learn how to trigger your Inactivity Workflow: Creating an Inactivity Workflow

Example workflows

At the bottom of this article, you’ll find working webhook scripts that you can use to get started with deprovisioning webhooks. These workflows aren’t production-ready — they parse the incoming webhook payload, perform a trivial check with the incoming data, then return a response in the format that Lumos expects. You can use these scripts as a way to quickly start creating webhooks of your own.

Connect an App

Supported Generics

Webhooks, ITSM, and Manual Tasks

On-Premise Agent

Connector SDK

Managing Integrations

Integration Library

Deprovisioning Webhooks

Background

Common use cases

What’s sent in the webhook?

How should my script or workflow respond?

Where can I use deprovisioning webhooks?

Configuring an AppStore Deprovisioning Webhook

1. Go to your AppStore apps and find the app in question.

2. Click “Settings”.

3. Find the “Deprovisioning” section, click “Add Step” and select “Run Webhook”.

Configuring an Access Review deprovisioning webhook

1. Find your access review.

2. Scroll to the Default Removal Method column, click on the arrow, then choose the “Webhook” option.

3. Select the correct webhook to save your settings.

Configuring an Inactivity Workflow deprovisioning webhook

1. Find your app and click on the Inactivity Workflowstab.

2. In the Remove section, choose the “Run Webhook” option.

3. Choose the webhook and click “Save Changes” to save your workflow.

Example workflows

​Background

​Common use cases

​What’s sent in the webhook?

​How should my script or workflow respond?

​Where can I use deprovisioning webhooks?

​Configuring an AppStore Deprovisioning Webhook

​1. Go to your AppStore apps and find the app in question.

​2. Click “Settings”.

​3. Find the “Deprovisioning” section, click “Add Step” and select “Run Webhook”.

​4. Within the Webhook step, select your webhook from the dropdown.

​Configuring an Access Review deprovisioning webhook

​1. Find your access review.

​2. Scroll to the Default Removal Method column, click on the arrow, then choose the “Webhook” option.

​3. Select the correct webhook to save your settings.

​Configuring an Inactivity Workflow deprovisioning webhook

​1. Find your app and click on the Inactivity Workflowstab.

​2. In the Remove section, choose the “Run Webhook” option.

​3. Choose the webhook and click “Save Changes” to save your workflow.

​Example workflows

Background

Common use cases

What’s sent in the webhook?

How should my script or workflow respond?

Where can I use deprovisioning webhooks?

Configuring an AppStore Deprovisioning Webhook

1. Go to your AppStore apps and find the app in question.

2. Click “Settings”.

3. Find the “Deprovisioning” section, click “Add Step” and select “Run Webhook”.

4. Within the Webhook step, select your webhook from the dropdown.

Configuring an Access Review deprovisioning webhook

1. Find your access review.

2. Scroll to the Default Removal Method column, click on the arrow, then choose the “Webhook” option.

3. Select the correct webhook to save your settings.

Configuring an Inactivity Workflow deprovisioning webhook

1. Find your app and click on the Inactivity Workflowstab.

2. In the Remove section, choose the “Run Webhook” option.

3. Choose the webhook and click “Save Changes” to save your workflow.

Example workflows