StellaOps.Workflow.AspNetCore

HTTP endpoints of the workflow engine for an ASP.NET Core host, with standard ASP.NET Core authentication and authorization.

PackageStellaOps.Workflow.AspNetCore
ComponentWorkflow
LicenceBUSL-1.1 (Workflow licence)
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Workflow.AspNetCore11

StellaOps.Workflow.AspNetCore namespace

TypeKindDescription
ClaimsWorkflowActorRoleResolverclassThe actor resolver that AddWorkflowAuthorization registers in place of the engine’s pass-through NullWorkflowActorRoleResolver.
WorkflowActorClaimOptionsclassThe claims of the authenticated principal that identify the actor of a task operation: the actor ID and the actor’s roles.
WorkflowAspNetCoreServiceCollectionExtensionsclassService registration for the Workflow endpoints.
WorkflowEndpointOperationclassEndpoint metadata on each state-changing Workflow endpoint: the operation it performs and the kind of resource it changes.
WorkflowEndpointsclassThe Workflow HTTP surface: every business endpoint under the /api/workflow route group.
WorkflowErrorResponserecordThe body of a refused Workflow request: the engine’s message id and its message.
WorkflowHealthResponseWriterclassWrites the readiness report as JSON: the overall status and, per entry, its status, description and data (a nested string-keyed dictionary as an object).
WorkflowPoliciesclassNamed authorization policy constants and registration for the Workflow endpoints.
WorkflowScopeRequirementclassAn any-of scope requirement: the user holds at least one of WorkflowScopeRequirement.RequiredScopesin a scope or scp claim.
WorkflowTaskAssignBodyrecordThe body of POST /api/workflow/tasks/{id}/assign.
WorkflowTaskCompleteBodyrecordThe body of POST /api/workflow/tasks/{id}/complete.

ClaimsWorkflowActorRoleResolver class

public sealed class ClaimsWorkflowActorRoleResolver : IWorkflowActorRoleResolver

The actor resolver that AddWorkflowAuthorization registers in place of the engine’s pass-through NullWorkflowActorRoleResolver. Inside an HTTP request the actor ID and the roles come from the authenticated principal only (WorkflowActorClaimOptions); the actor and roles the caller supplied are ignored, and a principal that is not authenticated or carries no actor ID claim has no actor and no roles. Outside an HTTP request (the signal pump, hosted services, other server-side callers) there is no principal, and the values the server-side caller passes are used as they are.

ClaimsWorkflowActorRoleResolver(IHttpContextAccessor, IOptions<WorkflowActorClaimOptions>) constructor

public ClaimsWorkflowActorRoleResolver(IHttpContextAccessor httpContextAccessor, IOptions<WorkflowActorClaimOptions> options)

The actor resolver that AddWorkflowAuthorization registers in place of the engine’s pass-through NullWorkflowActorRoleResolver. Inside an HTTP request the actor ID and the roles come from the authenticated principal only (WorkflowActorClaimOptions); the actor and roles the caller supplied are ignored, and a principal that is not authenticated or carries no actor ID claim has no actor and no roles. Outside an HTTP request (the signal pump, hosted services, other server-side callers) there is no principal, and the values the server-side caller passes are used as they are.

ResolveActorId(string) method

public string ResolveActorId(string? clientActorId)

Returns the actor ID for the current request. Implementations should prefer server-side identity over client-supplied values.

ResolveActorRolesAsync(string, IReadOnlyCollection<string>, CancellationToken) method

public Task<IReadOnlyCollection<string>> ResolveActorRolesAsync(string actorId, IReadOnlyCollection<string>? clientRoles, CancellationToken cancellationToken = default)

Resolves user roles from a trusted source (database, identity provider). Falls back to clientRoles when no server-side context is available (e.g., during signal pump processing).

WorkflowActorClaimOptions class

public sealed class WorkflowActorClaimOptions

