Authentication and authorization on SOARCA

Microsoft Entra ID

Mon, 01 Jan 0001 00:00:00 +0000

SOARCA accepts access tokens that Entra ID issues for a dedicated SOARCA API app registration. Permissions come from app roles on that registration, so you decide in Entra ID who may read, write or execute playbooks.

You need an account that can create app registrations and grant admin consent, for example Application Administrator. Note your tenant ID from the Entra admin center overview page.

Entra components: users and applications

@startuml
skinparam componentStyle rectangle

component "**SOARCA API** (app registration)\n\nApplication ID URI: api://soarca\nScope: access_as_user\nApp roles: Playbook.Read, Playbook.Write,\nPlaybook.Execute, SOARCA.Admin" as api

component "**A client that signs users in**\n(authorization code flow)" as client
component "**An integration or managed identity**\n(client credentials flow)" as integration

client -> api : delegated scope\n+ the user's assigned app roles
api <-- integration : application permission\n(app role assigned to the application)
@enduml

One registration represents SOARCA. Everything that calls SOARCA gets its own registration, or is a managed identity. Users and groups receive app roles through assignment; applications receive them as application permissions. Either way the roles end up in the token’s roles claim, which SOARCA maps to permissions:

authentik and other OIDC providers

Mon, 01 Jan 0001 00:00:00 +0000

SOARCA accepts access tokens from one OpenID Connect provider, found through its discovery document. This page uses authentik, which SOARCA is tested with. Other providers work if their tokens meet the same requirements.

Permissions come from the groups a user or service account belongs to:

Group	SOARCA permissions
`soarca_read`	`playbook:read`
`soarca_write`	`playbook:read`, `playbook:write`
`soarca_execute`	`playbook:read`, `playbook:execute`
`soarca_admin` (or the value of `AUTH_GROUP`)	all permissions

Group names are case-sensitive. Existing setups where every user is in soarca_admin keep working unchanged.

API keys

Mon, 01 Jan 0001 00:00:00 +0000

Some systems can only send a fixed header, for example a webhook source that triggers a playbook. For those, SOARCA accepts static API keys. Prefer Entra ID or authentik wherever the caller can request a token: tokens expire within hours, while a leaked key stays valid until it’s removed or expires.

SOARCA never stores the keys themselves, only their SHA-256 hash. Every key starts with soarca_, which lets SOARCA recognise it and lets secret scanners find leaked ones.