Step 2: Generate multitenant tokens

Summary and Key concepts

Summary

This article outlines the steps to generate and manage authentication tokens for Portworx using the pxctl command-line tool. It explains how to retrieve the shared secret stored in a Kubernetes secret, create tokens for storage administrators and tenants, and store those tokens securely in Kubernetes. These tokens are crucial for securing communication between Kubernetes and Portworx, ensuring that only authorized users can access storage resources. The article also covers how to manage tenant accounts by namespaces and how to prevent specific Kubernetes resources, like secrets, from being backed up by tools like Stork and PX-Backup.

Kubernetes Concepts

• Secret: Used to store sensitive data, such as authentication tokens, securely.
• Namespace: Used to isolate tenant resources and store tenant-specific tokens.
• kubectl: Command-line tool used to interact with Kubernetes clusters, including managing secrets and tokens.
• Annotation: Used to store metadata on Kubernetes objects, such as preventing certain resources from being backed up.

Portworx Concepts

• pxctl: The Portworx command-line tool used for managing clusters and generating authentication tokens.
• PX-Security: The security framework that secures communication between Kubernetes and Portworx.
• Administrator Role: A role that provides full access to manage Portworx resources, similar to the root user in Linux.

Now that the system is up and running, you can create tokens.

note

If you want to create your own application to generate tokens, you can base it on our open source golang example application openstorage-sdk-auth

SSH to one of your nodes and follow the steps below to use pxctl to generate tokens:

Fetching the shared secret

Fetch the shared secret, which is stored in a Kubernetes secret. Below, the secret is saved in the environment variable $PORTWORX_AUTH_SHARED_SECRET.

1. Get the shared secret:

   PORTWORX_AUTH_SHARED_SECRET=$(kubectl -n kube-system get \
         secret px-shared-secret -o json \
       | jq -r '.data."shared-secret"' \
       | base64 -d)

Generate a storage admin token

pxctl uses yaml configuration files to create tokens.

1. Create a file called admin.yaml with the the following:

   name: Storage Administrator
   email: the email of the storage admin
   sub: ${uuid} or email of the storage admin
   roles: ["system.admin"]
   groups: ["*"]

2. Create a token for the storage administrator using admin.yaml. In the example below:

   • The issuer matches the setting in the Portworx manifest of portworx.com as the set value for -jwt-issuer.

   • The example sets the duration of the token to one year -- You may want to adjust it to a much shorter duration if you plan on refreshing the token often.

     ADMIN_TOKEN=$(/opt/pwx/bin/pxctl auth token generate \
         --auth-config=admin.yaml \
         --issuer=portworx.com \
         --shared-secret=$PORTWORX_AUTH_SHARED_SECRET \
         --token-duration=1y)

3. Save the storage admin token in the pxctl context:

   /opt/pwx/bin/pxctl context create admin --token=$ADMIN_TOKEN

Generate tenant tokens

This model is based on isolating tenant accounts by namespaces. You will need to create an account for the tenant in Kubernetes and restrict it to one or more namespaces. You will then store the tenant's token in each namespace they own.

The following steps provide instructions for creating and storing the token in a namespace for the tenant:

1. Create a file called tenant-name.yaml with the following:

   name: <Tenant name>
   email: <Tenant email>
   sub: ${uuid} or email of the tenant
   roles: ["system.user"]
   groups: ["<groups the tenant participate if any"]

note

The sub is the unique identifier for this user and most not be shared amongst other tokens according to the JWT standard. This is the value used by Portworx to track ownership of resources. If email is also used as the sub unique identifier, please make sure it is not used by any other tokens. You can find more information on the rules of each of the value on the openstorage-sdk-auth repo.

2. Create a token for the Kubernetes using tenant-name.yaml:

   TENANT_TOKEN=$(/opt/pwx/bin/pxctl auth token generate \
       --auth-config=tenant-name.yaml \
       --issuer=portworx.com \
       --shared-secret=$PORTWORX_AUTH_SHARED_SECRET \
       --token-duration=1y)

3. Save the tenant Kubernetes token in a secret called <tenant namespace>/px-user-token:

   kubectl -n <tenant namespace> create secret \
     generic px-user-token --from-literal=auth-token=$TENANT_TOKEN

4. Annotate the Kubernetes secret so that other components like Stork and PX-Backup do not backup this resource.

   kubectl -n <tenant namespace> annotate secret px-user-token \
     stork.libopenstorage.org/skipresource=true

Kubernetes storage classes can now be set up to use this secret to get access to the token to communicate with Portworx.

Once you have completed the steps in this section, continue to the next section.