Workflow API Security

The Security component of the Workflow API allows you to add authorization and authentication to the Workflow API endpoints. It uses the ASP.NET framework to specify requirements for certain claims in the claim principal. Each endpoint and group of endpoints has its own permission, allowing for highly customizable access control. You can use any security schema implementation, such as JWT Bearer, Cookie-based, or custom implementations.

info

To integrate the Security component, you need to first include the Core and Data components.

Integration

The Security component is included in the Core NuGet package, which you should have already added when integrating the Core component.

The Security component is added during the web application's builder stage using an extension method for the service provider. You can also configure its options:

builder.Services.AddWorkflowApiSecurity(options =>
{
    // Configure the Workflow Engine API Security options.
    options.DisableSecurity = false;
    options.SecurityScheme = null;
});

That's it, you've integrated the Workflow API Security component. By default, it will use the SecurityScheme set as the default scheme when configuring ASP.NET authentication services. This typically looks like this:

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "YourScheme";
});

Options

Name	Type	Default	Description
DisableSecurity	bool	false	Allows disabling authentication and authorization. By default, authentication and authorization are enabled when adding AddWorkflowApiSecurity().
SecurityScheme	string?	null	The authentication scheme used for Workflow Engine API endpoints. When null, the default authentication scheme set in AuthenticationOptions will be used.

Claim Generation

To work with the Workflow API in security-enabled mode, you need to go through authentication and authorization. Authorization is conducted by verifying the appropriate claims in the Claim Principal. The claim structure is internally defined and essentially represents a list of claims that allow access to specific endpoints.

You can obtain this set of claims using the IWorkflowApiPermissions service, which provides methods to generate claims or privileges as an array of claims or strings. You can find a detailed example of Security implementation based on JWT Bearer in our GitHub Sample.

Typically, the code for using the Permissions service looks like this:

string[] permissions = ["workflow-api.health", "workflow-api.data.schemes.get-collection", "workflow-api.data.schemes.get"];
var claims = Permissions.AllowList(permissions);

In this example, we generate claims that allow access to the Health method and all get methods in Schemes controller.

To allow all endpoints, you can use:

var claims = WorkflowApiPermissions.AllowAll();

You can also obtain a list of all permissions instead of ready-made claims, filter or store them, and then use them as an allow list elsewhere in the code.

var permissions = Permissions
    .GetAllPermissions()
    .Where(permission => permission.StartsWith("workflow-api.search"));

var claims = Permissions.AllowList(permissions);

Permission List

Permissions in the Workflow Engine API are organized in a tree structure, where each node represents either a final endpoint or a group of endpoints and other groups. However, when generating claims, only the final list of endpoints, not groups, is allowed. That said, you can configure filtering by groups within your own logic. Below is a list of all existing permissions for all endpoints.

WorkflowApi API

• workflow-api.health — Check the health of internal API services.

Search API

• workflow-api.search.runtimes — Search runtimes.
• workflow-api.search.global-parameters — Search global parameters.
• workflow-api.search.schemes — Search schemes.
• workflow-api.search.statuses — Search process statuses.
• workflow-api.search.processes — Search processes.
• workflow-api.search.processes.parameters — Search process parameters.
• workflow-api.search.processes.timers — Search process timers.
• workflow-api.search.processes.transitions — Search process transitions.
• workflow-api.search.processes.approvals — Search process approvals.
• workflow-api.search.processes.inbox-entries — Search process inbox entries.

Data API

Runtimes

• workflow-api.data.runtimes.get-collection — Get runtime collection.
• workflow-api.data.runtimes.get — Get runtime.

Global Parameters

• workflow-api.data.global-parameters.get-collection — Get global parameters collection.
• workflow-api.data.global-parameters.create-collection — Create global parameters collection.
• workflow-api.data.global-parameters.delete-collection — Delete global parameters collection.
• workflow-api.data.global-parameters.get — Get global parameter.
• workflow-api.data.global-parameters.create — Create global parameter.
• workflow-api.data.global-parameters.update — Update global parameter.
• workflow-api.data.global-parameters.delete — Delete global parameter.

Schemes

• workflow-api.data.schemes.get-collection — Get schemes collection.
• workflow-api.data.schemes.create-collection — Create schemes collection.
• workflow-api.data.schemes.delete-collection — Delete schemes collection.
• workflow-api.data.schemes.get — Get scheme.
• workflow-api.data.schemes.create — Create scheme.
• workflow-api.data.schemes.update — Update scheme.
• workflow-api.data.schemes.delete — Delete scheme.

