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 six permissions. Each identity provider maps its own roles or groups onto them; see the provider pages below for the exact names.

Every role grants principal:read, and 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": ""
}

Discovering the accepted identity providers

SOARCA publishes which identity providers it accepts as OAuth protected resource metadata (RFC 9728). The document is public, so clients can read it before anyone signs in:

curl https://soarca.example.com/.well-known/oauth-protected-resource

{
  "resource": "https://soarca.example.com",
  "resource_name": "SOARCA",
  "authorization_servers": [
    "https://authentik.example.com/application/o/soarca/",
    "https://login.microsoftonline.com/11111111-1111-1111-1111-111111111111/v2.0"
  ],
  "scopes_supported": ["api://soarca/access_as_user"],
  "bearer_methods_supported": ["header"]
}

authorization_servers lists the issuer of every token SOARCA accepts: the OIDC issuer, one Entra ID issuer per tenant, and with AUTH_ENTRA_ACCEPT_V1 also the v1 issuers. API keys aren’t listed, since nobody signs in with them. With AUTH_ENABLED: false the list is empty, which tells clients they can skip sign-in. scopes_supported holds the Entra ID scope that user tokens must carry, when Entra ID is enabled.

A client such as SOARCA-GUI keeps its own client registration per provider. It offers sign-in only for providers whose issuer appears in authorization_servers, and can warn at startup when a provider it is configured for isn’t listed, instead of every call failing with 401 after sign-in.

A 401 response points at the document in its WWW-Authenticate header, so a client can discover it from a failed call:

WWW-Authenticate: Bearer realm="soarca", resource_metadata="https://soarca.example.com/.well-known/oauth-protected-resource"

resource is taken from the host the request came in on. Behind a reverse proxy, set AUTH_RESOURCE_URL to SOARCA’s public URL.

Checking what a caller may do

GET /principal/permissions returns the permissions of whoever calls it: a user, an application or an API key. Clients such as SOARCA-GUI use it to hide actions the caller can’t perform. SOARCA still checks the permission on every call.

{
  "subject": "entra:11111111-1111-1111-1111-111111111111:user:3f2c…",
  "provider": "entra",
  "permissions": ["principal:read", "playbook:read", "playbook:execute"]
}

soarca:admin is expanded, so an administrator gets the full list and clients don’t need to know which permission implies which.

The endpoint needs principal:read, which every role grants. A caller that signed in but holds no role gets 403 Forbidden, which clients can show as “no access to SOARCA”. API keys only get it when it is listed in the key’s permissions.

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