The claims of the authenticated principal that identify the actor of a task operation: the actor ID and the actor’s roles. The Workflow endpoints and ClaimsWorkflowActorRoleResolverread them; the actor and roles in a request body or query are not used. AddWorkflowAuthorization binds the section WorkflowActorClaimOptions.SectionNameof the host configuration when one is registered.

WorkflowActorClaimOptions() constructor

public WorkflowActorClaimOptions()

Creates an instance of WorkflowActorClaimOptions.

SectionName constant

public const string SectionName = "WorkflowAuthorization"

The configuration section bound by AddWorkflowAuthorization.

ActorIdClaimTypes property

public List<string> ActorIdClaimTypes { get; set; }

Claim types read for the actor ID, in order; the first non-blank value wins. Empty means WorkflowActorClaimOptions.DefaultActorIdClaimTypes. A non-empty list replaces the defaults.

DefaultActorIdClaimTypes property

public static IReadOnlyList<string> DefaultActorIdClaimTypes { get; }

The actor ID claim types used when WorkflowActorClaimOptions.ActorIdClaimTypesis empty: sub, then the name identifier claim.

DefaultRoleClaimTypes property

public static IReadOnlyList<string> DefaultRoleClaimTypes { get; }

The role claim types used when WorkflowActorClaimOptions.RoleClaimTypesis empty: the role claim and role.

RoleClaimTypes property

public List<string> RoleClaimTypes { get; set; }

Claim types read for the actor’s roles; every non-blank value of every listed type is a role. Empty means WorkflowActorClaimOptions.DefaultRoleClaimTypes. A non-empty list replaces the defaults.

WorkflowAspNetCoreServiceCollectionExtensions class

public static class WorkflowAspNetCoreServiceCollectionExtensions

Service registration for the Workflow endpoints.

AddWorkflowAuthorization(IServiceCollection) extension method

public static IServiceCollection AddWorkflowAuthorization(this IServiceCollection services)

Registers the named Workflow policies (WorkflowPolicies) and the handler of WorkflowScopeRequirement. Authentication stays with the host: register any ASP.NET Core scheme that puts the caller’s scopes in scope or scp claims. Also registers ClaimsWorkflowActorRoleResolverin place of the engine’s pass-through resolver (a resolver the host registered itself is kept), and binds WorkflowActorClaimOptionsfrom the WorkflowActorClaimOptions.SectionNamesection of the host configuration. Safe to call more than once, before or after the engine’s registration.

AddWorkflowAuthorization(IServiceCollection, Action<WorkflowActorClaimOptions>) extension method

public static IServiceCollection AddWorkflowAuthorization(this IServiceCollection services, Action<WorkflowActorClaimOptions> configureActorClaims)

WorkflowAspNetCoreServiceCollectionExtensions.AddWorkflowAuthorization(IServiceCollection), then applies configureActorClaims to the claim types that identify the actor.

WorkflowEndpointOperation class

public sealed class WorkflowEndpointOperation

Endpoint metadata on each state-changing Workflow endpoint: the operation it performs and the kind of resource it changes. The package emits no audit record itself; a host reads this entry (endpoint.Metadata.GetMetadata<WorkflowEndpointOperation>()) to attach its own audit, telemetry or rate limits. Read-only endpoints carry none.

WorkflowEndpointOperation(string, string) constructor

public WorkflowEndpointOperation(string operation, string resourceType)

Creates the metadata entry.

Parameters

ActivateDefinition constant

public const string ActivateDefinition = "activate_definition"

POST /api/workflow/definitions/{name}/activate.

AssignTask constant

public const string AssignTask = "assign_task"

POST /api/workflow/tasks/{id}/assign.

CompleteTask constant

public const string CompleteTask = "complete_task"

POST /api/workflow/tasks/{id}/complete.

ImportDefinition constant

public const string ImportDefinition = "import_definition"

POST /api/workflow/definitions/import.

ImportDefinitionMulti constant

public const string ImportDefinitionMulti = "import_definition_multi"

