Role Based Access Control

User

A user represents an entity (person/system) which needs to be authenticated and interacts with StackStorm through the API.

User permissions are represented as a union of permission grants which are assigned to all the user roles.

By default when a new StackStorm user is created, this user has no roles assigned to it, meaning it doesn’t have access to perform any API operation which is behind the RBAC wall.

Role

A role contains a set of permissions (permission grants) which apply to the resources. Permission grants are usually grouped together in a role using specific criteria (e.g. by project, location, team, responsibility, etc.).

Roles are assigned to the users. Each user can have multiple roles assigned to it and each role can be assigned to multiple users.

Permission Grant

Permission grant grants a particular permission (permission type) to a particular resource. For example, you could grant an execute/run permission (action_execute) to an action core.local.

In general, there are five permission types available for each supported resource type:

• view - Ability to view a specific resource or ability to list all the resources of a specific type.

• create - Ability to create a new resource.

• modify - Ability to modify (update) an existing resource.

• delete - Ability to delete a specific resource.

• all - Ability to perform all the supported operations on a specific resource. For example, if you grant action_all on a particular action this implies the following permissions: action_view, action_create, action_modify, action_delete and action_execute.

In addition to that, there is also a special execute (action_execute) permission type available for actions. This permission allows users to execute (run) a particular action.

Keep in mind that in StackStorm a workflow is just an action so if you want someone to be able to execute a particular workflow, you simply need to grant them action_execute permission on that workflow.

As described in the table below, create, modify, delete and execute permissions also implicitly grant corresponding view permission. This means that, for example, if you grant action_execute permission on a particular action, the user will also be able to view and retrieve details for this particular action.

Available Permission Types

The table below contains a list of all the available permission types.

Global

Pack

Sensor Type

Action

Action Alias

Api Key

Key Value Pair

Rule

Runner Type

Execution

Trigger

Webhook

Trace

This list can also be retrieved using the RBAC meta API (GET /v1.0/rbac/permission_types).

User Permissions

User permissions (also called effective user permission set) are represented as a union of all the permission grants which are assigned to the user roles.

For example, if a user has the following two roles assigned to it:

---
    name: "role_five"
    description: "Role which grants execute permission to my_action_1"
    permission_grants:
        -
            resource_uid: "action:dummy_pack_1:my_action_1"
            permission_types:
               - "action_execute"

---
    name: "role_six"
    description: "Role which grants execute permission to my_action_2"
    permission_grants:
        -
            resource_uid: "action:dummy_pack_1:my_action_2"
            permission_types:
               - "action_execute"

The effective user permission set is:

• action_execute on action:dummy_pack_1:my_action_1

• action_execute on action:dummy_pack_1:my_action_2

RBAC system uses a whitelist approach which means there is no possibility of conflicting and contradictory permission grants in different roles (e.g. one role granting a particular permission and another role revoking it).

Resource

In the context of RBAC, a resource refers to the resource to which the permission grant applies to. Permission grants can be applied to the following resource types:

• packs

• sensors

• actions

• action aliases

• rules

• executions

• webhooks

• inquiries

• key value pairs

A resource is identified by a uid, and referenced as such in permission grants. UID is an identifier which is unique for each resource in the StackStorm installation. UIDs follow this format: <resource type>:<resource specific identifier value> (e.g. pack:libcloud, action:libcloud:list_vms, key_value_pair:st2kv.system:key1, key_value_pair:st2kv.user:key2 etc.).

You can retrieve the UID of a particular resource by listing all the resources of a particular type or by retrieving details of a single resource using either API or CLI.

For example:

st2 action list
+-------------------------+-------------------------+-----------+-------------------------+-------------------------+
| uid                     | ref                     | pack      | name                    | description             |
+-------------------------+-------------------------+-----------+-------------------------+-------------------------+
| action:core:remote      | core.remote             | core      | remote                  | Action to execute       |
|                         |                         |           |                         | arbitrary linux command |
|                         |                         |           |                         | remotely.               |
+-------------------------+-------------------------+-----------+-------------------------+-------------------------+

Permission Inheritance

Pack resources

Pack resources inherit all the permissions from a pack. This means that if you grant action_execute permission to a pack, the user will be able to execute all the actions inside that pack. Similarly, if you grant rule_create permission to a pack, the user will be able to create new rules in that pack.

