Authentication security

Automation orchestrator secures authentication with ES256-signed JWTs, PKCE-protected OIDC flows, encrypted client secrets, and CSRF protection.

Token signing

Automation orchestrator signs all JWTs with ES256, an Elliptic Curve Digital Signature Algorithm using the P-256 curve.

You provide the signing key at deployment. These environment variables map to the Kubernetes Secrets.

Table 1. JWT signing key environment variables
Environment variable Description
APP_JWT_PRIVATE_KEY_PATH Path to an ES256 private key PEM file
APP_JWT_PRIVATE_KEY_BASE64 Base64-encoded ES256 private key PEM string

You must configure one of these variables. The application does not start without a signing key.

Note:

In Operator deployments, the Operator provisions the signing key automatically. If your security policy requires customer-managed keys, provide your own application secrets during installation.

Each key includes a key ID (kid) in the JWT header. Clients use the key ID to select the correct public key from the JWKS endpoint for verification.

Key rotation

Automation orchestrator supports zero-downtime key rotation by using backup keys. The new key signs all new tokens while the previous key remains available for verification until existing tokens expire.

OIDC flow protections

Table 2. OIDC flow protections
Protection Description
PKCE All authorization code flows use Proof Key for Code Exchange. Automation orchestrator encodes the code verifier in the signed OIDC state JWT and validates it during the token exchange.
State parameter OIDC flow state (including nonce and PKCE code verifier) is encoded as a signed JWT in the OAuth2 state parameter. No server-side state storage is required. The callback validates the state signature and expiration to prevent CSRF attacks.
Nonce validation A nonce is included in the authorization request and validated in the returned ID token to prevent replay attacks.
ID token validation ID tokens are validated for signature (using the identity provider JWKS), issuer, audience, and expiration.
Open redirect prevention Automation orchestrator validates post-login redirect URLs against configured CORS origins. Protocol-relative URLs and URLs with mismatched origins are rejected.

Refresh token cookie settings

Table 3. Refresh token cookie settings
Setting Value
Cookie name ao_refresh_token
Cookie path /api/v1/auth
HttpOnly Yes (inaccessible to JavaScript)
SameSite Lax
Secure Configurable (set totrue in production)
Domain Configurable

The restricted cookie path ensures that the browser sends the refresh token only with authentication requests, not with every API call.

Password requirements

Automation orchestrator enforces the following password requirements for local user accounts:

  • Minimum 14 characters.
  • At least 3 of the following 4 character classes: digits (0-9), uppercase letters (A-Z), lowercase letters (a-z), and punctuation or special characters.

These requirements apply to all password-setting methods, including the UI, the API, and the orchestrator-admin reset-password CLI command.

Automation orchestrator hashes local user passwords with Argon2id. This algorithm provides resistance to GPU-based and side-channel attacks. Automation orchestrator never stores or logs plaintext passwords.

Cross-origin resource sharing

Automation orchestrator enforces CORS restrictions on all API requests. When credential cookies are enabled (the default), wildcard (*) origins are not permitted. You must explicitly list allowed origins in APP_CORS_ALLOW_ORIGINS.

Client secret encryption

Identity provider client secrets are encrypted at rest using a Fernet symmetric key. You provide the encryption key at deployment.

CSRF protection

Automation orchestrator uses a CSRF token mechanism to protect state-changing cookie-authenticated requests.

To obtain a CSRF token, send a request to POST /api/v1/auth/csrf_token. This endpoint requires the ao_csrf_token HttpOnly cookie, which is set at login. The response returns a csrf_token string.

Include the returned token in the X-CSRF-Token header on state-changing cookie-authenticated requests, specifically POST /api/v1/auth/refresh and POST /auth/logout.

If the CSRF cookie is missing (for example, the user is not authenticated through the cookie flow), the endpoint returns a 403 error.

Multi-factor authentication

Automation orchestrator does not implement multi-factor authentication (MFA) directly. For users who authenticate through an external OIDC identity provider, the identity provider enforces MFA. The authentication method reference (amr) claim in the access token records the authentication methods used.

The built-in administrator account does not support MFA. For production environments, configure an external identity provider with MFA enabled and then disable the built-in administrator account.

Rotate the JWT signing key

Replace the active signing key with zero downtime by promoting a new key and demoting the current one to backup.

Before you begin

  • A new ES256 signing key with a unique key ID.
  • Access to the automation orchestrator deployment configuration.

Procedure

  1. Generate a new ES256 signing key and assign it a new key ID.
  2. Configure the new key as the primary key by setting APP_JWT_PRIVATE_KEY_PATH or APP_JWT_PRIVATE_KEY_BASE64 and APP_JWT_KEY_ID.
  3. Move the previous key configuration to the APP_JWT_BACKUP_KEYS environment variable.
  4. Restart the application.

What to do next

After restart:

  • Automation orchestrator signs new tokens with the new key.
  • Existing tokens signed with the previous key remain verifiable until they expire.
  • The JWKS endpoint (GET /auth/.well-known/jwks.json) serves both the primary and backup keys.

Automation orchestrator uses backup keys for verification only.