Deprovisioning Webhooks
Last updated: October 9, 2024
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 walks you through 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
Traditionally, one of the most time-consuming and error-prone parts of the access review process is removing access that's no longer needed. 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. Put your license management on auto-pilot. 💵 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 helps you understand when a deprovisioning webhook fires after a time-based access request expires.
Configuring an AppStore app webhook
Follow these steps if you want to configure an app-level deprovisioning webhook that runs when time-based access expires for that app. Make sure you're setting the webhook up at the right layer (app or permission). 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 "Advanced Settings".
3. Find the Inline Webhooks section and choose your webhook in the Deprovisioning Webhook dropdown.
Configuring an AppStore permission webhook
Follow these steps if you want to configure a permission-level deprovisioning webhook that runs when time-based access expires for that permission. Make sure you're setting the webhook up at the right layer (app or permission). 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 "Advanced Settings".
3. Click "Permissions", then click on the target permission.
4. Find the Inline Webhooks section and choose your webhook in the Deprovisioning Webhook dropdown.
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 Workflows tab.
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 to help you get started with deprovisioning webhooks.
These workflows aren't production-ready -- they simply 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.