elsa-core/doc/wiki/identity-tenancy-security.md

Identity, Tenancy, And Security

Elsa security and tenancy are split across identity, SAS token, tenant, tenant HTTP routing, API authorization, and persistence packages.

Identity

Start in src/modules/Elsa.Identity.

IdentityFeature registers:

• identity token options
• API key options
• users, applications, and roles options
• memory stores for users, applications, and roles
• user, application, and role providers
• user and role managers
• secret hashing
• access token issuing
• API key generation/parsing
• tenant resolvers based on claims and current user
• FastEndpoints assembly

Identity supports store-based providers, configuration-based providers, and admin bootstrap providers.

Authentication

DefaultAuthenticationFeature wires default authentication. The reference server calls:

elsa
    .UseIdentity(...)
    .UseDefaultAuthentication();

See src/apps/Elsa.Server.Web/Program.cs.

Identity JWTs include a token_use claim. API bearer authentication accepts only access tokens (token_use=access), while /identity/refresh-token uses a dedicated refresh-token bearer scheme and accepts only refresh tokens (token_use=refresh). Clients should not send refresh tokens to normal API endpoints or access tokens to the refresh endpoint.

JWT signing keys must be configured with a secure random value before production startup. Missing keys, weak keys shorter than 32 ASCII characters, and known public defaults are rejected by options startup validation. Known public defaults are only tolerated in the explicit Development or Demo environments for local/demo hosts. Use environment variables or a secrets manager, such as Identity__Tokens__SigningKey for code-first hosts or CShells__Shells__Default__Features__Identity__SigningKey for shell-based hosts.

Default Admin Bootstrap

The default admin bootstrap is documented in src/modules/Elsa.Identity/README.md and ADR 0010.

Key points:

• It creates initial admin role/user idempotently.
• It is recommended for initial identity access.
• Do not keep development defaults in production.
• Shell-based configuration uses DefaultAdminUser shell feature.
• Code-first configuration uses identity.UseDefaultAdmin(...).

SAS Tokens

SasTokensFeature registers data protection and ITokenService. Workflow API depends on SAS tokens. The default data protection application name is Elsa Workflows.

Use SAS tokens for protected links or temporary access flows where the API expects signed token semantics.

Tenancy

Start in src/modules/Elsa.Tenants.

Key features:

• TenantsFeature: enables tenant resolution pipeline, tenant options, and tenant resolver services.
• TenantManagementFeature: registers tenant store, defaulting to memory.
• TenantManagementEndpointsFeature: exposes tenant management endpoints.

Tenant providers:

• configuration-based tenants provider
• store-based tenants provider

The reference server enables configuration-based tenants and a custom tenant resolver pipeline using CurrentUserTenantResolver.

ASP.NET Core Tenant Routing

Elsa.Tenants.AspNetCore integrates tenants with HTTP routing.

MultitenantHttpRoutingFeature:

• is a dependency of HttpFeature and TenantsFeature
• configures HTTP endpoint routes and base path providers to use tenant prefixes
• registers route-prefix, header, and host tenant resolvers
• lets hosts configure tenant header and HTTP tenancy options

This feature is important when HTTP workflow routes must be tenant-aware.

Tenant Persistence Conventions

Persistence is tenant-aware through EF Core model/saving handlers and tenant-aware DbContext factory decoration. ADRs explain conventions:

• ADR 0008: Empty String As Default Tenant ID
• ADR 0009: Asterisk Sentinel Value For Tenant-Agnostic Entities

When changing persisted entities, verify tenant ID behavior and default tenant semantics.

API Authorization

Workflow API defines read-only-mode authorization in:

• AuthorizationPolicies
• NotReadOnlyRequirement

Structured logs define diagnostics permissions in StructuredLogsPermissions.

Identity endpoints and user-management endpoints are permission-based; see ADR 0010.

Ingress Rate Limiting

Elsa exposes opt-in ASP.NET Core rate limiting hooks for two ingress surfaces:

• Elsa management API endpoints, through ApiEndpointOptions.RateLimitingPolicyName and UseWorkflowsApiRateLimiting(...).
• Public HTTP workflow trigger routes, through HttpActivityOptions.RateLimitingPolicyName and UseWorkflowsRateLimiting(...).

The reference server registers disabled-by-default fixed-window policies under IngressRateLimiting. Enable them by setting IngressRateLimiting:Enabled to true, then tune the API and HTTP workflow permit/window values for production traffic. Set IngressRateLimiting:RegisterReferencePolicies to false when policy names and policies are supplied externally. Custom hosts should register named policies with services.AddRateLimiter(...), map Elsa API endpoints with MapWorkflowsApi(...), apply the Elsa metadata hooks after endpoint routing has selected endpoints and before the rate limiter middleware, and call app.UseRateLimiter() once in the host pipeline. The Elsa hooks only attach endpoint metadata; ASP.NET Core validates configured policy names when the rate limiter middleware handles matching requests. Leave the option disabled, omit the policy names in custom hosts, or set the reference-server policy options to empty strings to run without Elsa-provided rate limiting. The reference server only assigns its default policy names when Enabled is true.

Security Review Checklist

• Does the endpoint require authentication or a permission?
• Does mutable API behavior honor read-only mode?
• Does the operation need tenant scoping?
• Are exposed API or HTTP workflow trigger routes protected by appropriate ingress rate limiting?
• Does persistence apply tenant ID filters and saving handlers?
• Are bootstrap credentials only for development or secret-managed environments?
• Does any diagnostic/logging feature expose sensitive data without redaction?
• Do token settings use production-grade signing keys and data protection configuration?