Document default JWT token storage location and logout procedure in `using_the_client.md`

[mgajek-cern]

Description

After successful OIDC authentication via rucio whoami, users may want to:

1. Locate their JWT token for debugging or external use
2. Log out / invalidate their session
3. Re-authenticate with different credentials

Currently, this information is not documented in the official Rucio client documentation.

Proposed Documentation Addition

Location: docs/user/using_the_client.md (after the OIDC authentication section)

JWT Token Storage

After successful OIDC authentication, Rucio stores the JWT token locally:

# Default location
/tmp/root/.rucio_<account>/auth_token_for_account_<account>

# Example for 'root' account
cat /tmp/root/.rucio_root/auth_token_for_account_root

Token Format: The file contains a base64-encoded JWT with three parts separated by dots:

<header>.<payload>.<signature>

Decode Token (for debugging):

# View token payload
TOKEN=$(cat /tmp/root/.rucio_root/auth_token_for_account_root)
echo $TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

# Shows: exp (expiration), iat (issued at), sub (subject), iss (issuer), scope, etc.

Logout / Session Management

Logout (delete cached token):

# Remove all cached tokens
rm -rf /tmp/root/.rucio_*/

# Remove specific account token
rm -rf /tmp/root/.rucio_<account>/

# Verify logout
rucio whoami
# Will prompt for re-authentication

Switch Accounts:

# Logout from current account
rm -rf /tmp/root/.rucio_root/

# Authenticate with different account
export RUCIO_ACCOUNT=user
rucio whoami

Custom Token Location:

You can specify a custom token storage location in rucio.cfg:

[client]
auth_token_file_path = /path/to/custom/token/file

Security Note: Token files contain sensitive credentials. Ensure proper file permissions:

chmod 600 /tmp/root/.rucio_root/auth_token_for_account_root

Additional Context

• Token lifetime is controlled by the Identity Provider (typically 1-24 hours)
• Expired tokens are automatically refreshed if auth_oidc_refresh_active = true in config
• Tokens are account-specific (one token per Rucio account)

Files to Update

1. docs/user/using_the_client.md - Add new section after OIDC examples

[mgajek-cern]

Optionally, dedicated rucio login and rucio logout commands could be introduced to improve the user experience. We could phase out authentication side-effect of rucio whoami in future major version.

Ref: rucio/rucio#8315

[jainoshika]

Hi @mgajek-cern , I’d like to work on adding this documentation to docs/user/using_the_client.md. Please let me know if that’s okay.