Provisioning Webhooks

Background

Your identity provider may have SCIM connectors that help you automate user provisioning tasks.

But what happens when SCIM support isn't available, it's too expensive, or the connector doesn't do what you need? Or what if you need to provision to a homegrown app or database?

You can use provisioning webhooks to automate provisioning for virtually any app, resource, or permission so that your app admins spend less time managing access and employees get what they need faster. 🚀

This article walks you through some common scenarios where provisioning 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 provisioning webhooks to eliminate manual work and reduce time to access.

• License assignments

  Let's say you can assign people to Zendesk in your IdP but that doesn't assign them a license, and you want to fully-automate the workflow.

  You can create a provisioning webhook that grants the license requested after the request is approved.

• SCIM-less provisioning

  Not all apps support SCIM, or it might require a costly upgrade. However, there are many cases where you still want to create an account for someone via a user management API.

  You can call the service provider's API via a provisioning webhook after someone's access is approved to automate common tasks, such as creating or updating their account. See📄 Approving Access Requests

• Internally-developed apps

  You might need to create or update an account for someone when they need more access to an internally-developed app or tool.

  Provisioning webhooks have also been deployed here to save hours of time managing and securing access to these tools, which usually contain sensitive data.

What's sent in the webhook?

Lumos sends a JSON payload of access request data 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"
    },
     ...
  ],
  "target_user": {
    "email": "peterparker@lumos.com",
    "given_name": "Peter",
    "family_name": "Parker"
  },
  "access_length": 43189,
  "request_comment": "Give me access!",
  "request_task_url": "http://lumosidentity.com/tasks?requestId=12898293343",
  "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 provisioning webhooks can be found below.

If the user was provisioned (Success)

{
"response": "PROVISIONED_USER”
}

If the user was not provisioned (Failure)

{
"response": "NO_PROVISIONING_ACTION”
}

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

Where can I use provisioning webhooks?

Provisioning webhooks are used in the AppStore. See📄 What is the AppStore?

After you create a provisioning webhook, you need to add it to an app or a permission for it to run. See📄 Creating Webhooks

The diagram below helps you understand when to use an app webhook or a permission webhook. In short, if a user is being approved for a permission, use a permission webhook. For all other cases, use an app webhook.

Configuring an AppStore app provisioning webhook

Make sure you set up the webhook at the right layer (app or permission). Guidance is here:📄 Provisioning Webhooks

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 Provisioning Webhook dropdown.

Configuring an AppStore permission provisioning webhook

Make sure you set up the webhook at the right layer (app or permission). Guidance is here:📄 Provisioning Webhooks

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 Provisioning Webhook dropdown.

Example workflows

At the bottom of this article, you'll find working webhook scripts to help you get started with provisioning 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.

Okta Workflow - Lumos Provisioning Webhook Starter.flow