Statuses

• workflow-api.data.statuses.get-collection — Get statuses collection.
• workflow-api.data.statuses.get — Get status.

Processes

• workflow-api.data.processes.get-collection — Get processes collection.
• workflow-api.data.processes.get — Get process.
• workflow-api.data.processes.update — Update process.

Process Parameters

• workflow-api.data.processes.parameters.get-collection — Get process parameters collection.
• workflow-api.data.processes.parameters.create-collection — Create process parameters collection.
• workflow-api.data.processes.parameters.delete-collection — Delete process parameters collection.
• workflow-api.data.processes.parameters.get — Get process parameter.
• workflow-api.data.processes.parameters.create — Create process parameter.
• workflow-api.data.processes.parameters.update — Update process parameter.
• workflow-api.data.processes.parameters.delete — Delete process parameter.

Process Timers

• workflow-api.data.processes.timers.get-collection — Get process timers collection.
• workflow-api.data.processes.timers.create-collection — Create process timers collection.
• workflow-api.data.processes.timers.delete-collection — Delete process timers collection.
• workflow-api.data.processes.timers.get — Get process timer.
• workflow-api.data.processes.timers.create — Create process timer.
• workflow-api.data.processes.timers.update — Update process timer.
• workflow-api.data.processes.timers.delete — Delete process timer.

Process Transitions

• workflow-api.data.processes.transitions.get-collection — Get process transitions collection.
• workflow-api.data.processes.transitions.delete-collection — Delete process transitions collection.
• workflow-api.data.processes.transitions.get — Get process transition.
• workflow-api.data.processes.transitions.delete — Delete process transition.

Process Approvals

• workflow-api.data.processes.approvals.get-collection — Get process approvals collection.
• workflow-api.data.processes.approvals.delete-collection — Delete process approvals collection.
• workflow-api.data.processes.approvals.get — Get process approval.
• workflow-api.data.processes.approvals.delete — Delete process approval.

Process Inbox Entries

• workflow-api.data.processes.inbox-entries.get-collection — Get process inbox entries collection.
• workflow-api.data.processes.inbox-entries.delete-collection — Delete process inbox entries collection.
• workflow-api.data.processes.inbox-entries.get — Get process inbox entry.
• workflow-api.data.processes.inbox-entries.delete — Delete process inbox entry.

IWorkflowApiPermissions

Service for creating claims with access rights to the Workflow Engine API, as well as for working with permissions.

AllowAll()

Creates an array of claims with access rights to all Workflow Engine API endpoints.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

AllowList(params string[] permissions)

Creates claims with access rights to the Workflow Engine API using permissions as an Allow List.

Parameters

Name	Type	Description
permissions	string[]	An array of permissions to grant access rights.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

AllowList(IEnumerable<string> permissions)

Creates claims with access rights to the Workflow Engine API using permissions as an Allow List.

Parameters

Name	Type	Description
permissions	IEnumerable<string>	An enumeration of permissions to grant access rights.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

DenyAll()

Creates an array of claims without access rights to the Workflow Engine API endpoints.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

DenyList(params string[] permissions)

Creates claims with access rights to the Workflow Engine API using permissions as a Deny List.

Parameters

Name	Type	Description
permissions	string[]	An array of permissions to restrict access rights.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

DenyList(IEnumerable<string> permissions)

Creates claims with access rights to the Workflow Engine API using permissions as a Deny List.

Parameters

Name	Type	Description
permissions	IEnumerable<string>	An enumeration of permissions to restrict access rights.

Returns

Type	Description
Claim[]	An array of claims with access rights to the Workflow Engine API.

GetAllPermissions()

Creates an array containing all possible permissions for the Workflow Engine API.

Returns

Type	Description
string[]	An array of all permissions in the Workflow Engine API.

ValidatePermissions(params string[] permissions)

Validates an array of permissions for the Workflow Engine API.

Parameters

Name	Type	Description
permissions	string[]	An array of permissions for validation.

Returns

Type	Description
bool	A boolean value indicating whether the permissions are valid.

ValidatePermissions(IEnumerable<string> permissions)

Validates a permissions enumerable for the Workflow Engine APIe.

Parameters

Name	Type	Description
permissions	IEnumerable<string>	An enumeration of permissions for validation.

Returns

Type	Description
bool	A boolean value indicating whether the permissions are valid.