Skip to content

HPC with User Context

This pattern allows users to submit jobs to an HPC cluster (e.g., Slurm, PBS) while maintaining their individual user identity for QLAM API calls.

Overview

In multi-user HPC environments, you often want API calls attributed to individual users rather than a shared service account. This enables:

  • Per-user audit trails
  • Individual usage tracking and quotas
  • User-specific permissions and access control

Authentication Options

Use the Device Code Flow for one-time authentication on the login node.

Workflow:

  1. User authenticates on login node - User runs Device Code flow from the cluster login node (no browser needed on the node itself)
  2. User completes auth on separate device - User visits the URL on their phone/laptop and enters the code
  3. Tokens stored in shared location - Credentials are saved to ~/.qsh/credentials/
  4. Job submitted - User submits their batch job to the cluster scheduler
  5. Token refresh on execution - When the job runs, it uses the refresh token to obtain a fresh access token

One-Time Login with Shared Filesystem

If your HPC cluster has a shared filesystem across nodes (common for home directories), this becomes a one-time login. After authenticating once on the login node, the QLAM Core configuration and credentials in ~/.qsh/ are available to all compute nodes. Combined with automatic token refresh, users only need to re-authenticate when the refresh token expires (typically 15 days).

Example with QLAM Shell:

# On login node (one-time)
qsh auth login  # Opens device code flow

# In your batch script
#!/bin/bash
#SBATCH --job-name=quantum-task

# QLAM Core automatically refreshes tokens
python my_quantum_script.py

Example with QLAM Core:

from qlam_core.common import AppContext
from qlam_core.sdk import refresh_credentials
from qlam_core.plugins.tasks import TasksClient

# Refresh credentials before API calls (handles token expiration)
ctx = AppContext()
refresh_credentials(ctx)

with TasksClient(ctx) as client:
    # API calls are attributed to the authenticated user
    task = client.create(body=task_payload)

Option 2: Authorization Code Flow

Use the Authorization Code Flow if users have browser access on their workstation before submitting jobs.

Workflow:

  1. User authenticates on workstation - User runs Authorization Code flow from their local machine (with browser access)
  2. Tokens synced to cluster - User copies access and refresh tokens or syncs ~/.qsh/ directory to the cluster
  3. Job submitted - User submits their batch job
  4. Token refresh on execution - When the job runs, it uses the refresh token

This approach works well when users prepare jobs on their local machine before submission.

Benefits

  • API calls are attributed to the individual user, not a shared service account
  • Users don't need browser access on cluster nodes
  • Long queue times are handled gracefully via token refresh
  • Maintains audit trail per user
  • One-time login with shared filesystem configurations

Considerations

  • Refresh tokens expire (typically 15 days) - users may need to re-authenticate periodically
  • Requires either shared filesystem or token sync mechanism
  • Each user manages their own credentials

Next Steps