Authentication and authorization

Authentication is disabled by default in SOARCA. With the default configuration, anyone who can reach SOARCA over the network can submit and execute playbooks. Because playbooks can reconfigure the systems SOARCA is connected to, enable authentication for every deployment that is reachable by more than a single trusted machine.

With authentication enabled, every API request needs an Authorization: Bearer <credential> header. SOARCA accepts three kinds of credentials, side by side:

You can enable any combination. SOARCA looks at each credential and hands it to the matching provider: a JWT by its issuer (iss claim), an API key by its soarca_ prefix. Tokens from an issuer SOARCA isn’t configured for are rejected.

Permissions

SOARCA grants access through four permissions. Each identity provider maps its own roles or groups onto them; see the provider pages below for the exact names.

Every role that grants playbook:write or playbook:execute also grants playbook:read.

A request without a valid credential gets 401 Unauthorized. A valid credential that lacks the permission gets 403 Forbidden. Both use SOARCA’s usual error format:

{
  "status": "403",
  "message": "forbidden: requires playbook:execute",
  "original-call": "POST /trigger/playbook",
  "downstream-call": ""
}

Setting up a provider

• Microsoft Entra ID
• authentik (and other OpenID Connect providers)
• API keys

Environment variables

Authentication is turned on with AUTH_ENABLED: true. SOARCA then refuses to start unless at least one provider is fully configured.

General

OpenID Connect (authentik)

OIDC_ISSUER and OIDC_CLIENT_ID must be set together.

Microsoft Entra ID

AUTH_ENTRA_TENANT_IDS and AUTH_ENTRA_API_CLIENT_ID must be set together.

API keys

Example

• .env

AUTH_ENABLED: true

# authentik
OIDC_ISSUER: "https://authentik.example.com/application/o/soarca/"
OIDC_CLIENT_ID: "soarca"
AUTH_GROUP: "soarca_admin"

# Entra ID
AUTH_ENTRA_TENANT_IDS: "11111111-1111-1111-1111-111111111111"
AUTH_ENTRA_API_CLIENT_ID: "aaaaaaaa-0000-0000-0000-000000000001"
AUTH_ENTRA_API_APP_ID_URI: "api://soarca"

# API keys
AUTH_API_KEYS_FILE: "/etc/soarca/api-keys.json"

Checking a token

Access tokens are signed, not encrypted, so you can read their claims. This is the quickest way to find out why SOARCA rejects one:

echo "$TOKEN" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq

Compare iss with the issuer SOARCA is configured for, aud with the client ID, and roles (Entra ID) or groups (authentik) with the role tables on the provider pages.

Then call SOARCA with it:

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/playbook/

Common problems