Skip to content
📌 OpenRun 1.0 is released, read the announcement
Role Based Access Control

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:access grant 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 anonymous user of none-auth apps) the openrun-user role, which is app:access and app:read on 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 google for auth, a user who can log into the Google account still needs an app:access grant on the app to reach it.
  • Admins: the admin user, and any user holding the admin permission, always have access.
  • Disabling: RBAC enforcement cannot be disabled through the dynamic config. The static config flag security.unsafe_disable_rbac turns 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] enable is 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 --as is 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 = true and 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:manage owner permission includes app: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.app to 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"]
      }
    ]
  }
}
  • groups is 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 include finance-analysts or sales-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.
  • roles is a map of role name to permissions. Roles also can be composed, for example role fullaccess gets all permissions of role accessor.
  • grants assign roles to users on targets, see Grants.
A grant ties users and groups to roles, which carry permissions, and applies those permissions on its targets: apps, services and bindings A grant ties users and groups to roles, which carry permissions, and applies those permissions on its targets: apps, services and bindings
RBAC model: grants, roles, permissions and targets

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).

FieldMeaning
descriptionA note about the grant.
usersList of users or groups.
rolesList of roles granted.
targetsList of targets the grant’s scoped permissions apply to (see below).

Target entries:

EntryMatches
domain:path globApps, 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).

RolePurposeHighlights
openrun-adminUnrestricted super-user; bypasses every checkthe admin permission
openrun-operatorRuns the platformfull app lifecycle, app:approve, sync, services, bindings, provider management, container management, config, secrets (no reveal), audit, server stop, builder, own API keys
openrun-developerBuilds and deploys appsapp: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-builderA developer who also uses the AI app buildereverything in openrun-developer plus builder:*
openrun-userBaseline authenticated userapp:access and app:read (list apps and see their basic info; no source, config, files or logs)
openrun-consumerReach served apps onlyapp:access, no app listing or app info at all
openrun-monitorRead-only observabilityapp: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

ScopePermissionsApplies 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: permissionsThe apps matched by the grant’s app path targets.
Service (scoped)service:create, service:update, service:delete, service:read, service:bind, service:manageThe 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:manageThe bindings matched by the grant’s binding:<glob> targets.
Globalbuilder: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:manageConferred by a grant regardless of its targets.

App permissions

  • app:token_read and app:token_manage list and create/delete app webhook tokens.
  • app:manage is the composite of all app permissions except app:approve.
  • app:update implies app:reload and app:apply.
  • Custom (custom:) app-level permissions are scoped the same way as the app:* permissions.
  • app:read covers listing apps and the basic app info: path, name, id, auth type, active version, timestamps and staging state. A user with app:read only gets the basic view from app list/get_app and the console’s app detail page, and is denied the version, file, export and log operations.
  • app:read_detail (which implies app: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-wide container:read). app:update implies app:read_detail, and app:manage includes it, so every built-in role except openrun-user and openrun-consumer sees the full app info.

Service and binding permissions

  • service:bind provisions 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:use attaches the binding to an app, or derives a new binding from it. binding:reveal reads back the binding account credentials.
  • Like app:approve, binding:reveal is never implied by binding:manage: it needs an explicit grant, and binding owners do not hold it by default (add it to owner_permissions.binding to opt owners in).
  • An empty target entry ("") is rejected when the config is updated; it is not a synonym for all.
  • A grant whose targets only name app paths confers no service or binding permissions; use service:** / binding:/** entries (or all) to grant them broadly.
  • Attaching a binding to an app requires binding:use on the binding (or service:bind on 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 with owner_permissions.service / owner_permissions.binding.

Global permissions

  • container:manage (start/stop managed containers) implies container:read.
  • provider:read lists installed providers and provider:manage installs or removes provider executables (and implies provider:read).
  • config:basic_read reads non-sensitive config metadata (auth and git auth entry names, specs, the permission catalog) and is implied by config:read.
  • apikey:manage:self lets a user create, list and delete their own API keys.
  • admin is the super-user permission that bypasses every check. admin:manage governs changes to who holds admin (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 needs app:create, republishing an existing app needs app:update, and unpublishing needs app:delete (local mode publishes also run through the declarative apply, which enforces app:apply and app:approve before any file is staged). The preview dev app a session creates under the configured preview_path is authorized by builder:create itself (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 the admin super-user permission, e.g. the openrun-admin role).
  • Setting the --approve flag on a create/reload/apply, or calling approve directly, requires this permission on every matched app.
  • Creating a sync entry with approve set requires app:approve granted with target all (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 admin or admin:manage (listing either literally or composing a role that does, such as role:openrun-admin)
  • the users and roles of 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:manage grants are protected the same way as admin grants, so granting oneself admin:manage is not a route to admin.
  • The rest of the config (other grants, roles and groups, the protected grants’ description and targets, config entries and settings) stays editable with config:update. A grant’s description and targets do not affect who holds admin, since admin is a global permission.
  • The same rule applies to builtin users: openrun user add or user update placing a user in, or removing a user from, a group an admin grant references (directly or through a nested group) requires admin:manage in addition to user:create/user:update.
  • Any change to a builtin user who holds admin or admin:manage also requires admin:manage, whichever way the user holds it (a group, a grant naming builtin:<name>, a config group entry or a regex: pattern): setting the password, unlocking, enabling, disabling, deleting, or creating the user such a grant names. Without it, user:manage would be a route to signing in as an admin.
  • admin:manage is not part of any built-in role other than openrun-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 admin and app:approve, it is never matched by a permission glob in a role (* or admin:*) and must be named literally in API key scopes.
  • Local CLI calls over the unix domain socket run as the trusted admin and are not subject to this check unless --as is 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 (admin over 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 admin permission with an unscoped credential runs unrestricted.
  • Manual sync run calls are authorized against the caller’s own current grants, not the stored snapshot.
  • The creator of a sync entry keeps the sync:run, sync:delete and sync:read owner permissions on it.

App jobs follow their execution context:

  • Manual jobs and before_deploy jobs 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 groups key. 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 needs user:manage).
  • Point an app at it with --auth builtin, and exercise grants with curl -u alice:password.
  • The user id in grants is builtin:alice; the groups of the user are matched by group: 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.
  • --as works 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 feed group: matching.
  • Any other <provider>:<username> id (like github: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

HeaderValue
X-Openrun-UserThe 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-IdThe provider user ID claim, when available. For OIDC providers this is the sub claim.
X-Openrun-User-EmailThe provider email claim, when available.
X-Openrun-PermsThe 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-EnabledWhether 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:access grant to reach an app (the default grant provides it to every authenticated principal). The rbac: 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 admin unless --as is used. Remote CLI calls run as the authenticated credential’s user, with RBAC enforced.
  • For apps with no authentication (using none auth), the user ID to use in RBAC is anonymous, without the auth type prefix.