POST /api/workflow/definitions/import-multi.

RaiseSignal constant

public const string RaiseSignal = "raise_signal"

POST /api/workflow/signals/raise.

ReleaseTask constant

public const string ReleaseTask = "release_task"

POST /api/workflow/tasks/{id}/release.

ReplayDeadLetters constant

public const string ReplayDeadLetters = "replay_dead_letters"

POST /api/workflow/signals/dead-letters/replay.

RunRetention constant

public const string RunRetention = "run_retention"

POST /api/workflow/retention/run.

StartInstance constant

public const string StartInstance = "start_instance"

POST /api/workflow/start.

Operation property

public string Operation { get; }

The operation, for example WorkflowEndpointOperation.StartInstance.

ResourceType property

public string ResourceType { get; }

The kind of resource the operation changes.

WorkflowEndpoints class

public static class WorkflowEndpoints

The Workflow HTTP surface: every business endpoint under the /api/workflow route group. Each endpoint requires one of the named policies of WorkflowPolicies(register them with AddWorkflowAuthorization); the host chooses the authentication scheme. Each state-changing endpoint carries a WorkflowEndpointOperationmetadata entry that a host can use to attach its own audit or telemetry. Identity comes from the authenticated principal, never from the request: the actor ID and the roles are read from its claims (WorkflowActorClaimOptions). The task and instance endpoints act as that actor, the definition import and activation record it in the definition audit (importedBy, actorId), and a workflow started, continued or signalled over HTTP calls services as it (WorkflowExecutionActorContext.CallerUserId). The actorId, actorRoles and importedBy of a request body or query are not used. A task operation or definition change by a principal without an actor ID claim, and a task operation the task authorization denies, are answered with 403. An expected refusal of the engine or of the definition store is answered with its status and a WorkflowErrorResponsebody: 404 for a definition, instance or task that does not exist, 403 for a denied action, 409 for a conflict (a completed, expired or cancelled task, a lost activation fence, an operation the instance’s runtime provider does not support), 400 for an invalid request.

Remarks

The class name is part of the published API description: minimal-API operations take the declaring type of their handler as their OpenAPI tag (WorkflowEndpoints).

MapWorkflowEndpoints(IEndpointRouteBuilder) extension method

public static RouteGroupBuilder MapWorkflowEndpoints(this IEndpointRouteBuilder app)

Maps the Workflow business endpoints under /api/workflow and returns the group, so the host can add its own conventions (filters, metadata, rate limits).

WorkflowErrorResponse record

public sealed record WorkflowErrorResponse

The body of a refused Workflow request: the engine’s message id and its message. The endpoints answer an expected refusal with this body and a 4xx status (404 not found, 403 denied, 409 conflict, 400 invalid request), never with 500.

Parameters

WorkflowErrorResponse(string, string) constructor

public WorkflowErrorResponse(string Error, string Message)

The body of a refused Workflow request: the engine’s message id and its message. The endpoints answer an expected refusal with this body and a 4xx status (404 not found, 403 denied, 409 conflict, 400 invalid request), never with 500.

Parameters

Error property

public string Error { get; init; }

The message id, such as WorkflowActorUnresolved.

Message property

public string Message { get; init; }

The message.

WorkflowHealthResponseWriter class

public static class WorkflowHealthResponseWriter

Writes the readiness report as JSON: the overall status and, per entry, its status, description and data (a nested string-keyed dictionary as an object). The engine’s licence entry shows the licence status and the licence notice here; it always reports Healthy, so it never changes the readiness result. Use it as the HealthCheckOptions.ResponseWriter of the host’s readiness endpoint.

WriteAsync(HttpContext, HealthReport) method

public static Task WriteAsync(HttpContext context, HealthReport report)

Writes report as the JSON body of the response.

Parameters

Returns

A task that completes when the body is written.

WorkflowPolicies class

public static class WorkflowPolicies

