Preparing To Enhance Security

To enable PX-Security, you must first determine which source of tokens you will be using. You can choose to leverage an OIDC provider, use self-signed tokens, or both. See the Overview for details on the pros/cons of each.

OpenID Connect (OIDC)

An OpenID Connect (OIDC) service can be used to provide your users with tokens, which are then be provided to Portworx for verification. Portworx needs to connect to your OIDC provider to automatically download the public key. This public key is used to verify that the signature of the JWT is valid.

To connect Portworx to an OIDC you will need the following information from your provider:

• OIDC client-id: This is the client name that has been setup for Portworx at the OIDC.
• OIDC issuer: The issuer is the address to the OIDC and must match the issuer value in the claims of each token generated.

Mapping groups and roles

Tokens created by OIDC must also have a groups and roles claim as mentioned in the Overview section. These sections provide the permissions necessary to access certain APIs and resources.

You may need to configure your OIDC provider to map information about your users into the roles and groups section of the JWT token. Please refer to your OIDC provider documentation on how to map values.

These claims are called custom claims and depending on your OIDC, it may place custom claims under a namespace. Portworx supports both un-namespaced and namespaced roles and groups in the JWT claims.

For example, an un-namespaced role would look as follows:

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

While a namespaced role using a namespace of https://myoidc.provider.com/ would look as follows:

{
  "https://myoidc.provider.com/roles" : [ "system.admin" ],
  "https://myoidc.provider.com/groups": [ "*" ]
}

Namespace information (if used) will need to be provided to Portworx as an initialization parameters, when first enabling PX-Security.

Self signing tokens

If you are using self-signed tokens, you then need to determine if you will be using a shared-secret or an RSA or ECDSA public/private key pair. Creating a JWT is a standard process and there are many applications and libraries for multiple languages to generate tokens. For convenience, Portworx has added support to pxctl to generate tokens.

Self signed tokens must also contain the identifier of the issuer. This value in the JWT claims is set as iss and is used by Portworx to determine if the token is from a trusted token authority.

Generating a shared secret

If you choose to use a shared secret for your self-signed tokens, here is a simple way to generate a very secure secret:

cat /dev/urandom | base64 | fold -w 64 | head -n 1

Portworx cluster authorization

When PX-Security is enabled, Portworx itself will generate its own tokens to securely communication with the cluster. For this reason, you will be asked to provide a shared secret for the system.

Verification of a token authority

To confirm that a token has the correct information, after creating the token using your preferred method, copy this token and paste it in jwt.io. Note the payload section has all the necessary claims to provide the appropriate permissions. Also note that the iss(Issuer), is correct. Portworx will use the value of iss to determine if the token comes from a trusted token authority.

Second, you can try out the token on a running Portworx system which has PX-Security enabled. There are multiple ways to do this. One is to use pxctl context on a Portworx node. You can then run a set of commands that confirm the token access. Another way is to use the REST SDK Gateway by going to http://<node ip>:9021/sdk or https://<node ip>:9021/sdk (depending on if TLS has been enabled for your Portworx system). Once that loads, click on the Authorize button, and paste your token. You can then execute a set of APIs to confirm the token access.