Authorization

Authorization configuration

Key	Type	Required	Description
default_user_app_role	string	No	Default app-scoped role to assign users. App: scope will be prefixed to the value, then looked up in Roles map. Default is User.
user_app_role_mapping	map of Username/Email : App Role	No	Override a specific user's app role. Map key is the user's username/email. Map value is the Role to assign. App: scope will be prefixed to the value, then looked up in Roles map.
roles	Roles	No	Roles that can be assigned in the application.
policies	Policies	No	Policies that make up roles.

Authorization model

Control Plane ships with a set of default roles that cover access to the application, systems, accounts, and NATS users. These roles can be customized, extended, or disabled via the Control Plane config file as needed.

Statements

The root of Control Plane's access control are statements that describe resources, actions and effects:

systems_read:
  name: Read Systems
  resource:
    - /systems/**
  action:
    - GET
  effect:
    - ALLOW

• name: descriptive name of this
• resource: list of API paths over which those resources are accessed, e.g. /accounts/, /jetstream/, and /stream-exports/. Globs are supported:
  • a single * matches any character between a /
  • a double ** matches any character, including a /
  • see Open Policy Agent's full glob reference for more options
• action: list of REST API verbs: POST, PATCH, GET or DELETE
• effect: list of effects, currently must be either ALLOW or DENY. For an API endpoint to be authorized, one or more statements must evaluate to ALLOW. If a DENY is encountered, it overrides all ALLOW statements and the effect will be DENY

Policies

A policy is a collection of one or more statements:

authorization:
  policies:
    system_observer:
      name: System Observer
      description: Allows viewing configured Systems information
      statements:
        systems_read:
          name: Read Systems
          resource:
            - /systems/**
          action:
            - GET
          effect:
            - ALLOW

note

The Name field is the user friendly display name of the policy. Control Plane references the policy by its map key: system_observer in the example above

Roles

Individual policies are combined to create roles:

'System:Observer':
  enabled: true
  name: System/Account Observer
  description: Read-only access to this System and its Accounts/NATS Users
  policies:
    - system_observer
    - account_observer
  sort_order: 10

Roles are what get assigned to Control Plane Users and all policy statements are combined and evaluated for each API call.

Entities and scope

Control Plane groups its resources and access control around a hierarchy of entities:

App: Control Plane itself

System: Systems within Control Plane

Account: Accounts within a system

NatsUser: NATS users within an account

Roles must be scoped to one of these entities, and will be applied and evaluated in the context of a specific entity. For example, a System scoped role can be given to users in the context of a specific system and will only be evaluated when that system, or resources under it, are accessed. Likewise, an Account scoped role will only be evaluated when a user accesses the specific account their role was assigned in.

It is possible for roles to contain policies that allow access to resources farther down in the hierarchy, for example a System scoped role allowing access Account resources like streams. The effect is to allow access to ALL accounts within in that system, however, since the role is applied at the system level and not for a specific account.

Scope is indicated by the name of the entry in the role map: roles that begin with App: are app roles, System: system roles, Account: account roles, and NatsUser: NATS user roles. When defining a custom role it must be prefixed with one of these scopes or Control Plane will throw an error.

Customizing

Role and policy definition are handled in the authorization section of Control Plane config file. Default roles and policies that ship with Control Plane can be modified and new ones defined.

The role and policy definitions are loaded at Control Plane start, but are evaluated when the resource is accessed. If a user has been assigned a role that no longer exists or has been disabled, no policies within that role will be evaluated and the default DENY policy will be applied.

Modifying existing policies and roles

Roles and Policies are defined in the role and policy maps within the authorization section. To modify a default policy overwrite properties in the appropriate map key. For example, to disable the System:Admin role and change the display name of the Account:Admin role:

authorization:
  roles:
    'System:Admin':
      enabled: false
    'Account:Admin':
      name: Account Manager

You can override any of the properties of the default roles and policies by defining that property in their entry in the role or property map.

Creating new roles and policies

You can create custom roles and policies by defining them in the role or policy map. Custom policies can be used to override the default roles, and likewise default policies can be used inside custom roles.

For example, if we wanted to create a role that could see everything inside an account except jetstream assets, we could use the default "account_observer" policy and combine it with a custom deny policy for jetstream assets.

authorization:
  roles:
    'Account:LimitedObserver':
      enabled: true
      name: Limited Account Observer
      description: Not able to view jetstream assets
      policies:
        - account_observer
        - account_deny_jetstream
      sort_order: 20
  policies:
    account_deny_jetstream:
      name: Account Deny JetStream
      description: Deny access to all JetStream resources in an account
      statements:
        deny_jetstream:
          name: Deny JetStream
          resource:
            - /accounts/**/jetstream
            - /jetstream/**
          action:
            - GET
            - POST
            - PATCH
            - DELETE
          effect:
            - DENY

Policy and role list

Configured policies and roles can be retrieved from the API:

http(s)://<control-plane-url>/api/beta/authz/policies

http(s)://<control-plane-url>/api/beta/authz/roles

You can easily call these endpoints via the embedded API docs in Control Plane:

http(s)://<control-plane-url>/API-docs#get-/authz/policies
http(s)://<control-plane-url>/API-docs#get-/authz/roles

note

These endpoints will return all policies and roles as they are currently configured: custom roles and policies will be returned along with any modifications applied to the defaults. This is a good way to way to view the default polices for use or modification as well as ensure your modifications are working as expected.