Executions

Executions inherit permissions from the action they belong to and from the action’s parent pack. This means that if you grant action_view permission on a particular action, the user will be able to view all the executions which belong to that action. Similarly, if you grant action_view to the parent pack which the action execution belongs to, the user will be able to view all the executions which belong to the action with that parent pack.

On top of that, granting action_execute on a particular pack or action also grants execution_rerun and execution_stop to all the executions which belong to that action.

Rule enforcements

Rule enforcements (models that represent when a rule evaluated actually resulted in an action) inherit permissions from the rule they belong to and from the rule’s parent pack. This means, if a user has a rule_view permission on a particular rule, then they also have permissions to view the rule enforcement model for the rule. Similarly, if you grant rule_view to the parent pack of the rule, users will be able to see all enforcements of rules belonging to that pack.

Note that rule enforcements are operational models. You cannot create/modify/delete them via API. So permissions other than view and list do not make sense.

Inquiries

Inquiries inherit response permissions based on execution permissions of the workflow that generated them. This is useful for ensuring that anyone that has rights to execute a workflow that generates an Inquiry is also automatically granted permissions to respond to that Inquiry.

Specifically, granting action_execute on a workflow action, or its parent pack, also grants inquiry_respond permissions for any Inquiries generated from that Workflow.

For detailed examples, see Securing Inquiries.

Permissions and Executions Which Are Not Triggered via the API

Normally when an execution is triggered via the API (POST to /actionexecutions/), the authenticated StackStorm user who triggered the execution is the effective user for RBAC purposes. There are some exceptions, described below:

Rules - Effective user for executions which are triggered by a rule is the system user (by default, stanley).

ChatOps - Effective user for executions which are triggered via ChatOps (POST to /aliasexecutions/) using hubot is the StackStorm user that is configured in hubot (ST2_AUTH_USERNAME - by default that is chatops_bot).

Defining Roles and Permission Grants

Roles and permission grants are defined in YAML files which are stored in /opt/stackstorm/rbac/roles/. Each file defines role information and associated permission grants for a single role which means that if you want to define n roles you will need n files.

Example role definition (/opt/stackstorm/rbac/roles/role_sample.yaml):

---
    name: "sample"
    description: "Role which contains many different permission grants and serves for demonstration purposes"
    enabled: false
    permission_grants:
        -
            # Here we grant "pack_all" to "dummy_pack_1" pack which means user can perform all the
            # operations on this pack.
            resource_uid: "pack:dummy_pack_1"
            permission_types:
               - "pack_all"
        -
            # Here we grant "action_view" and "rule_view" to "dummy_pack_1" pack which means user
            # can view (list) all the actions and rules inside this pack.
            resource_uid: "pack:dummy_pack_1"
            permission_types:
               - "action_view"
               - "rule_view"
        -
            # Here we grant "rule_create" to "dummy_pack_1" pack which means user can create new
            # rules inside this pack.
            # Note: To be able to create a rule user also needs to have an "action_execute" permission
            # on the action used inside the rule. In case the rule trigger type is a webhook, user also
            # needs to have "webhook_create" permission on the corresponding webhook.
            resource_uid: "pack:dummy_pack_1"
            permission_types:
               - "rule_create"
        -
            # Here we grant "webhook_create" which allows user to create a webhook with a name of
            # "my_sample_webhook".
            # Keep in mind that webhooks have no parent resource so the permission grant is
            # directly on the webhook you want to allow a user to create.
            resource_uid: "webhook:my_sample_webhook"
            permission_types:
               - "webhook_create"
        -
            # Here we grant "action_execute" to "dummy_pack_2" which means user can execute (run)
            # all the actions inside this pack. Execute permission also grants "execution_re_run"
            # and "execution_stop" which means user can also re-run and stop (cancel) all the
            # executions which are triggered for the actions which belong to this pack.
            resource_uid: "pack:dummy_pack_2"
            permission_types:
               - "action_execute"
        -
            # Here we grant "action_all" to action "my_action_1" inside "dummy_pack_2" which means
            # user can perform all the operations (view, modify, execute and delete) on the
            # specified action.
            resource_uid: "action:dummy_pack_2:my_action_1"
            permission_types:
               - "action_all"
        -
            # Here we grant "action_execute" to action "my_action_2" inside "dummy_pack_2" allowing
            # user to execute (run) this particular action.
            resource_uid: "action:dummy_pack_2:my_action_2"
            permission_types:
               - "action_execute"
        -
            # Here we grant "rule_view" and "rule_modify" to rule "my_rule_1" inside "dummy_pack_2" allowing
            # user to view and modify (but not delete) this particular rule.
            resource_uid: "rule:dummy_pack_2:my_rule_1"
            permission_types:
               - "rule_view"
               - "rule_modify"
        -
            # Here we grant "webhook_send" to a webhook named "st2" (that's a generic webhook which exists
            # by default in every installation) allowing user to POST triggers to this particular webhook.
            # Keep in mind that the user needs to have "webhook_create" permissions on a particular webhook
            # if you want to allow user to create / register a new webhook via rule.
            resource_uid: "webhook:st2"
            permission_types:
               - "webhook_send"
        -
            # Here we grant "action_list" and "rule_list" allowing user to view / list all the actions and
            # rules
            permission_types:
               - "action_list"
               - "rule_list"

