Documentation

Approval workflows

Suggest Edits

Overview

Approval workflows in Entitle define the Just-in-Time (JIT) permissions approval process. This process activates when a user requests permissions and runs before those permissions are granted (pending approval). A workflow specifies the approval sequence, approvers, recipients, and duration of access. Once defined, a workflow can be applied to multiple components of the JIT permissions process: integrations, resources, roles, and bundles.

What are approval workflows?

  • Each approval workflow consists of multiple rules, and each rule has two parts: a condition ("if" section) and an approval process ("then" section).
  • The approval process can include multiple steps. Each step defines who can approve the access request—a person, group, or automated code—and who receives notifications after approval.
  • Rule order within a workflow is crucial because the first rule whose condition is met ("if" section) determines the approval process for the permission request.

Approval workflows screen

This screen has three main functionalities:

  1. View and manage existing approval workflows
  2. Set up new approval workflows
  3. Set up approval processes outside of Entitle’s options using webhooks

Key Terms and components

This section explains the key terms and components needed to set up or edit an approval workflow.

Choose the “Or"/“Any” operator for each approval step

Any approval step can be with an “Or” operator or “Any” operator and you can have multiple approval steps.

💡

It is recommended to avoid using specific named approvers when possible. Instead, use abstract approvers, groups, or role names.

Approver types

  • Direct Manager: The manager of the user requesting access. For requests made on behalf of another user, this refers to the manager of the user receiving access.
  • Integration Owner: The owner of an integration. For bundles, this means the owner of each included integration.
  • Integration Maintainer: A secondary administrator of the integration. Multiple maintainers can be assigned, including IDP groups. For bundles, this refers to the maintainers of each integration.
  • Resource Owner: The owner of a resource. For bundles, this means the owner of each included resource.
  • Resource Maintainer: A secondary administrator of the resource. Multiple maintainers can be assigned, including IdP groups. For bundles, this refers to the maintainers of each resource.
  • Automatic Approval: The request is approved automatically.
  • Team Member: Any user who shares the same direct manager as the user requesting access. For requests made on behalf of others, this refers to users sharing the manager of the recipient. If no direct manager exists, any Entitle Admin can approve.
  • Group: Any member of an IdP group at the time of request. Members cannot approve their requests. If someone requests access on behalf of another user and belongs to the approval group, the step is automatically approved.
  • Specific user: Any user in your tenant.
  • Schedules: Any member of an on-call schedule. Members cannot approve their requests. If someone requests access on behalf of another user and is currently on-call, the step is automatically approved.
  • Webhooks: Third-party code that approves the step. See below for details.

💡

On-call access clarification

  • When using Team or Schedule in the workflow, access requests are restricted to users who are currently On-Call. This design ensures that only active responders can request access.
  • To allow all schedule members (not just on-call users) to request access, create a group containing all schedule members and use that group in the workflow.

View and manage approval workflows

  1. Log into Entitle and navigate to the Approval workflows screen.

  2. Your organization’s existing approval workflows in Entitle can be found here. You can perform two main actions on the existing workflows:

    1. Edit approval workflow details (name, “if”/”then” sections, add new roles/change their order using the arrows on the left of any rule, and add a new step to a rule).

      Note: Remember to click Save approval workflow once you edit the workflow.

    2. Delete an approval workflow: Click the according button and in the pop-up window click Delete once again.

Set up a new approval workflow

  1. Log into Entitle and navigate to the Approval workflows screen.

  2. Click New approval workflow.

  3. Choose a name for your workflow, define the rules that determine when it applies and their order, and set up the approval process. Once done, click Save approval workflow.

    The newly created approval workflow will appear on the Approval workflows main screen.

Approval by your code

Approval workflows support both third-party code approvals and webhook notifications. Approval by workflow allows you to extend Entitle's built-in approver types with your organization's specific approval mechanisms, such as customer approvals or certification services.

Follow the steps below to approve Entitle requests by code:

  1. Log into Entitle and navigate to the Approval workflows screen.

  2. Click Approval by webhook.

  3. Click Add webhook, and insert your webhook details.


    • URL - Insert your webhook URL. Make sure it adheres to the Approval webhook structure.
    • Headers - Any value set in this field will be added to the request header 'as is'.
    • Additional Parameters - Any value set in this field will be added to the request body 'as is'.
      Note that the following keys are forbidden: stageNumber, stageAmount, token, and accessRequest.

  4. In the relevant workflow definition, add the registered webhook as either an approver or for notification, then click Save workflow. The example below shows both configurations (indicated by the webhook icon).

  5. When called, perform the custom approval logic within the webhook code and then call the Approval webhook response API.

Approval webhook structure

The approval webhook uses the following structure:

{  
  stageNumber: 1,  
  stageAmount: 3,  
  accessRequest: {  
    behalfOf: {  
      id: "51907709-306b-4587-a89a-4c1a3f8d081f",  
      email: "[[email protected]](mailto:[email protected])",  
    },  
    duration: 15768000,  
    id: "054283fe-f1b4-4bdc-b54e-2adba50f079a",  
    justification: "I need it",  
    number: 114,  
    roles: [  
      {  
        isPrerequisite: false,  
        id: "a7b1e5be-d2bb-4891-a446-406b74ba7b3f",  
        name: "role1",  
        resource: {  
          id: "f40d54f4-1483-431f-bbe1-ce6e19a792eb",  
          name: "resource 1 name",  
          integration: {  
            id: "e5eb6b93-5735-4a65-97fc-5f11e29b9566",  
            name: "manuella",  
            application: {  
              name: "Manual",  
            },  
          },  
        },  
      },  
    ],  
    status: "waitingForApproval",  
    targets: [  
      {  
        type: "role",  
        role: {  
          id: "a7b1e5be-d2bb-4991-a446-406b74ba7b3f",  
          name: "requested role",  
        },  
      },  
    ],  
    user: {  
      id: "51907709-306b-4587-a89a-4c1a3f8d081f",  
      email: "[[email protected]](mailto:[email protected])",  
    },  
  },  
  token: "some string",  
}
  • stageNumber - The current approval step.
  • stageAmount- The total number of approval steps for the access request.
  • token - A unique identifier used to authenticate and link a specific webhook workflow request with its corresponding response. This token is only required when the webhook acts as an approver, not when it's used for notifications.
  • accessRequest - The access request details.

Approval webhook response

Approval webhook response, whether the access request was approved or not, is HTTP Put request for the route here.

The response should include the following parameters:

  • Type - "approve" | "decline"
  • Token - The token received in the approval webhook

CURL:

curl -X POST <https://api.entitle.io/webhooks/v1/approvalRequests/reply>  
-H "Content-Type: application/json"  
-d '{  
    "type": "approve" | "decline",  
    "token": "token received from webhook data"  
}'

🚧

Webhooks availability

When Entitle fails to send multiple HTTP requests to a registered webhook, the webhook becomes disabled and remains inactive until reactivated. During this time, all new webhook calls are redirected to Entitle administrators instead of the disabled webhook.

Updated about 18 hours ago