Understand policy-based access control
Automation orchestrator uses policy-based authorization to control access to workflows, credentials, and other resources. The authorization system evaluates permissions decisions against your identity, group memberships, projects and resource attributes.
Authentication establishes your identity: who you are, which identity provider authenticated you, and which groups you belong to. Authorization determines what you can do. For example, it controls whether you can view a workflow, use a credential, or modify settings.
Why policy-based instead of traditional RBAC
Traditional role-based access control assigns fixed roles to users and maps those roles to predefined permission sets. The model ties roles like "Admin", "Execute", and "Read" to specific objects in a hierarchy.
Automation orchestrator uses a more flexible model:
- Fine-grained access cross organizational boundaries. Workflows often combine integrations and execution targets from multiple teams. A traditional RBAC hierarchy does not support fine-grained level of permissions control that limits the action per group of users.
- You need to understand why access was granted or denied. Policy-based access control returns the specific policies that contributed to each decision. It also returns the reason each policy matched or did not match.
How authorization decisions are made
When you make a request, automation orchestrator sends an authorization query containing your identity and group memberships, the resource being accessed (type, ID, and metadata), and the action being attempted (for example, workflow:read, execution:run, group:manage-members). The authorization system evaluates all applicable policies against this input and returns a decision (allow or deny) with the matched policy and denial reason. Automation orchestrator then grants or denies the request and logs the authorization decision in the audit log.
| Capability | Traditional RBAC | Policy-based system |
|---|---|---|
| Access decisions based on | Role assignment only | User attributes, resource attributes, labels, metadata, and context |
| Policies | Fixed, predefined | Define permissions for a specific resource and action pair |
| Roles | Fixed, predefined | Expressed as named policy bundles; custom roles can combine any set of policies |
| Explainability | Manual trace through role hierarchy | Every decision returns the policies and reasons that contributed |
| Extensibility | Add new roles, reassign users | Add new policy without changing the role model |
How the deny-by-default model protects resources
Automation orchestrator denies all access unless a policy explicitly grants it. You must have a role assignment or explicit permissions to access resources. If no allow policy matches your request, access is denied. You do not need an explicit deny rule to block access.
The built-in administrator account has the admin role, which includes allow policies for every resource type and action. It goes through the same policy evaluation as all other users. Disable it after configuring external identity providers.
Flat resource model
Automation orchestrator uses a flat resource model where policies define access control per resource or per identity. Resources do not inherit access from a container hierarchy. Some resources are global-scoped, such as users and groups. Other resources are project-scoped, such as workflows and credentials. Policies and roles can be either global or project-scoped. Project membership does not automatically grant access.
Credentials must belong to a project. Automation orchestrator does not support cross-project credential sharing.
| Aspect | automation controller | automation orchestrator |
|---|---|---|
| Resource organization | Hierarchical (project > job template) | Flat (resources scoped to projects, but no nested hierarchy) |
| Access inheritance | Access to a project grants access to its contents | No container inheritance; access is per resource or per policy |
| Cross-boundary sharing | Resources must be duplicated or cross-referenced | Resources can be shared across teams through policy conditions (except credentials, which are project-bound) |
| Resource classification | Organization and hierarchy | Labels, metadata, and projects |
Labels and attribute-based conditions
All policy-evaluable objects in automation orchestrator expose a labels field. Labels are key-value pairs stored as JSON. The authorization system evaluates labels during authorization decisions, enabling attribute-based access control.
For example, a policy can grant access only to workflows labeled environment=staging. Because no allow policy matches for environment=production, access to those workflows is denied by default. You or automation processes set labels on individual resources. The authorization system evaluates labels; it does not manage or assign them.
Resource metadata, user metadata, and group labels provide additional attributes for policy conditions. For the full list of supported condition types, see the policy statement structure.
Resource types and actions
Automation orchestrator builds a resource-actions catalog at startup by inspecting route dependencies and built-in policies. The GET /api/v1/authz/resource_actions endpoint exposes this catalog. You and the UI can use it to discover valid resource-action pairs for authorization checks.
Automation orchestrator enforces authorization on these resource types:
| Resource type | Actions | Description |
|---|---|---|
| workflow | create, read, update, delete | Automation workflows |
| execution | read, run | Workflow execution records |
| credential | create, read, update, delete | Credentials for workflow nodes (must belong to a project) |
| project | create, read, update, delete | Project configuration and scoping |
| group | create, read, update, delete, manage-members | Group membership management |
| user | create, read, update, delete | User management |
| role | create, read, update, delete | Role definitions |
| policy | read | Built-in policy definitions |
| role-assignment | read, assign, revoke | Role assignments for users and groups at system or project scope |
| identity-provider | create, read, update, delete, test | Identity provider configuration |
| approval | create, read, decide | Human-in-the-loop approval nodes |
| authz | query | Authorization query endpoints (who-can) |
| user_identity | read, attach, detach | User identity provider links |
| invocation | create, read, cancel | Workflow invocation records. Only theadmin role includes invocation permissions. |
| files | upload, download | File uploads and downloads for workflow resources |
| setting | read, write | Runtime settings configuration |
| integration | create, read, update, delete, discover, validate, refresh | External tool integrations |
| tool | read, update | Tools provided by integrations |
| llm_model | read, update | Large language model configurations |
| service_account | create, read, update, delete, rotate_secret, disable, enable | Service accounts for system-to-system authentication |
| user-directory | read | Lightweight user lookup for role assignment workflows |
| group-directory | read | Lightweight group lookup for role assignment workflows |
| admin:revocation | read, execute | Administrative token and session revocation |
Authorization hook points
Automation orchestrator evaluates authorization at specific points in the request lifecycle:
API request authorization. The authorization system evaluates every API request before the operation executes. If you lack permission, the API returns a 403 Forbidden response with a denial explanation (RFC 9457 error format).
Workflow execution authorization. When you execute a workflow, the authorization system verifies that you have execution:run permission. Execution records are a separate resource type from workflows. The authorization system checks execution:read for viewing execution history and execution:run for triggering executions.
Permission management authorization. Managing role assignments requires the role-assignment:assign permission. The admin role includes this permission. For project-scoped assignments, automation orchestrator also verifies that you hold the permission within the target project.
List endpoint visibility filtering. All list endpoints apply a unified visibility filter. You see only the resources you are authorized to access. If you lack read permission for a resource type, the API returns an empty list rather than a 403 error. Automation orchestrator redacts project names from responses if you lack access to those projects.
Audit logging. Automation orchestrator logs API requests as audit events, including the request path, HTTP method, response status code, and actor identity. Audit events also cover non-HTTP contexts such as settings changes and internal system operations.