StellaOps.Workflow.AspNetCore
HTTP endpoints of the workflow engine for an ASP.NET Core host, with standard ASP.NET Core authentication and authorization.
| Package | StellaOps.Workflow.AspNetCore |
| Component | Workflow |
| Licence | BUSL-1.1 (Workflow licence) |
| Package kind | Library |
| Target framework | net10.0 |
To add the package to a project, see Installing Stella Ops packages.
Namespaces
| Namespace | Types |
|---|---|
StellaOps.Workflow.AspNetCore | 11 |
StellaOps.Workflow.AspNetCore namespace
| Type | Kind | Description |
|---|---|---|
ClaimsWorkflowActorRoleResolver | class | The actor resolver that AddWorkflowAuthorization registers in place of the engine’s pass-through NullWorkflowActorRoleResolver. |
WorkflowActorClaimOptions | class | The claims of the authenticated principal that identify the actor of a task operation: the actor ID and the actor’s roles. |
WorkflowAspNetCoreServiceCollectionExtensions | class | Service registration for the Workflow endpoints. |
WorkflowEndpointOperation | class | Endpoint metadata on each state-changing Workflow endpoint: the operation it performs and the kind of resource it changes. |
WorkflowEndpoints | class | The Workflow HTTP surface: every business endpoint under the /api/workflow route group. |
WorkflowErrorResponse | record | The body of a refused Workflow request: the engine’s message id and its message. |
WorkflowHealthResponseWriter | class | 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). |
WorkflowPolicies | class | Named authorization policy constants and registration for the Workflow endpoints. |
WorkflowScopeRequirement | class | An any-of scope requirement: the user holds at least one of WorkflowScopeRequirement.RequiredScopesin a scope or scp claim. |
WorkflowTaskAssignBody | record | The body of POST /api/workflow/tasks/{id}/assign. |
WorkflowTaskCompleteBody | record | The 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
operation: One of the operation constants of this class.resourceType: The kind of resource changed, for exampleworkflow_task.
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
Error: The message id, such asWorkflowActorUnresolved.Message: The message.
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: The message id, such asWorkflowActorUnresolved.Message: The message.
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
context: The HTTP context.report: The health report.
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.*.
