Skip to content

kc token

Overview

The kc token command obtains OIDC tokens using the authorization code flow. It opens a browser for user authentication and returns access, refresh, and ID tokens.

  • The ID token signature is checked against the server key.
  • If Access Token is in JWT form, its signature is checked against the server key.
  • If Access Token is in opaque form, it is checked against server introspection endpoint.

Syntax

kc token --issuerURL <url> --clientId <id> [options]

Flags

--issuerURL

The Kubauth OIDC issuer URL.

Example: --issuerURL https://kubauth.example.com

Value may also be fetched from KC_ISSUER_URL environment variable, or Kubernetes kubeconfig if kc init .... has been used.

--clientId

The OIDC client ID to use for authentication.

Example: --clientId public

Value may also be fetched from KC_CLIENT_ID environment variable, or Kubernetes kubeconfig if kc init .... has been used.

--clientSecret

The client secret (for confidential clients).

Example: --clientSecret mysecret123

Value may also be fetched from KC_CLIENT_SECRET environment variable, or Kubernetes kubeconfig if kc init .... has been used.

--insecureSkipVerify

Skip TLS certificate verification. Use only for testing with self-signed certificates.

Example: --insecureSkipVerify

--caFile

Provide a CA file for TLS certificate verification of ìssuerURL

Example: --caFile ./CA.crt

--onlyIdToken

Output only the ID token (base64-encoded JWT). Useful for piping to other commands or scripts.

Example: --onlyIdToken

--onlyAccessToken

Output only the access token (base64-encoded). Useful for piping to other commands or scripts.

Example: --onlyAccessToken

-d, --detailIdToken

Decode and display the JWT OIDC token payload. This is equivalent to kc token .... --onlyIdToken | kc jwt.

Example: -d

-a, --detailAccessToken

Decode and display the JWT Access token payload. This is equivalent to kc token .... --onlyAccessToken | kc jwt.

Example: -a

The Kubauth server must be configured to generate AccessToken in JWT form.

--scope

List of OAuth2 scopes to request.

Default: openid profile groups offline

Example: --scope "openid" --scope "profile" --scope "email" --scope "groups"

Warning

In its current version, Kubauth does not manage scopes. All claims are included in the JWT token.

-p, bindPort

Local web server bind port.

Default: 9921

--pkce

Use PKCE (Proof Key for Code Exchange) for enhanced security.

--browser

Override default browser. Possible values:

  • chrome
  • firefox
  • safari

Examples

Basic Usage

kc token --issuerURL https://kubauth.example.com --clientId public

output: 

if browser doesn't open automatically, visit: http://127.0.0.1:9921

Output: (After successful login) 

Access token: ory_at_xLUfAhEGpFVWpMLdNEDZAj94hHFrHWjgOYB5g0Leh_k...
Refresh token: ory_rt_nU9NBZs4NtKTxVYVko1aqlJkAMF5MLBYjfiZbhVt9aE...
ID token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImY0Y2NkNDU0LWYzYTgtNDQ3Zi1hN2MzLTY...
Expire in: 59m59s

With Decoded Token

kc token --issuerURL https://kubauth.example.com --clientId public -d

Output: 

Access token: ory_at_...
Refresh token: ory_rt_...
ID token: eyJhbG...
Expire in: 59m59s
JWT Payload:
{
  "aud": ["public"],
  "auth_time": 1763573723,
  "auth_time_human": "2025-11-19 17:35:23 UTC",
  "azp": "public",
  "email": "john@example.com",
  "emails": ["john@example.com"],
  "exp": 1763577323,
  "exp_human": "2025-11-19 18:35:23 UTC",
  "groups": ["developers", "ops"],
  "iat": 1763573723,
  "iat_human": "2025-11-19 17:35:23 UTC",
  "iss": "https://kubauth.example.com",
  "name": "John DOE",
  "sub": "john"
}

Only ID Token (for Piping)

kc token --issuerURL https://kubauth.example.com --clientId public --onlyIdToken

Output: 

eyJhbGciOiJSUzI1NiIsImtpZCI6ImY0Y2NkNDU0LWYzYTgtNDQ3Zi1hN2MzLTY3ZmY5MzUxMzZiMSIsInR5cCI6IkpXVCJ9.eyJhdF9oYXNoIjoiaGNBY2dtdmdBekJlSGgyODlkWHF3USIsImF1ZCI6WyJwdWJsaWMiXSwi...

Pipe to JWT Decoder

kc token --issuerURL https://kubauth.example.com --clientId public --onlyIdToken | kc jwt

Behavior

Browser Flow

  1. Local Server Started - kc starts a local HTTP server on a localhost port
  2. Browser Opens - Your default browser opens to the Kubauth login page
  3. User Authenticates - You log in with your credentials
  4. Callback Received - Kubauth redirects back to the local server with an authorization code
  5. Token Exchange - kc exchanges the code for tokens
  6. Display Results - Tokens are displayed in the terminal

Token Storage

Tokens are displayed but not automatically stored. If you need to save them:

# Save ID token to variable
ID_TOKEN=$(kc token --issuerURL https://kubauth.example.com --clientId public --onlyIdToken)

# Save to file
kc token --issuerURL https://kubauth.example.com --clientId public --onlyIdToken > token.txt

SSO Session

If you previously checked "Remember me" on the login page, subsequent kc token commands will complete automatically without requiring you to log in again (SSO session active).

To clear the SSO session:

kc logout --issuerURL https://kubauth.example.com

Troubleshooting

Browser Doesn't Open

If the browser doesn't open automatically:

  1. Check the terminal output for the URL
  2. Manually copy and paste it into your browser
  3. Or use kc token-nui for terminal-based authentication

Example: 

If browser doesn't open automatically, visit: http://127.0.0.1:9921

TLS Certificate Errors

Error: 

Error: x509: certificate signed by unknown authority

Solutions:

  • Use --insecureSkipVerify for testing (not recommended for production)
  • Use --caFile ./ca.crt. To extract the CA: 
    kubectl -n kubauth get secret kubauth-oidc-server-cert \
  -o=jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
  • Add this CA certificate to system trust store.

Security Considerations

  1. Don't Expose Tokens - Be careful when displaying or logging tokens
  2. Use HTTPS - Always use HTTPS for the issuer URL in production
  3. Verify Certificates - Only use --insecureSkipVerify for testing
  4. Token Lifetime - Tokens expire quickly by design; request new ones as needed
  5. Client Secrets - Never commit client secrets to version control

See Also