The example above contains a variety of permission grants with corresponding explanations (comments).

Defining User Role Assignments

User role assignments are defined in YAML files which are located in /opt/stackstorm/rbac/assignments/. Each file defines assignments for a single user which means that if you want to define assignments for n users, you will need n files.

Example role definition (/opt/stackstorm/rbac/assignments/user4.yaml):

---
    username: "user4"
    roles:
        - "role_one"
        - "observer"

In the example above we assign two roles to the user named user4:

• role_one (a custom role which needs to be defined as described above) and

• observer (system role).

Key Value Pairs

Users with admin and system_admin roles have all access to system scoped KVPs. In v3.6.0 and before, users with admin role have full access to other users’ KVPs. This behavior is unchanged.

By default, a user has access to his/her own user scoped KVPs without requiring specific permission grants. A non-admin user by default cannot access system scoped KVPs or other users’ KVPs. A non-admin user can be explicitly granted permission to one or more system scoped KVPs similar to how access to other resources are granted to users. Currently, there is no option or plan to grant non-admin user access to another user’s set of KVPs.

The following is an example to assign a system scoped KVP to a role. Create /opt/stackstorm/rbac/roles/key1_write_role.yaml with the following content. Assign this role to a user and then apply the RBAC definitions.

---
name: key1_write_role
description: Role that allow users to set system key1
enabled: true
permission_grants:
    - resource_uid: "key_value_pair:st2kv.system:key1"
      permission_types:
        - "key_value_pair_set"

How LDAP Group-Based Role Assignments Work

Role assignments based on the LDAP group to StackStorm role mappings are synchronized each time a user authenticates with the StackStorm auth API and receives a fresh auth token.

If for some reason you want user roles to be synchronized before the existing auth token expires (default TTL is 24 hours), you can simply ask the user to re-authenticate to retrieve a new auth token. Alternatively, administrators can manually expire or disable an active auth token which will force the user to re-authenticate.

A similar workflow can be used when removing a user from your system. By default, when a user is removed from LDAP they will still be able to use StackStorm if they have a valid auth token, until that auth token expires. If you want user access to be revoked as soon as they are removed from LDAP, you can manually purge active auth tokens for a particular user from the user database.

1. Admin user (can view all the resources)

Authenticated as a user with admin role.

curl "https://localhost/api/v1/rules"

[
    {
        "name": "rule1",
        "ref": "examples.rule1",
        ...
        "context": {
            "user": "admin"
        },
    },
    {
        "name": "rule2",
        "ref": "examples.rule2",
        ...
        "context": {
            "user": "user2"
        },
    },
    {
        "name": "rule3",
        "ref": "examples.rule3",
        ...
        "context": {
            "user": "user2"
        },
    },
    {
        "name": "rule4",
        "ref": "examples.rule4",
        ...
        "context": {
            "user": "user3"
        },
    },
    {
        "name": "rule5",
        "ref": "examples.rule5",
        ...
        "context": {
            "user": "user3"
        },
    }
]

2. User “user2” can only view their own resources

Authenticated as “user2”.

curl "https://localhost/api/v1/rules"

