lbcli create jwt (2.1 and above)
JWT, or JSON Web Token, is designed to securely transmit encoded data across any network, with its contents signed to ensure integrity. Lightbits utilizes JWTs to authenticate and authorize all API calls using RestAPI, and lbcli (which uses gRPC interactions).
All API/CLI commands enforce strict permission controls, using JWTs for authentication. During deployment, the Ansible process generates a cluster-admin JWT that grants system-wide permissions.
Synopsis
Generates and prints out a JWT for access to a Lightbits cluster.
lbcli create jwt [flags]Examples:
# generate a JWT with role "proj-1:admin" using private key from file "/tmp/root-key.pem":lbcli create jwt --role "proj-1:admin" --key=/tmp/root-key.pem --key-id=system:cluster-admin --issuer=root@example.com --subject=tenant-1"# generate a JWT with role "proj-1:viewer" using private key from file "/tmp/tenant-1-key.pem":lbcli create jwt --role "proj-1:viewer" --key=/tmp/tenant-1-key.pem --key-id=proj-1:manager --subject=mon-dashbord"# generate a JWT with expiry date of Jan 1 2028":lbcli create jwt --role "proj-1:admin" --key=/tmp/root-key.pem --key-id=system:cluster-admin --expiry=2028-01-01T00:00:00+00:00"| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| --expiry | string | JWT expiration time in RFC3339 format (default: 30 days from now). | ||
| --help | -h | bool | Help for jwt. | |
| --issuer | string | Authority signing this JWT. | ||
| --key | string | Path to PEM-encoded private key file to sign this JWT with (required). | ||
| --key-id | string | Corresponding public key name in Lightbits, in '<scope>:<name>' format (required). | ||
| --role | string | Lightbits role in '<scope>:<name>' format (required). | ||
| --subject | string | "lightos-client" | Entity this JWT is being issued to; e.g., user or application name. |
Creating JWTs with Specific Access Scopes and Permissions
1.With $SYSTEMJWT
export SYSTEMJWT=eyJhb...s4u-w
Create a new project (as cluster-admin), Note the encrypted (https, port 443) endpoints and usage of the system jwt.
lbcli --jwt $SYSTEMJWT create project --name 22256 --description "my project"
List projects (as cluster-admin):
lbcli --jwt $SYSTEMJWT --endpoint https://localhost:443 list projects
Create a public/private RSA256 key pair:
mkdir -p ${HOME}/.lightos_keys && ssh-keygen -t rsa -f ${HOME}/.lightos_keys/mykey -q -N "" -m PKCS8 && openssl rsa -in ${HOME}/.lightos_keys/mykey -pubout -out ${HOME}/.lightos_keys/mykey.pem
ls ${HOME}/.lightos_keys
Create the first credential in the project (as cluster-admin):
lbcli --jwt $SYSTEMJWT create credential --id=c3 --project-name 22256 --type rsa256pubkey ${HOME}/.lightos_keys/mykey.pem
List credentials in the project (as cluster-admin):
lbcli list credentials --project-name=22256
2.With $ADMINJWT:
Create a project:admin JWT for new project:
lbcli create jwt --role 22256:admin --key ${HOME}/.lightos_keys/mykey --key-id=22256:c3 --issuer=root@example.com --subject=tenant-1z
export MYPROJADMINJWT=eyJhbGciOi..
Create a volume in the project as project:admin:
lbcli --jwt $MYPROJADMINJWT create volume --size="256 Tib" --name=explorevolume --acl=["ALLOW_ANY"] --replica-count=2 --sector-size=4096 --project-name=22256
- With $VIEWERJWT:
Create project:viewer JWT for a new project:
lbcli create jwt --role 22256:viewer --key ${HOME}/.lightos_keys/mykey --key-id=22256:c3 --subject=mon-dashboard
export MYPROJVIEWERJWT=eyJhbGciOiJSUz..
List volumes in the project as project:admin or project:viewer:
lbcli --jwt $MYPROJVIEWERJWT --endpoint https://localhost:443 list volumes --project-name 22256lbcli --jwt $MYPROJADMINJWT --endpoint https://localhost:443 list volumes --project-name 22256
Viewer jwt only has permission to view the projects that it is related to.
Regenerating a System Admin JWT
The default system JWT generated during Lightbits deployment expires one year after the deployment. If an expired JWT is referenced by lbcli, the following error will be returned:
# lbcli list nodesrpc error: code = Unauthenticated desc = invalid JWT bearer token: token is expired by 7h47m48sYou can use the following command to regenerate the JWT. Make sure to run the lbcli binary from the same current working directory where the cert-lb-admin-key.pem file is located. Also, modify the expiration date appropriately.
lbcli create jwt --role="system:cluster-admin" --key=cert-lb-admin-key.pem --key-id="system:root" \ --expiry=2025-04-16T00:00:00.00ZThe cert-lb-admin-key.pem can be found in the lightos-certificates directory on the Ansible server that was used to deploy Lightbits, or where it was securely stored after deployment.
- The default generated cert-lb-admin-key.pem expires after 10 years. Contact Lightbits Support to help regenerate it when the certificate nears expiration.
- You will need to save the created JWTs, as they are not automatically saved anywhere on the cluster (not in the etcd or in files).
- Without setting an expiration, a JWT expires a month after creation. Set the expiration date to be one or two years past the current date, and put a reminder in your calendar a week prior to regenerating it. It is not recommended to create a lengthy JWT if one is compromised.
Creating a System View-Only JWT
The default system-jwt has full system scope and full permissions. This view-only JWT will have full system scope, but will only be able to perform read-only commands. For example, it will be able to list nodes but not create volumes. Commands that would make an edit would create “No Permissions”.
lbcli create jwt --role="system:viewer" --key=cert-lb-admin-key.pem --key-id="system:root" \ --expiry=2025-04-16T00:00:00.00ZSave the output.