Skip to main content

Authentication Token

Description​

This guide explains how px pxb handles authentication tokens with Keycloak and how to configure Keycloak to issue longer‑lived tokens for PX‑Backup. Token lifetimes are determined server-side by Keycloak's configuration. It follows the same structure and conventions as backup.md.

Usage​

Login​

px pxb login [--server <auth-url>] [--username <name>] [--password <pass>]

Persist Keycloak base URL (no /auth)​

px pxb set config --pxcentral-auth-url <auth-url>

View config​

px pxb view config

Status (shows token expiry)​

px pxb status config

Examples​

Login (Keycloak issues ~10h token in this example)​

px pxb login --server http://127.0.0.1:8080 --username admin --password admin
# Output: Successfully logged in. Token will expire in 10h0m0s.

Persist the Keycloak base URL in config (do not append /auth)​

px pxb set config --pxcentral-auth-url https://keycloak.example.com:31342

Check token and expiry in your config​

px pxb status config
px pxb view config

Flags for commands and sub-commands​

Login Flags​

FlagShortTypeDescription
--server-sstringAuth server endpoint (e.g., https://host:port). If omitted, uses pxcentral_auth_url from config
--username-ustringUsername for direct (non-browser) login
--password-pstringPassword for direct (non-browser) login

Set Config Flags (auth handling)​

FlagShortTypeDescription
--pxcentral-auth-urlstringPX-Central/Keycloak base URL (do not append /auth)

Notes​

  • Keycloak realm and base path
    • PX‑Backup uses the Keycloak realm: master.
    • Keycloak is accessed via the /auth/ base path.
    • px pxb automatically calls: &lt;auth-url&gt;/auth/realms/master/...
  • How px pxb determines token expiry
    • You run px pxb login with --server https://keycloak.example.com:31342 (or configured pxcentral_auth_url).
    • px pxb requests a token from Keycloak realm master using endpoints under /auth/.
    • Keycloak determines the token lifetime server-side based on its configuration (realm/client token lifespans and session limits).
    • px pxb stores the exact expiry timestamp from Keycloak in ~/.pxb/config as token_expiry.
  • Important notes
    • Token lifetimes are determined entirely by Keycloak's server-side configuration.
    • px pxb does not extend or refresh tokens automatically. For longer sessions, configure Keycloak to issue longer lifetimes, then re‑login.
  • Server URL format
    • Provide the base URL without appending /auth (e.g., https://keycloak.example.com:31342).
    • px pxb will automatically use realm master under /auth/realms/master/....
  • Where px pxb stores token info
    • px pxb status config — quick status with token expiry
    • px pxb view config — show saved fields from ~/.pxb/config
    • Fields include:
      • oidc_token — current access token
      • token_expiry — when px pxb considers the token to expire (the value Keycloak issued)
  • Configure Keycloak for longer token lifetimes
    • Token TTL Configuration Levels: There are two places where the access token TTL can be defined:
      • Realm setting — Applies to the entire realm
      • Client setting — Applies to a specific client and overrides the realm TTL
    • Portworx Backup Configuration: During the post-install hook, the client TTL is configured to 1 year. However, because the SSO Session Max in the realm is capped at 10 hours, the effective token lifetime is limited to 10 hours.
    • Recommended Configuration Method: Instead of updating at the realm level, set the TTL at the client level. For Portworx Backup, the client is pxcentral.
    • Steps to update access token TTL:
      • Sign in to the Keycloak Admin Console
      • Navigate to: Clients → pxcentral → Advanced Settings → Access Token Lifespan
      • Set the desired value (must be ≤ 10 hours due to the SSO Session Max cap)
      • Click Save
    • Important: Keycloak's OAuth 2.0 password flow does not accept a request parameter like token-duration to set the access-token TTL. The token lifetime is determined server-side by Keycloak's configuration (realm/client token lifespans and session limits).
    • Security note: Increasing token lifetimes reduces the frequency of logins but can increase risk. Align changes with your organization’s policies.

Output Format Support​

  • Not applicable: these commands print human-readable messages; --output is not supported for this guide’s commands.

Authentication and Context​

  • This guide complements the authentication flow documented in:
  • Other px pxb commands automatically use the token and expiry stored in ~/.pxb/config.