RBAC role management using pxctl

Overview

Starting with version 2.1, Portworx introduced support for RBAC. This document outlines how to manage your own custom roles for fine-grained access control within your Portworx clusters.

Default Roles

Portworx comes with a few standard roles that you can use when issuing tokens to users:

• system.admin: can run any command
• system.view: can only run read-only commands
• system.user: can only access volume lifecycle commands
• system.guest: similar to system.user, but for public volumes only.

All of these roles are immutable, except for system.guest. Admins may update the system.guest role to change how Portworx RBAC handles unauthenticated users.

Custom Roles

pxctl role gives you more fine-grained control over what users can do within your clusters. Let’s get a feel of the available commands by running:

pxctl role --help

Portworx pxctl authorization role commands.  Roles define permission rules for users capabilities.

Usage:
  pxctl role [flags]
  pxctl role [command]

Available Commands:
  create      Create a role
  delete      Delete a role
  inspect     Show permission rules for role(s)
  list        Show all role names
  update      Update a role

Flags:
  -h, --help   help for role

Global Flags:
      --ca string            path to root certificate for ssl usage
      --cert string          path to client certificate for ssl usage
      --color                output with color coding
      --config string        config file (default is $HOME/.pxctl.yaml)
      --context string       context name that overrides the current auth context
  -j, --json                 output in json
      --key string           path to client key for ssl usage
      --output-type string   use "wide" to show more details
      --raw                  raw CLI output for instrumentation
      --ssl                  ssl enabled for portworx

Use "pxctl role [command] --help" for more information about a command.

Creating a custom role from a JSON file

To define a custom role, you should first create a JSON file that describes that role. Say you've created a file named role.json. Then, to create the custom role, you will have to run this command:

pxctl role create --role-config role.json

If the details are fuzzy, take a moment to run the following:

pxctl role create --help

Create a role using a JSON file which specifies the role and its rules.  A role consist of a set of rules defining services
and api's which are allowable.
e.g. Rule file which allows inspection of any object and listings of only volumes:
  {
     "name": "test.view",
     "rules": [
       {
         "services": [
           "volumes"
         ],
         "apis": [
           "*enumerate*"
         ]
       },
       {
         "services": [
           "*"
         ],
         "apis": [
           "inspect*"
         ]
       }
     ]
  }

Usage:
  pxctl role create [flags]

Examples:
pxctl role create --role-config <path to json file>

Flags:
  -h, --help                 help for create
      --role-config string   (Required) create role using role json file

Global Flags:
      --ca string            path to root certificate for ssl usage
      --cert string          path to client certificate for ssl usage
      --color                output with color coding
      --config string        config file (default is $HOME/.pxctl.yaml)
      --context string       context name that overrides the current auth context
  -j, --json                 output in json
      --key string           path to client key for ssl usage
      --output-type string   use "wide" to show more details
      --raw                  raw CLI output for instrumentation
      --ssl                  ssl enabled for portworx

Role configuration

A role configuration is comprised of a name and a list of rules. Each rule has the following:

• Services: Which services you want to provide access to.
• APIs: Which APIs you want to provide access to. You can use a simple regular expression to represent multiple APIs. i.e. to allow all enumerate APIs, add an entry *enumerate* to your "apis" array (see below).

Example configuration (role.json):

The following example configuration only allows access to volume enumerate commands and all inspect APIs for every service.

{
    "name": "test.view",
    "rules": [{
            "services": [
                "volumes"
            ],
            "apis": [
                "*enumerate*"
            ]
        },
        {
            "services": [
                "*"
            ],
            "apis": [
                "inspect*"
            ]
        }
    ]
}

Services and APIs

To see all services and APIs you can use within your custom roles, see our API documentation.

Other role commands

• To delete a role, you can use pxctl role delete <name>
• To list all roles, you can use pxctl role list
• To update a role, you can use pxctl role update --role-config <path to JSON config>. This JSON config file is similar to the one used for pxctl role create.

Using your custom roles

Once you've created your custom roles, you can simply add the role names during token generation/user management.

Add the custom role in your auth-config during token creation:

name: User Name
email: user@example.com
sub: user@example.com/user
roles: ["test.view"]
groups: ["*"]

This token will now allow access to whichever services and APIs were defined in the custom role test.view.

Updating the System Guest role

Updating the system.guest role will change how Portworx authorization handles users that do not pass a token to any Portworx operation or SDK call. For more information, see the guest role overview.

Disabling the System Guest role

To disable the system.guest role, perform the following steps:

1. On one of your Portworx nodes, create the following role.json file:

   {
     "name": "system.guest",
     "rules": [{
       "services": [
         "!*"
       ],
       "apis": [
         "!*"
       ]
     }]
   }

2. Run the following pxctl role update command, specifying your role.json config:

   pxctl role update --role-config role.json

Re-enabling the system.guest role

To re-enable the system.guest role to its default behavior, perform the following steps:

1. Create the following role.json file:

   {
     "name": "system.guest",
     "rules": [{
         "services": [
           "mountattach",
           "volume",
           "cloudbackup",
           "migrate"
         ],
         "apis": [
           "*"
         ]
       },
       {
         "services": [
           "identity"
         ],
         "apis": [
           "version"
         ]
       },
       {
         "services": [
           "cluster",
           "node"
         ],
         "apis": [
           "inspect*",
           "enumerate*"
         ]
       }
     ]
   }

2. Run the following pxctl role update command, specifying your role.json config:

   pxctl role update --role-config role.json