Security & Authentication
Comprehensive guide to securing Elsa Server and workflows end-to-end, covering identity, authentication, tokenized resume URLs, CORS, secrets management, and production hardening.
Executive Summary
This guide provides actionable, Elsa-specific security practices for protecting your workflow runtime, API endpoints, and Studio deployments. It focuses on configurations and patterns unique to Elsa Workflows while deferring deep platform-specific topics (OIDC provider setup, full reverse proxy hardening, WAF configuration) to official vendor documentation.
Goals and Scope
What This Guide Covers:
Configuring Identity and Authentication in Elsa Server (
UseIdentity,UseDefaultAuthentication)Securing tokenized bookmark resume URLs (TTL, revocation, rate limiting)
CORS, CSRF, and rate limiting for public-facing endpoints
Secrets management for API keys, database connections, and workflow variables
Network security and TLS requirements
Studio deployment security considerations
Production hardening checklist
What This Guide Defers to Vendor Documentation:
Detailed OIDC provider configuration (Azure AD, Auth0, Keycloak)
Full reverse proxy hardening (Nginx, Traefik, Envoy)
Web Application Firewall (WAF) setup
Infrastructure-as-Code (IaC) security best practices
Advanced certificate management and PKI
For clustering-specific security (distributed lock credentials, database permissions), see Clustering Guide (DOC-015).
Identity & Authentication in Elsa Server
UseIdentity Configuration
Elsa Server's identity system is configured in Program.cs via the UseIdentity extension method. In the 3.7.0 server sample, token options are bound from Identity:Tokens, while users, applications, and roles are provided by configuration-based providers bound from the Identity section.
Reference: src/apps/Elsa.Server.Web/Program.cs in elsa-core
Basic Identity Setup:
Key Configuration Points:
UseIdentity: Registers Elsa's built-in identity systemidentity.TokenOptions: Configures JWT issuer, audience, signing key, and token lifetimesConfiguration-based providers: Load
Users,Applications, andRolesfrom theIdentitysectionUseDefaultAuthentication: Enables JWT bearer and API-key authentication from theAuthorizationheader
Minimal appsettings.json Structure
See examples/appsettings-identity.json for a complete example with placeholders.
API-key clients authenticate with:
Elsa validates the API key against configured applications; store hashed API keys and salts in configuration, not raw API keys.
Elsa API Permission Claims
Elsa API endpoints check the permissions claim. Each claim value must match a permission required by the endpoint, and * grants all Elsa API permissions.
Elsa Identity roles collect permission strings. When Elsa Identity issues a JWT, permissions from the assigned roles are emitted as permissions claims. API-key authentication handlers should add equivalent permissions claims. External IdPs should emit the same claim type or the host should map external roles, groups, or scopes into permissions claims during token validation.
ASP.NET Core policies such as RequireRole("Admin") protect custom host endpoints, pages, or controllers. They do not replace Elsa endpoint permission claims. Elsa endpoint permissions come from endpoint configuration and module constants, not only from shared PermissionNames constants.
Common read-only workflow access uses read:workflow-definitions, read:workflow-instances, and read:activity-execution. Use * only for full administrative access.
Important:
Never commit secrets to source control
Use environment variables or secret managers (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault)
Rotate API keys regularly (every 90 days or per your security policy)
API Key vs JWT/OIDC
API Keys:
Best for: Machine-to-machine communication, CI/CD pipelines, internal services
Pros: Simple to implement, no external dependencies
Cons: No fine-grained scopes, harder to rotate safely
JWT/OIDC:
Best for: User authentication, web applications, mobile apps
Pros: Industry standard, fine-grained scopes, short-lived tokens, refresh token support
Cons: Requires OIDC provider setup and maintenance
Recommendation: For production systems, prefer JWT/OIDC for user-facing endpoints and reserve API keys for trusted service-to-service communication.
Tokenized Bookmark Resume URLs
How Bookmark Tokens Work
Elsa generates tokenized URLs for resuming workflows at bookmarks (e.g., HTTP callbacks, webhooks). These URLs are used in scenarios like:
Sending approval requests via email
Webhook callbacks from external systems
Multi-step form submissions with state preservation
Reference: src/modules/Elsa.Http/Extensions/BookmarkExecutionContextExtensions.cs (elsa-core)
The GenerateBookmarkTriggerUrl method creates URLs in this format:
The token contains:
Bookmark ID
Workflow instance ID
BookmarkTokenPayload contains only BookmarkId and WorkflowInstanceId. Token lifetime is controlled by the token generated by GenerateBookmarkTriggerToken / GenerateBookmarkTriggerUrl, including overloads that accept a TimeSpan or DateTimeOffset.
Security Best Practices for Resume Tokens
See examples/resume-endpoint-notes.md for detailed guidance.
Critical Security Controls:
Time-to-Live (TTL):
Bookmark resume tokens can be generated with a lifetime or absolute expiration
Use short-lived tokens for webhooks (minutes) and longer-lived tokens for email approvals (hours/days)
Tokens become invalid when the bookmark is consumed (AutoBurn) or the workflow is cancelled
Single-Use Semantics:
Bookmarks are "burned" (deleted) after successful resume by default
Use
AutoBurn = truein bookmark creation for one-time-use tokensCheck for duplicate resume attempts via distributed locking
Revocation Strategy:
Implement a token revocation list for compromised tokens
Workflow cancellation automatically invalidates associated bookmarks
Manual revocation: delete bookmark from database or cancel workflow
Audit Logging:
Log all resume attempts (success and failure)
Include source IP, timestamp, and workflow context
Integrate with SIEM for anomaly detection
Rate Limiting:
Apply rate limits at ingress (Nginx, Traefik) or application middleware
Recommended limits:
Per IP: 100 requests/minute for resume endpoints
Per token: 3 attempts before soft-block (requires investigation)
See examples/ingress-cors-snippet.md for configuration
Example: Resuming a Workflow via Bookmark
Request:
Expected Responses:
200 OK: Workflow resumed successfully
400 Bad Request: Token invalid or input query-string JSON is malformed
429 Too Many Requests: Rate limit exceeded
Security Notes:
Always use HTTPS for resume URLs to prevent token interception
Validate payload schema to prevent injection attacks
Consider IP allowlisting for internal webhooks
CORS, CSRF, and Rate Limiting
CORS for Resume Endpoints
When exposing resume endpoints to browser-based applications or external systems, configure CORS carefully to prevent unauthorized access.
Configuration Example:
Best Practices:
Never use
AllowAnyOrigin()in productionWhitelist only necessary origins
Prefer POST over GET for resume operations (prevents token leakage in logs)
For public webhooks, avoid CORS altogether (server-to-server only)
CSRF Considerations
Bookmark Resume Endpoints:
Resume endpoints are designed for server-to-server or webhook callbacks
If resume tokens are embedded in web pages, add CSRF protection:
Studio and API:
Elsa Studio uses token-based auth (immune to CSRF)
For cookie-based sessions, enable
SameSite=StrictorSameSite=Lax
Rate Limiting
Application-Level:
Ingress-Level (Preferred):
See examples/ingress-cors-snippet.md for Nginx/Traefik examples.
Ingress rate limiting is more scalable and protects against DDoS before traffic reaches the application.
Secrets Management
Storing Sensitive Configuration
Do:
Store API keys, database connections, and JWT signing keys in:
Environment variables
Azure Key Vault
AWS Secrets Manager
HashiCorp Vault
Encrypt secrets at rest in configuration stores
Rotate credentials regularly (quarterly minimum)
Don't:
Commit secrets to Git (use
.gitignoreand secret scanning)Log sensitive data in plaintext
Share API keys via email or chat
Example: Loading Secrets from Environment Variables:
Workflow Variable Security
Sensitive Workflow Data:
Mark sensitive workflow variables as "secret" (not logged or displayed)
Avoid passing PII through workflow variables when possible
Use encrypted storage for workflow instance data containing secrets
Logging Best Practices:
Scrub PII and secrets from structured logs
Use safe fields only: WorkflowInstanceId, ActivityType, Status
Example log configuration:
Network & TLS
TLS Requirements
Minimum Requirements:
TLS 1.2 or higher for all HTTP endpoints
Valid, trusted certificates (not self-signed in production)
HTTPS redirect enforced:
Certificate Configuration:
Obtain certificates from Let's Encrypt, DigiCert, or your organization's CA
Configure certificate renewal automation
Use wildcard certificates for multi-subdomain deployments
Mutual TLS (mTLS)
For service-to-service communication in zero-trust environments:
Use Cases:
Internal microservices mesh
Sensitive data workflows
Compliance requirements (PCI-DSS, HIPAA)
Session Affinity (Sticky Sessions)
Important Note: Sticky sessions are not required for Elsa workflow runtime. Workflows use distributed locking and database persistence, making them resilient to node switching mid-execution.
When Sticky Sessions May Help:
Studio UI interactions only (for caching workflow definitions client-side)
Not needed for API calls or runtime operations
See Clustering Guide (DOC-015) for more on distributed runtime architecture.
Studio Security Notes
Deploying Studio Behind Ingress
Ingress Configuration:
SSO/Identity Integration
Studio Authentication:
Configure Studio to use the same OIDC provider as Elsa Server through Studio 3.7.0 configuration
Use the Blazor host pattern in Studio Designer Integration, then configure:
AuthenticationScopesare requested during sign-in.BackendApiScopesare requested when Studio obtains an access token for the Elsa Server API. Some identity providers require the backend API scope in the original sign-in grant as well; if backend API token acquisition or refresh fails, include the same scope in bothAuthenticationScopesandBackendApiScopes.Register Studio redirect and logout callback URIs according to the host model: Blazor WebAssembly uses
/authentication/login-callbackand/authentication/logout-callback; Blazor Server uses/signin-oidcand/signout-callback-oidcby default. Studio initiates logout at/authentication/logout.
Authorization:
Grant Studio users only the Elsa
permissionsclaims needed for the screens and actions they can useUse ASP.NET Core role policies for custom host controllers or pages; Elsa API endpoints still require Elsa permission claims
Session Affinity for Studio
While not required for runtime, Studio benefits from session affinity to:
Cache workflow definitions in browser memory
Reduce API round-trips during editing
Configuration (Optional):
Enable sticky sessions at load balancer for Studio endpoints only
Use cookie-based or IP-hash affinity
Not needed for
/elsa/api/endpoints (runtime operations)
Production Hardening Checklist
Use this checklist to verify your Elsa deployment is production-ready from a security perspective.
Identity & Authentication
Network Security
CORS & CSRF
Resume Tokens
Secrets Management
Observability & Logging
Clustering & Distributed Runtime
Authorization
Infrastructure
Observability & Monitoring
Security-Relevant Metrics
Monitor these metrics for security anomalies:
Authentication Failures: Spike indicates brute-force attempts
Resume Token Errors: High rate of invalid-token or no-op resume attempts may indicate token enumeration
Rate Limit Hits: Track which IPs/tokens are rate-limited
Workflow Cancellations: Unusual patterns may indicate attacks
Tracing and diagnostics
Enable distributed tracing to track security-relevant events:
Reference: Elsa.Workflows.Core/Telemetry/WorkflowInstrumentation.cs and Elsa.Diagnostics.OpenTelemetry/*
Security Event Tracing:
Authentication attempts (success/failure)
Resume token validation
Workflow instance modifications
Permission checks
For full monitoring setup, see Monitoring & Observability.
Troubleshooting Security Issues
Common Issues and Solutions
Token Invalid or Expired
Symptom: Resume requests fail validation or return a client error
Diagnosis:
Check whether the resume URL contains the
tquery-string tokenVerify clock synchronization across nodes (use NTP)
Confirm token signing key matches between issue and validation
Fix:
Generate bookmark URLs with an appropriate lifetime or absolute expiration
Ensure all nodes use same signing key
Regenerate token if signing key rotated
CORS Blocked
Symptom: Browser console shows CORS error, API call fails
Diagnosis:
Check browser DevTools Network tab for preflight (OPTIONS) request
Verify response headers include
Access-Control-Allow-OriginConfirm origin is in whitelist
Fix:
Rate Limit Exceeded
Symptom: Resume requests return 429 Too Many Requests
Diagnosis:
Check rate limit configuration in ingress or middleware
Identify source IP in logs
Determine if legitimate spike or attack
Fix:
Whitelist trusted IPs if legitimate traffic
Adjust rate limits based on actual usage patterns
Implement token bucket algorithm for burst tolerance
For more troubleshooting guidance, see Troubleshooting Guide (DOC-017).
Related Documentation
Authentication & Authorization Guide - Detailed OIDC and API key setup
Clustering Guide (DOC-015) - Distributed runtime security
Troubleshooting Guide (DOC-017) - Diagnosing security issues
Monitoring & Observability - Security metrics and alerting
Workflow Patterns Guide (DOC-018) - Secure workflow design
Diagram Placeholders
Note: Diagrams to be added in future updates. Suggested diagrams:
Identity flow: Client → Elsa API → OIDC Provider
Resume token lifecycle: Generation → Validation → Bookmark resume
Network architecture: Ingress → Load Balancer → Elsa Nodes → Database
Studio SSO flow: Browser → Studio → OIDC Provider → Elsa API
Last Updated: 2025-11-25 Document ID: DOC-020
Last updated