Roles, groups, and permissions

Roles allow users to perform actions in the Decodable platform. You can use roles to control access to Decodable resources. As users don’t receive permissions and capabilities directly, roles connect users to how they interact with Decodable.

You can assign roles to users to control the scope of the tasks that they can perform, and which resources they can access in the system. Roles don’t take away access, so if you don’t want a user to perform a certain function, then that user must not hold any role with permissions that let them perform that function.

Decodable includes two groups and roles with your account to start: an admins group that’s assigned with the admin role and a new-users group that’s assigned with the new-user role. Each new user who accepts an invitation to your Decodable account (and uses that account) starts in the new-users group. You can change the permissions on the new-user role, but not the admin role.

View and manage users, groups, and roles

You can see what users, groups, and roles are available in your account by performing the following steps.

  1. From the Decodable web interface, select the Account dropdown in the top-right corner and select Manage Access Control. The Access Control view opens.

  2. Select the Users, Groups, or Roles to open the management page for each component.

Users

A user represents the human user interacting with Decodable resources. Users are assigned to one or more groups. You can see what groups and roles a specific user is assigned to in the Users page.

A user record is created for the account the first time that user uses that account. It’s not enough to accept the invite. They must click through to any page in the account itself, or use the Decodable CLI against that account. Once that has happened, the user will appear in the list on the Users page, and may be assigned groups. Initially they will be only in the new-users group.

Groups

A group is a collection of users who are grouped together for administrative or security purposes. A group has assigned roles that define the permissions that the users of that group have. For example, all users of the admins group have special permissions allowing them to perform certain tasks within Decodable. By assigning users to groups rather than assigning roles individually, you can efficiently manage permissions for multiple users and teams.

Every Decodable account includes an admins group and a new-user group. When you invite a new user to the Decodable account, that user is automatically added to the new-user group.

To add a new group, complete the following steps.

  1. From the Decodable web interface, select the Account dropdown in the top-right corner and select menu:Manage Access Control[Groups].

  2. Select New Group.

  3. Enter a group name and select Create group to create the new group. The details page of the newly created group opens.

  4. Select the users that you want to make a member of this group.

  5. Then, select the Roles tab and select the roles that members of this group will have. The permissions that are assigned to these roles will be available to all group members.

Roles and permissions

Roles are sets of permissions that are assigned to groups based on their job responsibilities or other criteria. Permissions provide operational access to resources in an account. Permissions are assigned to roles rather than users. Roles are then assigned to groups. Finally, users are added to groups and access the permissions designated to those groups. For example, a user would be assigned the role of admin by being added to the admin group, which would grant them full permissions for managing resources like streams and pipelines.

Every Decodable account includes an admin role and a new-user role. By default, the admin role and the new-user role have the same set of permissions (*:*:* granting full access to all resources in the account). You can change the permissions that the new-user role has, but you can’t modify the permissions for the admin role.

To add a new role, perform the following steps.

  1. From the Decodable web interface, select the Account dropdown in the top-right corner and select menu:Manage Access Control[Roles].

  2. Select New Role.

  3. Enter a role name and select Create role to create the new role. The details page of the newly created role opens.

  4. Select the Permissions tab, and enter the permissions that you want to assign to the role. Permissions are represented as permission strings. See the Manage permissions section for details on how to construct the permission string.

  5. Then, select the Groups tab and add the groups that you want to assign to this role. The permissions that are assigned to the role will be available to all group members.

Manage permissions

A permission refers to the level of access assigned to a role that specifies how a group with that role can interact with resources in Decodable. Permissions are represented as permission strings, which have the following pattern: <type>:<action>:<qualified-name>. These permission placeholders are defined as follows:

  • Type: The resource type that you want to set permissions for. Must be one of the following: account, connection, secret, stream, pipeline, group, role, user, or *.

  • Action: The operation that you want to grant permissions for. Typically one of the following: read, read-data, write, write-data, delete, activate, or *.

    • The read-data and write-data actions are only applicable to streams.

    • The activate action is only applicable to connections and pipelines.

  • Qualified name: The name of the specific object that you want to set permissions for. The qualified name for the connection, stream, or pipeline resource types must be prepended with the word default. For example, if you want to grant read permissions to a stream called user_locations, then the permission string looks like: stream:read:default.user_locations.

    • You can use *to match string values. For example, if you want to grant read permissions to all streams whose names start with user_, then the permission string looks like: stream:read:default.user_*.

Common permission pattern examples

The following are common permission patterns. You can use these examples to guide you in writing your own permission patterns to assign to roles.

Permission pattern What it enables

*:read:*

View all resources in the account.

pipeline:write:*

Create or edit all pipelines.

pipeline:write:default.marketing_*

Edit all pipelines that begin with marketing_ and create pipelines that begin with marketing_.

stream:read*:*

Allow the user to view metadata and access the underlying data from any stream (read and read-data, respectively).

role:write:analyst

Edit the custom role analyst.

group:write:team-finance user:read:*

Add a user to the custom group team-finance.

*:*:*

Grants access to every part of the account.

Add or edit a permission

You can add or edit permissions from the Roles page.

  1. From the Decodable web interface, select the Account dropdown in the top-right corner and select menu:Manage Access Control[Roles].

  2. Select the role that you’d like to edit permissions for to open the details page for that role, and select Permissions.

  3. Add or edit a permission string that corresponds to the access level that you want this role to have.

Example: Grant a user read-only access to all resources in an account

To grant a user read-only access to your account, make sure the user’s role has the *:read:* permission string and no other permission strings that grant permissions to perform other actions.

Assign this permission to a user by adding it to an existing role or by creating a new role, and then adding that role to a group that the user is a member of.

Perform the following steps to create a custom role that has read-only permissions, assign that custom role to a group, and add a user to that group.

  1. Create a new role.

    1. From the Roles page, select New Role and enter a name for the role. For example: reader.

    2. Select Create role. The details page for the newly created role opens.

  2. Add permissions to the newly created role.

    1. Select the permissions tab and enter the following permission string: *:read:*. This permission string grants read access to all resources in the account.

    2. Select the checkmark icon to save the permission.

  3. Create a new group and assign the newly created reader role to that group.

    1. Navigate to the Groups page, and select New Group.

    2. Enter a name for the group. For example, readers. Then, select Create Group. The details page for the newly created group opens.

    3. Select Roles and then select the role that you created earlier to assign that role to this group.

  4. Add the user to the group and remove the user from any other groups that grant them additional permissions.

    1. Select the Users tab and then select the user that you want to add to the new readers group.

    2. Make sure to remove the user from any other group that grants them permissions other than read. You can see what groups a user is in from the Users page.