Skip to main content
Version: 3.1

RBAC Overview

Portworx supports Role-based Access Control (RBAC) over both cluster operations and volume operations. The platform provides namespace-granular, role-based authentication, authorization, and ownership in addition to volume encryption.

This document walks you through the different components used to secure Portworx through RBAC.

General considerations

Portworx RBAC centers around the ubiquitous JWT based authentication and authorization model. This technology is currently used by most major internet sites and applications, providing a proven secure model for user and account identification.

A token is generated by a token authority and signed using either a private key or a shared secret. Then, the user provides the token to Portworx for identification. No passwords are ever sent to Portworx.

This secure model enables Portworx to need to verify only the validity of the token to authenticate the user. Portworx then destroys the token ensuring that tokens are never saved on a Portworx system.

The token contains a section called claims which identifies the user and provides authorization information in the form of RBAC. Portworx uses the RBAC information to determine if the user is authorized to make the request.


ACLAccess Control List identifying those accounts which can access a resource
claimsInformation contained in the payload of the JWT identifying the owner of the request
COContainer Orchestration System like Kubernetes, Mesosphere, or Nomad
RBACRole Based Access Control defined by the rules of a role
roleA named set of rules
rulesA description of the permissions for a role
tokenA JSON Web Token which is signed by a token authority identifying the owner of the request
TAtoken authority, an application used to generate and sign an identification token

Security tokens

To enable Portworx security the administrator can generate a token using their own Token Authority (TA). The administrator can also generate user tokens using the pxctl command-line tool. For more details, refer to generate token.

For Portworx to verify the tokens are valid, they must be signed with any of the following:

  • a shared secret
  • an RSA private key
  • an ECDSA private key

Portworx must also be configured with the same shared secret or a pair of keys.

Required JWT claims

Portworx requires a set of claims to be provided in order to authorize the user. The following table lists the set of required claims:

issstringName of the issuer. Portworx utilizes this information to determine if the token was issued by a trusted token authority
substringUnique identifier of the user. It is used to determine access control of resources
expdateExpiration date
iatdateIssued at time
namestringName of the user
emailstringEmail of the user. Portworx may be configured to use the email as the unique identifier of the user
rolesstring array(custom claim) Portworx RBAC roles
groupsstring array(custom claim) List of groups the user is part of, used determine access control of resources

Portworx RBAC Security Models

Portworx RBAC security is composed of three models:

  1. Authentication: A model for verifying the token is correct and generated from a trusted issuer.
  2. Authorization: A model for verifying access to a particular request type according to the role or roles applied to the user.
  3. Ownership: A model for determining control of resources.

1. Authentication

Authentication is based on RBAC for all clients in the stack and an ownership model that is similar to UNIX-style permissions. Portworx will determine the validity of a user through a token-based model. The token is created by the TA and contains information about the user in the claims section. When Portworx receives a request from the user, it checks the accompanying token's validity by verifying its signature, using either a shared secret or a public key provided during RBAC's initial configuration.

2. Authorization

Once the token has been determined to be valid, Portworx then checks if the user is authorized to make the request. The roles claim in the token must contain the name of an existing default or customer registered role in the Portworx system. A role is the name given to a set of RBAC rules which enable access to certain SDK calls. Custom roles can be created using pxctl or through the OpenStorage SDK.

See also Role management using pxctl.


Ownership is the model used for resource control. The model is composed of the owner and a list of groups and collaborators with access to the resource. Groups and collaborators can also have their access to a resource constrained by their access type. The following table defines the three access types supported:

ReadHas access to view or copy the resource. Cannot affect or mutate the resource.
WriteHas Read access plus permission to change the resource.
AdminHas Write access plus the ability to delete the resource.

For example, user1 could create a volume and give Read access to group1. This means that only user1 can mount the volume. However, group1 can clone the volume. When a volume is cloned, it is owned by the user who made the request.

Public volumes

A volume will be considered public if it does not have any ownership associated with it. Ownership is added automatically based on the token used during volume creation. If a volume isn't public however it will have ownership and is considered "private".

In addition, volumes may be explicitly marked public via pxctl.

The system.guest role (see below) can always access public volumes.

Built-in Roles

The Administrator Role

Similar to the root user in a UNIX-based system (such as Linux), Portworx has the concept of a system administrator. This role is not constrained by RBAC and participates in every group. The built-in RBAC role for system administrators is called system.admin and gives the caller access to every API call. To have access to every resource, a user must be in group *, which means they are part of every group. Their token claims would then look like this:

"roles" : [ "system.admin" ],
"groups": [ "*" ]

Guest Access Role

Portworx (as of version 2.6) also has a role for Guest Access. This role allows your users to access and manipulate public volumes. The system.guest role is used whenever a user does not pass a token to any Portworx operation or SDK call. This role, by default, allows all standard user operations such as Create, Delete, Mount and Unmount for any volume that is marked as public.

Volumes can also be marked public if they were created before the PX-Security feature was enabled, or if they are created without a token. This simplifies the process for upgrading from an auth disabled deployment to one with a auth enabled. The admin may also explicitly mark a volume as public to expose it to the guest role.

The role is mutable and is named system.guest. This allows the admin to change how the auth system behaves when an unauthenticated user interacts with it. More strict security requirements allow admins to disable the guest role entirely if they necessary.


For more information, see also:

Was this page helpful?