[
    {
        "name": "rule2",
        "ref": "examples.rule2",
        ...
        "context": {
            "user": "user2"
        },
    },
    {
        "name": "rule3",
        "ref": "examples.rule3",
        ...
        "context": {
            "user": "user2"
        },
    }
]

3. User “user3” can only view their own resources

Authenticated as “user3”.

curl "https://localhost/api/v1/rules"

[
    {
        "name": "rule4",
        "ref": "examples.rule4",
        ...
        "context": {
            "user": "user3"
        },
    },
    {
        "name": "rule5",
        "ref": "examples.rule5",
        ...
        "context": {
            "user": "user3"
        },
    }
]

User Creation

All user and password management is kept outside of StackStorm. Read the authentication docs to see how to configure to configure StackStorm with various identity providers.

For sake of this example let us assume that the identity provider is managed by the OS on which StackStorm runs.

On most Linux systems, to create a user and set their password, run this:

$ useradd rbac_user1
$ passwd rbac_user1

Once this user is created StackStorm will allow access to this user. (Optional) To validate, try:

$ st2 login rbac_user1 -p '<RBACU1_PASSWORD>'
$ st2 action list

Role Creation

A newly created user has no assigned permissions. Each permission must be explicitly assigned to a user. To assign permission grants requires creation of a role and then associating this role with a user. In this case we are trying to create a pack owner role.

Lets first make sure there is a pack example we can use to experiment.

$ cd /opt/stackstorm/packs/
$ mkdir example
$ mkdir example/actions example/rules example/sensors
$ touch example/pack.yaml
$ touch /opt/stackstorm/configs/example.yaml
$ touch example/requirements.txt
$ cp core/icon.png example/icon.png

Now we setup a role. Create /opt/stackstorm/rbac/roles/example_pack_owner.yaml with the following content:

---
name: "example_pack_owner"
description: "Owner of pack example"
enabled: true
permission_grants:
    -
        resource_uid: "pack:example"
        permission_types:
           - "pack_all"
           - "sensor_type_all"
           - "rule_all"
           - "action_all"
    # Note: To be able to create a rule, the user also needs to have an "action_execute" permission
    # on the action used inside the rule. In this example, the rule created calls core.local action
    -
        resource_uid: "action:core:local"
        permission_types:
           - "action_execute"
    # Need runner_type_list on relevant runners
    -
        resource_uid: "runner_type:local-shell-cmd"
        permission_types:
           - "runner_type_list"

A pack owner role would require the user to be able to view, create, modify and delete all contents of a pack. Again, let’s pick the pack example as the target of ownership.

See available permission types for a full list of permission types.

Role Assignment

Creation of a role is followed by assignment of a role to the user. Create the file /opt/stackstorm/rbac/assignments/rbac_user1.yaml with the following content:

---
username: "rbac_user1"
description: "Grant example_pack_owner role to rbac_user1 user."
enabled: true
roles:
    - "example_pack_owner"

Applying RBAC

As a StackStorm administrator, run:

st2-apply-rbac-definitions --config-file=/etc/st2/st2.conf

This command will sync the StackStorm RBAC state with the filesystem state. Only after running this command does StackStorm know of the latest changes to RBAC permission grants.

Validation

Lets take this for a spin using the StackStorm CLI.

1. Setup Authentication token:

$ st2 login rbac_user1 -p '<RBACU1_PASSWORD>'

1. Validate rule visibility and creation:

$ cd /opt/stackstorm/packs/example
$ cp /usr/share/doc/st2/examples/rules/sample_rule_with_timer.yaml rules/
$ sed -i 's/pack: "examples"/pack: "example"/g' rules/sample_rule_with_timer.yaml
$ st2 rule create rules/sample_rule_with_timer.yaml
$ st2 rule get example.sample_rule_with_timer
$ st2 rule delete example.sample_rule_with_timer

# Expect Failure
$ st2 rule get <EXISTING_RULE_REF>

1. Validation action visibility, creation and execute:

$ cd /opt/stackstorm/packs/example
$ cp /usr/share/doc/st2/examples/actions/local.yaml actions/
$ echo "pack: example" >> actions/local.yaml
$ st2 action create actions/local.yaml
$ st2 action get example.local-notify
$ st2 run example.local-notify hostname
$ st2 action delete example.local-notify

# Expect failure
$ st2 action get core.echo
$ st2 run core.echo hello