Workflow API Security

The Security component of the Workflow API allows you to add authorization and authentication to the Workflow API operations. It uses the ASP.NET framework to specify requirements for certain claims in the claim principal. Each operation 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";
});

Security Options

You can configure the Security component options using the WorkflowApiSecurityOptions record provided as ASP.NET IOptions in the service collection. Below is a table describing its properties:

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 operations. 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 operations.

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.liveness", "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 Liveness operation and all get operations in Schemes controller.

To allow all operations, 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 an operation identifier or a group of operations. However, when generating claims, only the final list of operations identifiers, not groups, is allowed. That said, you can configure filtering by groups within your own logic. Below is a list of all existing operation identifiers.

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.

RPC API

Bulk API

• workflow-api.rpc.bulk-create-instance — Create multiple process instances.
• workflow-api.rpc.bulk-get-process-instance — Get multiple process instances with parameters.
• workflow-api.rpc.bulk-get-process-instances-tree — Get multiple root process instances with all subprocesses as trees.
• workflow-api.rpc.bulk-get-available-commands — Get multiple lists of commands available for current activities and identities.
• workflow-api.rpc.bulk-execute-command — Execute multiple commands with specified identity.
• workflow-api.rpc.bulk-update-scheme-if-obsolete — Update multiple schemes of process instances if they are obsolete.
• workflow-api.rpc.bulk-delete-instance — Delete multiple process instances with all their subprocesses.
• workflow-api.rpc.bulk-is-process-exists — Check existence of multiple process instances.

Commands API

• workflow-api.rpc.get-available-commands — Get the list of commands available for current activity and identities.
• workflow-api.rpc.execute-command — Execute command with specified identity.
• workflow-api.rpc.get-initial-commands — Get the list of commands available for initial activity and identities.

Instance API

• workflow-api.rpc.create-instance — Create instance of the process.
• workflow-api.rpc.delete-instance — Delete process instance and all child subprocesses.
• workflow-api.rpc.is-process-exists — Check existence of the process instance.
• workflow-api.rpc.get-process-instance-tree — Get the root process instance and all subprocesses as a tree.
• workflow-api.rpc.get-process-instance — Get the process instance with all parameters.
• workflow-api.rpc.get-process-history — Get the history records for the process instance.
• workflow-api.rpc.get-process-history-count — Get the count of history records for the process instance.
• workflow-api.rpc.set-process-new-status — Set a new status for the process instance.
• workflow-api.rpc.get-process-status — Get the status of the process instance.
• workflow-api.rpc.delete-all-subprocesses — Delete all subprocesses of the process instance.
• workflow-api.rpc.check-all-subprocesses-completed — Check if all subprocesses of the process instance are completed.
• workflow-api.rpc.set-process-parameter — Set the value of a process parameter with persistence purpose.
• workflow-api.rpc.get-process-parameter — Get the value of a process parameter.

Log API

• workflow-api.rpc.log-debug — Logs a debug message with parameters.
• workflow-api.rpc.log-debug-if-logger-exists — Logs a debug message with parameters if the logger exists.
• workflow-api.rpc.log-info — Logs an info message with parameters.
• workflow-api.rpc.log-info-if-logger-exists — Logs an info message with parameters if the logger exists.
• workflow-api.rpc.log-error — Logs an error message with parameters.
• workflow-api.rpc.log-error-if-logger-exists — Logs an error message with parameters if the logger exists.

Pre-Execution API

• workflow-api.rpc.pre-execute-from-initial-activity — Pre-execute from the initial activity of the process instance.
• workflow-api.rpc.pre-execute-from-current-activity — Pre-execute from the current activity of the process instance.
• workflow-api.rpc.pre-execute — Pre-execute from the specified activity of the process instance.

Runtime API

• workflow-api.rpc.runtime-shut-down — Shuts down the workflow runtime.
• workflow-api.rpc.runtime-start — Starts the workflow runtime.
• workflow-api.rpc.runtime-cold-start — Starts the workflow runtime in cold start mode.
• workflow-api.rpc.runtime-get-status — Gets the status of the workflow runtime.

Scheme API

• workflow-api.rpc.get-scheme-codes — Get scheme codes with optional filtering by tags.
• workflow-api.rpc.set-scheme-is-obsolete — Set all process schemes with the specified scheme code as obsolete.
• workflow-api.rpc.update-scheme-if-obsolete — Update scheme of the process instance if it is obsolete.
• workflow-api.rpc.get-process-scheme — Get the scheme of the process instance.

State API

• workflow-api.rpc.get-available-states-to-set — Get the list of all available to set states for the process instance.
• workflow-api.rpc.get-available-states-to-set-by-scheme-code — Get the list of all available to set states for the scheme.
• workflow-api.rpc.set-state-without-execution — Set state for the process instance without execution.
• workflow-api.rpc.set-state-with-execution — Set state for the process instance with execution.
• workflow-api.rpc.set-activity-without-execution — Set activity for the process instance without execution.
• workflow-api.rpc.set-activity-with-execution — Set activity for the process instance with execution.
• workflow-api.rpc.resume — Resumes the process instance execution.
• workflow-api.rpc.get-current-state-name — Get the current state name of the process instance.
• workflow-api.rpc.get-current-activity-name — Get the current activity name of the process instance.
• workflow-api.rpc.get-current-state — Get the current state of the process instance.
• workflow-api.rpc.get-initial-state — Get the initial state of the scheme.

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 operations.

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 operations.

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.