RBAC Overview

Portworx has always provided support for volume encryption in order to keep data secure. Starting with version 2.1, Portworx introduced support for RBAC. Thus, the platform provides namespace-granular, role-based authentication, authorization, and ownership in addition to 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 systems, providing a proven secure model for user and account identification.

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

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

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


Term Definition
ACL Access Control List identifying those accounts which can access a resource
claims Information contained in the payload of the JWT identifying the owner of the request
CO Container Orchestration System like Kubernetes, Mesosphere, or Nomad
JWT JSON Web Token
OIDC OpenID Connect
RBAC Role Based Access Control defined by the rules of a role
role A named set of rules
rules A description of the permissions for a role
token A JSON Web Token which is signed by a token authority identifying the owner of the request
token authority Application used to generate and sign an identification token

Security Tokens

Portworx security supports two types of token generation models: OIDC and self-generated tokens. OpenID Connect (or OIDC) is a standard model for user authentication and management and is a great solution for enterprise customers due to its integration with SAML 2.0, Active Directory, and/or LDAP. The second model is a self-generated token, where the administrator would generate a token using their own TA application. For convenience, Portworx provides a method of generating tokens using pxctl.

For Portworx to verify the tokens are valid, they must be signed with either a:

  • shared secret, or
  • an RSA private key, or
  • an ECDSA private key.

Also, Portworx must be configured with the same shared secret or 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:

Claim Type Description
iss string Name of the issuer. Portworx utilizes this information to determine if the token was issued by a trusted token authority
sub string Unique identifier of the user. It is used to determine access control of resources
exp date Expiration date
iat date Issued at time
name string Name of the user
email string Email of the user. Portworx may be configured to use the email as the unique identifier of the user
roles string array (custom claim) Portworx RBAC roles
groups string array (custom claim) List of groups the user is part of, used determine access control of resources

Self-Generated Tokens

Token generation can be done by any JWT compliant application which sets the claims required by Portworx. For convenience, administrators can generate user tokens using pxctl. See Generating Tokens.

OpenID Connect (OIDC)

Due to its ability to manage thousands of users, it is highly recommended that enterprise customers deploy an OIDC service. There are multiple public and private OIDC providers. Customers could use public providers such as Okta.com, Auth0.com, etc, or private providers such as Keycloak, CloudFoundry UAA, Dex, or Tremolo Security OpenUnison.

In the case where the claims required by Portworx security do not match with those provided by the customer, most OIDCs have a mapping feature. This feature allows the OIDC system to return a token to Portworx where the claims have the appropriate information. Some OIDCs may namespace custom claims. This is supported by Portworx, but the namespace value must be provided to the system during initialization.

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 access to resources.

1. Authentication

Authentication is based on Role Based Access Control for all clients in the stack and an ownership model that is much like the familiar unix style permissions. Portworx will determine the validity of a user through a token-based model. The token will be created by the TA and will contain information about the user in the claims section. When Portworx receives a request from the user, it will check the token validity by verifying its signature, using either a shared secret or public key provided during 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:

Type Description
Read Has access to view or copy the resource. Cannot affect or mutate the resource.
Write Has Read access plus permission to change the resource.
Admin Has 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.

The Administrator Role

Similar to the root user in a Linux system, 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

Starting with version 2.6, Portworx introduced a new concept called Guest Role Access. The guest role allows your users to access and manipulate public volumes. The new system.guest role is now 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 public volumes.

Volumes are public if they are created before security was enabled or without a token. This simplifies the process for upgrading from auth disabled to auth enabled for Portworx 2.6+. Additionally, the admin may 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. Strict admins may disable the guest role entirely if they wish.

Public volumes

A volume is public if it does not have any ownership associated with it. Ownership is added based on the token a volume is created with. If a volume is not public, it has ownership and is considered private.

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

The system.guest can always access public volumes.


For more information, see also:

Last edited: Tuesday, Aug 18, 2020