Named authorization policy constants and registration for the Workflow endpoints. Every business endpoint uses a named policy from this class via .RequireAuthorization(WorkflowPolicies.XxxPolicy).

Scope hierarchy (any of these grants access to the corresponding tier): View : workflow:view, workflow:operate, workflow:admin (any one is sufficient) Operate : workflow:operate, workflow:admin (operate implies view) Admin : workflow:admin only

Each policy requires an authenticated user and a WorkflowScopeRequirement, which reads the standard scope claim (space-delimited) and individual scp claims. The requirement exposes its scopes, so a gateway that maps authorization metadata to claim requirements can enforce the same rule.

Admin constant

public const string Admin = "workflow.admin"

Policy for engine-admin operations (definition deploy/activate, retention, dead-letter replay).

AdminScope constant

public const string AdminScope = "workflow:admin"

Scope granting permission to deploy/activate definitions, run retention, replay dead letters.

Operate constant

public const string Operate = "workflow.operate"

Policy for runtime mutations (start/complete/assign/release/signal).

OperateScope constant

public const string OperateScope = "workflow:operate"

Scope granting permission to start workflows, complete/assign/release tasks, raise signals.

ScopeClaimType constant

public const string ScopeClaimType = "scope"

The OAuth claim holding space-delimited scopes.

ScopeItemClaimType constant

public const string ScopeItemClaimType = "scp"

The claim holding one scope per claim.

View constant

public const string View = "workflow.view"

Policy for read-only access to workflow data.

ViewScope constant

public const string ViewScope = "workflow:view"

Scope granting read-only access to workflow definitions, instances, tasks, signals.

Configure(AuthorizationOptions) method

public static void Configure(AuthorizationOptions options)

Registers the three named policies into the authorization options. Hosts normally call services.AddWorkflowAuthorization(), which also registers the requirement’s handler.

WorkflowScopeRequirement class

public sealed class WorkflowScopeRequirement : IAuthorizationRequirement

An any-of scope requirement: the user holds at least one of WorkflowScopeRequirement.RequiredScopesin a scope or scp claim. The scopes are public so that an authorization-metadata mapper (for example a gateway that forwards a service’s policies as claim requirements) can read them; WorkflowScopeRequirement.RequireAllScopesis false, so such a mapper emits one any-of rule. Evaluated by the handler that AddWorkflowAuthorization registers.

WorkflowScopeRequirement(params string[]) constructor

public WorkflowScopeRequirement(params string[] scopes)

Creates the requirement; at least one non-blank scope is required.

RequireAllScopes property

public bool RequireAllScopes { get; }

Always false: one of the scopes is enough.

RequiredScopes property

public IReadOnlyCollection<string> RequiredScopes { get; }

The scopes, any one of which satisfies the requirement (ordinal order).

WorkflowTaskAssignBody record

public sealed record WorkflowTaskAssignBody

The body of POST /api/workflow/tasks/{id}/assign. The route names the task and the authenticated principal is the actor. Without a target the task is assigned to the principal; the body is optional.

WorkflowTaskAssignBody() constructor

public WorkflowTaskAssignBody()

Creates an instance of WorkflowTaskAssignBody.

TargetRoles property

public IReadOnlyCollection<string> TargetRoles { get; init; }

The role groups to assign the task to instead of a user.

TargetUserId property

public string? TargetUserId { get; init; }

The user to assign the task to; empty assigns it to the principal.

WorkflowTaskCompleteBody record

public sealed record WorkflowTaskCompleteBody

The body of POST /api/workflow/tasks/{id}/complete. The route names the task and the authenticated principal is the actor, so the body carries only the completion payload. The body is optional; a body that also sends workflowTaskId, actorId or actorRoles is accepted and those members are not used.

WorkflowTaskCompleteBody() constructor

public WorkflowTaskCompleteBody()

Creates an instance of WorkflowTaskCompleteBody.

Payload property

public IDictionary<string, object?> Payload { get; init; }

The completion payload, which the task’s completion steps read as payload.*.