Authorization using pxctl
This document outlines how to interact with an authorization-enabled Portworx cluster. The main way to do it is by using the
pxctl context command. Also, you can integrate with an OIDC provided token or generate self-signed tokens through
pxctl. See the generate self-signed tokens page for more details.
Portworx stores the following locally to your home directory, allowing you to switch between configurations with a few commands:
- associated clusters
local to your home directory. This allows you to switch between these configurations with a few commands.
pxctl context command with the
--help flag to list the available subcommands and flags:
/opt/pwx/bin/pxctl context --help
Portworx pxctl context commands for setting authentication and connection info Usage: pxctl context [flags] pxctl context [command] Aliases: context, ctx Available Commands: create create a context delete delete a context list list all contexts set set the current context unset unset the current context Flags: -h, --help help for context 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 context [command] --help" for more information about a command.
Create a context
You can create a new context by running the
pxctl context create command and passing it the following arguments:
- the name of the context
--tokenwith the token Portworx must use for this context
--endpointwith the endpoint for this context
Here’s an example of how you can create a new context:
pxctl context create <context> --token <token> --endpoint <endpoint>
Delete a context
To delete a context, run the
pxctl context delete command with the name of the context as in the following example:
pxctl context delete <context>
List your contexts
Portworx stores your contexts in the
~/.pxctl/contextconfig directory. Use the
pxctl context list command to view them:
pxctl context list
contextconfig: current: user configurations: - context: user token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImpzdGV2ZW5zQHBvcnR3b3J4LmNvbSIsImV4cCI6MTU1MzcyNTMyMSwiZ3JvdXBzIjpbInB4LWVuZ2luZWVyaW5nIiwia3ViZXJuZXRlcy1jc2kiXSwiaWF0IjoxNTUzNjM4OTIxLCJpc3MiOiJwb3J0d29yeC5jb20iLCJuYW1lIjoiSmltIFN0ZXZlbnMiLCJyb2xlcyI6WyJzeXN0ZW0udXNlciJdLCJzdWIiOiJqc3RldmVuc0Bwb3J0d29yeC5jb20vanN0ZXZlbnMifQ.pZDbCIL7ldcImvIaNSjk18Ah3LqxX63MV378NiauRwk identity: subject: email@example.com/jstevens name: Jim Stevens email: firstname.lastname@example.org endpoint: http://localhost:9001
Select the current context
Once you’ve created your contexts, use the
pxctl context command to switch between them. Under the hood, Portworx reads your current context and then uses the associated token for all commands.
--contextflag to run a single command with a given context.
Use the following command to set the current context:
pxctl context set <context>
Unset the current context with:
pxctl context unset
Portworx supports two methods of authorization:
- OIDC and
To generate a token through your OIDC provider, see the documentation on generating bearer tokens on the website of the provider. The following links direct you to the most commonly used OIDC providers:
Note that, for self-signed tokens, you can use your own JWT compliant application. Furthermore, for convenience, the
pxctl CLI tool provides a command for generating tokens. See the self-signed tokens page for more details.
How to debug token issues
This section explains how to debug common token issues.
Permission denied issues
Problem symptom: You see an unexpected
Permission denied or other auth-related error.
Find the root cause: Take a look into your token permissions. Decode and verify your token with a JWT token decoding tool such as jwt.io
Problem symptom: you see an error message similar to
rpc error: code = Internal desc = stream terminated by RST_STREAM with error code: PROTOCOL_ERROR.
Find the root cause: Make sure your token doesn’t contain a newline character. The
gRPC/http2 protocol doesn’t allow newline characters.
that your token does not accidentally contain a newline character. This is due to gRPC/http2 not allowing newline characters.
- For information about enabling and managing Portworx authorization through Kubernetes, refer to the Authorization page.