Role Based Access Control (RBAC) for Apps
RBAC Overview
Role-based access control (RBAC) allows fine-grained control on which users are allowed to view, access and update apps. RBAC is supported using OAuth based auth (like GitHub, GitLab etc). When using OAuth, users have to be explicitly added to groups in the OpenRun RBAC config. RBAC is also supported for OpenID Connect and SAML, like Okta and Microsoft Entra etc. With OIDC, the group information can be detected automatically through the user profile information or it can be explicitly configured in the OpenRun config.
This page covers how RBAC relates to authentication, the config structure (groups, roles, grants), the built-in roles, how each permission is scoped, who may change the admin set, how background runs are authorized, and how to test policies with builtin users.
Authentication versus Authorization
RBAC is used for multiple authorization checks, like app:read (list apps and view basic app info), app:read_detail (view the full app info: source, config, files, logs), app:access (access the app) and various update related actions.
- Always on, every app: a user needs an
app:accessgrant to reach an app, in addition to passing the app’s authentication. - Default grant: the default configuration ships a grant giving every principal (including the
anonymoususer ofnone-auth apps) theopenrun-userrole, which isapp:accessandapp:readon all apps. So out of the box, a user can reach an app if they can authenticate against it. - Locking down: removing or narrowing that grant locks apps down. For example, if an app uses
googlefor auth, a user who can log into the Google account still needs anapp:accessgrant on the app to reach it. - Admins: the
adminuser, and any user holding theadminpermission, always have access. - Disabling: RBAC enforcement cannot be disabled through the dynamic config. The static config flag
security.unsafe_disable_rbacturns all enforcement off for dev/test setups; it cannot be set through the dynamic config API and it excludes the remote API surfaces ([api.rest]/[api.mcp]enableis rejected while it is set).
Who a management API call runs as:
- App Starlark code: management API calls are authorized as the authenticated request user, including read/list operations and mutations. List APIs filter out apps, services and bindings for which that user lacks the corresponding read permission.
- CLI over the unix domain socket: the transport-level administrative exception. Calls run as trusted admin unless
--asis used. - Remote API calls: authenticate with an API key or an OAuth token from browser login and run as that credential’s user identity with RBAC enforced. Enable REST with
[api.rest] enable = trueand MCP with[api.mcp] enable = true; see Remote API and MCP.
App owners:
- The configured app owner permissions also apply when serving an app: the default
app:manageowner permission includesapp:access. Owners must still pass the app’s authentication. - Stage and git preview apps inherit the main app’s owner; existing git previews are migrated on upgrade. Creating a git preview does not grant access to it.
- Set
owner_permissions.appto an empty list to require explicit grants for owners too. - Remote config reads and update responses redact credential fields, as the console does; trusted unix-socket config exports retain the full configuration.
RBAC Configuration
The RBAC configuration is managed through dynamic config. The structure of the RBAC config is
{
"version_id": "ver_32wLWdqboA08eCRDO1KEznxBxka",
"rbac": {
"groups": {
"group1": ["github_local:abc", "oidc_oktatest:def@example.com"],
"group2": ["group:group1", "oidc_oktatest:xyz@example.com"]
},
"roles": {
"accessor": ["app:access"],
"viewer": ["app:read"],
"fullaccess": ["role:accessor", "app:read"]
},
"grants": [
{
"description": "view on all apps",
"users": ["group:group1", "github_local:xyz"],
"roles": ["viewer"],
"targets": ["all"]
},
{
"description": "access on one app",
"users": ["group:mygroup"],
"roles": ["fullaccess"],
"targets": ["example.com:/myapp"]
}
]
}
}groupsis a map of group name to group members. Members are user ids, prefixed with the auth provider name. Group composition is supported, for example group2 includes all group1 users.- A
group:member can also name a group that comes from the user’s sign-in (see Group Info) instead of a group defined in the config:"reporting-users": ["group:finance-analysts", "group:sales-ops"]matches any user whose login groups includefinance-analystsorsales-ops, checked on each request. - A
group:member has the same meaning as in a grant: it matches the config group of that name if one is defined and the sign-in group of that name.
- A
rolesis a map of role name to permissions. Roles also can be composed, for example rolefullaccessgets all permissions of roleaccessor.grantsassign roles to users on targets, see Grants.
Grants
Beyond the default grant (the openrun-user role for every principal), users have no permissions. Grants have to be added for each additional permission. The grant list can never be emptied through a dynamic config update: at least one grant is required while RBAC is enforced (an empty list would lock every user except admin out of every app).
| Field | Meaning |
|---|---|
description | A note about the grant. |
users | List of users or groups. |
roles | List of roles granted. |
targets | List of targets the grant’s scoped permissions apply to (see below). |
Target entries:
| Entry | Matches |
|---|---|
domain:path glob | Apps, using the app glob path format. |
service:<glob> | Service ids in the <type>/<name> form, without a leading slash: service:postgres/* matches postgres/main, service:** matches all services. |
binding:<glob> | Binding paths: binding:/apps/team1/**. |
all (or *:**) | Every app, service and binding. |
The group name referenced in a grant (or as a group: member of a config group) can be a group which is seen at runtime in the user profile. This works for OIDC based auth, like Okta.
Built-in Roles
In addition to any roles you define, OpenRun ships a set of built-in roles that are always available. Their names all use the reserved openrun- prefix; user-defined role names may not start with openrun-. They can be referenced directly in grants, or composed into your own roles with the role: prefix (for example "team-lead": ["role:openrun-developer", "app:approve"]). A role mixes scoped (app:*) and global permissions: the scoped ones apply to the grant’s targets, the global ones apply regardless of the targets (see Permission Scope).
| Role | Purpose | Highlights |
|---|---|---|
openrun-admin | Unrestricted super-user; bypasses every check | the admin permission |
openrun-operator | Runs the platform | full app lifecycle, app:approve, sync, services, bindings, provider management, container management, config, secrets (no reveal), audit, server stop, builder, own API keys |
openrun-developer | Builds and deploys apps | app:manage, services/bindings (no delete), container:read, sync:run/read, secret:create/read, config:basic_read (for the create/update forms), own API keys. No app:approve, full config, audit, secret delete/reveal, server stop, or builder |
openrun-builder | A developer who also uses the AI app builder | everything in openrun-developer plus builder:* |
openrun-user | Baseline authenticated user | app:access and app:read (list apps and see their basic info; no source, config, files or logs) |
openrun-consumer | Reach served apps only | app:access, no app listing or app info at all |
openrun-monitor | Read-only observability | app:read_detail (full app info across apps), audit, containers, sync, services, bindings, providers, config, and secret metadata (no reveal, no writes) |
secret:reveal (reading back stored secret values) and binding:reveal (reading back binding account credentials with binding show-account) are not included in any built-in role other than openrun-admin (whose admin permission bypasses every check). Users who need to read these values back must be granted secret:reveal / binding:reveal explicitly.
Permission Scope
| Scope | Permissions | Applies to |
|---|---|---|
| App (scoped) | app:access, app:read, app:read_detail, app:create, app:update, app:reload, app:apply, app:delete, app:promote, app:preview, app:token_read, app:token_manage, app:approve, app:manage, and custom: permissions | The apps matched by the grant’s app path targets. |
| Service (scoped) | service:create, service:update, service:delete, service:read, service:bind, service:manage | The services matched by the grant’s service:<glob> targets. |
| Binding (scoped) | binding:create, binding:update, binding:delete, binding:read, binding:run_command, binding:use, binding:reveal, binding:manage | The bindings matched by the grant’s binding:<glob> targets. |
| Global | builder:list/create/publish, sync:create/run/delete/read, container:read/manage, provider:read/manage, config:basic_read/read/update, secret:create/read/delete/reveal, audit:read, server:stop, apikey:manage:self, admin, admin:manage | Conferred by a grant regardless of its targets. |
App permissions
app:token_readandapp:token_managelist and create/delete app webhook tokens.app:manageis the composite of all app permissions exceptapp:approve.app:updateimpliesapp:reloadandapp:apply.- Custom (
custom:) app-level permissions are scoped the same way as theapp:*permissions. app:readcovers listing apps and the basic app info: path, name, id, auth type, active version, timestamps and staging state. A user withapp:readonly gets the basic view fromapp list/get_appand the console’s app detail page, and is denied the version, file, export and log operations.app:read_detail(which impliesapp:read) covers everything else an app exposes: the source url and git info, spec, config, parameters, bindings, requested plugin permissions, versions and their files and diffs, job run history and output, and the app’s own containers (details and logs, without needing the platform-widecontainer:read).app:updateimpliesapp:read_detail, andapp:manageincludes it, so every built-in role exceptopenrun-userandopenrun-consumersees the full app info.
Service and binding permissions
service:bindprovisions binding accounts on the service. It is needed to create base/auto bindings from it and to link it as the staging service of another service.binding:useattaches the binding to an app, or derives a new binding from it.binding:revealreads back the binding account credentials.- Like
app:approve,binding:revealis never implied bybinding:manage: it needs an explicit grant, and binding owners do not hold it by default (add it toowner_permissions.bindingto opt owners in). - An empty target entry (
"") is rejected when the config is updated; it is not a synonym forall. - A grant whose targets only name app paths confers no service or binding permissions; use
service:**/binding:/**entries (orall) to grant them broadly. - Attaching a binding to an app requires
binding:useon the binding (orservice:bindon the service for auto bindings created from a service source), in addition to the app permission for the app update itself. - Service and binding list operations return only the entries the user can read.
- The creator of a service or binding holds the configured owner permissions on it (default
service:manage/binding:manage) without needing a grant, like app and sync owners. Override withowner_permissions.service/owner_permissions.binding.
Global permissions
container:manage(start/stop managed containers) impliescontainer:read.provider:readlists installed providers andprovider:manageinstalls or removes provider executables (and impliesprovider:read).config:basic_readreads non-sensitive config metadata (auth and git auth entry names, specs, the permission catalog) and is implied byconfig:read.apikey:manage:selflets a user create, list and delete their own API keys.adminis the super-user permission that bypasses every check.admin:managegoverns changes to who holdsadmin(see Managing admins).- The
builder:*permissions are global because a builder session is not bound to an app path until it publishes. The app a session publishes, edits or removes is enforced separately with the app permissions on that path: publishing to a new path needsapp:create, republishing an existing app needsapp:update, and unpublishing needsapp:delete(local mode publishes also run through the declarative apply, which enforcesapp:applyandapp:approvebefore any file is staged). The preview dev app a session creates under the configuredpreview_pathis authorized bybuilder:createitself (no app permission is needed for the preview mount) and is owned by the session creator, so the owner rule covers viewing the preview and deleting it with the session.
The app:approve permission
app:approve is the operator-only permission that authorizes approving an app’s plugin permissions (which run server-side code). It is scoped like the other app:* permissions, so a grant confers it only on the apps matched by its targets, but it always needs an explicit grant:
- It is never implied by
app:manage, never matched by a permission glob and never granted through ownership. It has to be granted by its literal name (or held via theadminsuper-user permission, e.g. theopenrun-adminrole). - Setting the
--approveflag on a create/reload/apply, or calling approve directly, requires this permission on every matched app. - Creating a sync entry with
approveset requiresapp:approvegranted with targetall(or*:**), since the entry’s glob can match apps created later. Other globs do not qualify, even broad ones like/**(which covers the default domain only).
Managing admins
config:update is not enough to change who holds the admin permission. A config editor who could rewrite the admin grants or groups could otherwise simply add themselves to one. A dynamic config update (openrun server update-config, the console’s staged RBAC editor and its publish, config_update over REST or MCP) is checked against the live config for changes to the admin surface:
- the roles that resolve to
adminoradmin:manage(listing either literally or composing a role that does, such asrole:openrun-admin) - the
usersandrolesof the grants that use those roles - the membership of every config group those grants reference, through nested
group:members
A change to any of these requires the admin:manage permission, which holders of admin have implicitly; force does not bypass it.
admin:managegrants are protected the same way asadmingrants, so granting oneselfadmin:manageis not a route toadmin.- The rest of the config (other grants, roles and groups, the protected grants’
descriptionandtargets, config entries and settings) stays editable withconfig:update. A grant’sdescriptionandtargetsdo not affect who holdsadmin, sinceadminis a global permission. - The same rule applies to builtin users:
openrun user addoruser updateplacing a user in, or removing a user from, a group an admin grant references (directly or through a nested group) requiresadmin:managein addition touser:create/user:update. - Any change to a builtin user who holds
adminoradmin:managealso requiresadmin:manage, whichever way the user holds it (a group, a grant namingbuiltin:<name>, a config group entry or aregex:pattern): setting the password, unlocking, enabling, disabling, deleting, or creating the user such a grant names. Without it,user:managewould be a route to signing in as an admin. admin:manageis not part of any built-in role other thanopenrun-admin. Grant it explicitly to the users who administer the admin set without being admins themselves, for example"admin-managers": ["role:openrun-operator", "admin:manage"].- Like
adminandapp:approve, it is never matched by a permission glob in a role (*oradmin:*) and must be named literally in API key scopes. - Local CLI calls over the unix domain socket run as the trusted
adminand are not subject to this check unless--asis used.
Sync Jobs and Background Runs
A sync entry runs declarative applies in the background, without an authenticated user. When a sync is created through an RBAC enforced request, the creator’s authorization is frozen on the entry: the grants matching the creator (with group membership, including SSO provided groups, resolved at create time and role permissions flattened) are stored in the sync metadata. Every scheduled run is then authorized against that snapshot. Each apply, reload and promote the run performs needs the corresponding permission (app:apply, app:promote, app:approve) on that app in the frozen grants, and a denied action fails the run (counting toward the sync failure backoff and eventual disable).
Notes on the snapshot behavior:
- The snapshot is frozen at create time. Later edits to roles, groups or grants do not change what an existing sync may do: delete and recreate the sync to pick up new grants.
- Syncs created via the CLI (
adminover the unix socket) or with RBAC disabled store no snapshot and run unrestricted, as before. - Disabling RBAC disables snapshot enforcement too; re-enabling it restores enforcement for entries that have a snapshot.
- The creating credential’s scope ceiling is frozen alongside the grants, including for users holding
admin. Scheduled runs cannot exceed those scopes. Syncs created before scope ceilings were stored must be recreated to capture the credential’s limits. - A sync created by a user holding the
adminpermission with an unscoped credential runs unrestricted. - Manual
sync runcalls are authorized against the caller’s own current grants, not the stored snapshot. - The creator of a sync entry keeps the
sync:run,sync:deleteandsync:readowner permissions on it.
App jobs follow their execution context:
- Manual jobs and
before_deployjobs retain the caller’s RBAC permissions, credential scope ceiling and any sync snapshot. - Scheduled app jobs evaluate management API calls against the app owner’s live RBAC grants and builtin groups. Scheduling a job does not grant trusted server authority.
- SSO owners: OAuth/OIDC and SAML logins refresh a stored IdP group snapshot, valid for
api.federated_identity_ttl; existing browser sessions do not extend that lifetime. After upgrading, an SSO owner must sign in again to populate the snapshot. - Missing owners: unattributed scheduled jobs and deleted builtin or disabled owners have no management API authority. Owners without an API identity row retain direct principal grants; identity lookup failures fail the run before execution. The jobs still run under the app’s approved plugin permissions.
Group Info
To get the group info dynamically as part of the user login (instead of statically defining in the config file), the requirements are:
- OpenID Connect-based auth or SAML is used
- For OpenID, the appropriate scope is requested, like
groups - The Identity Provider is configured to return the groups info in the user profile, with the
groupskey. For example, see Okta forum about configuring Okta with OIDC. - The group name as returned in the user profile is used in the grant
Testing RBAC with Builtin Users
To try out RBAC policies with multiple users and groups without setting up an OAuth/SAML provider, use the builtin auth type:
- Create users with groups using
openrun user add alice --groups dev,qa(no server restart needed; managing users needsuser:manage). - Point an app at it with
--auth builtin, and exercise grants withcurl -u alice:password. - The user id in grants is
builtin:alice; the groups of the user are matched bygroup:references like SSO groups.
Testing management API grants with –as
To test the management API side of a policy (app/service/binding/secret operations, list filtering, the owner rule), run CLI commands as another user with the global --as flag:
openrun --as builtin:alice app list
openrun --as builtin:alice service create --config url=... postgres/teamdb- The call is authorized against the named user’s current grants instead of running as the trusted
admin, and audit events record that user. --asworks only over the unix domain socket (the caller is already the administrator; impersonation only ever narrows authority, no password is needed).- For
builtin:users the user must exist (and not be disabled) and its groups feedgroup:matching. - Any other
<provider>:<username>id (likegithub:user1) is taken literally with no groups, so grants for SSO identities can be tested without creating the users.
Regex User Name
In the groups.<group_name> property and in grant.users, the username can be specified as a regex. If the value starts with regex: prefix, the subsequent value is considered as a regex. The pattern must match the entire user ID (it is evaluated fully anchored, as if wrapped in \A(?:...)\z), so a partial match does not grant access: regex:google:.*@example\.com matches any user ID with the google provider and an example.com email, and does not match google:user@example.com.attacker.io.
Custom Permissions
Permissions like app:access, app:read, app:update are OpenRun-defined permissions. They control what actions can be performed by the user in OpenRun. In addition to these, custom permissions are supported. Custom permissions are defined in the config with the custom: prefix. These permissions are ignored by OpenRun. They are passed to the app. For apps where requests are proxied through OpenRun (like containerized apps), these permissions are available in the HTTP headers
| Header | Value |
|---|---|
X-Openrun-User | The user performing the request. The user ID is prefixed with the provider name (like google:test@example.com). The username is anonymous for anonymous requests and admin for admin requests. |
X-Openrun-User-Id | The provider user ID claim, when available. For OIDC providers this is the sub claim. |
X-Openrun-User-Email | The provider email claim, when available. |
X-Openrun-Perms | The list of custom permissions available to this user on this app. The list is comma-separated, without the custom: prefix, like appread,appdelete. |
X-Openrun-Rbac-Enabled | Whether RBAC is enabled for the app, true or false. |
For Action apps, custom perms can be used to limit which user can perform what operations. In the action definition, adding permit=['appread'] means that the action will be available only to users who have any one of the custom permissions specified in the list. The default action should be available to everyone, other actions can be controlled using custom permissions. If no permits are set, all actions are available to authenticated users.
Plugin calls can use the same custom permissions with ace.permission(..., permit=['appread']). The call is allowed only if the user has at least one listed custom permission. If the permit list is empty, plugin permissions behave normally. Custom permissions require grants like any other permission (with security.unsafe_disable_rbac, every custom permission is granted to everyone).
Notes
- RBAC applies to every app: users need an
app:accessgrant to reach an app (the default grant provides it to every authenticated principal). Therbac:auth prefix is still accepted for backward compatibility but no longer has any special effect. - Local CLI calls over the Unix domain socket run as
adminunless--asis used. Remote CLI calls run as the authenticated credential’s user, with RBAC enforced. - For apps with no authentication (using
noneauth), the user ID to use in RBAC isanonymous, without the auth type prefix.