Authentication

Loom supports multiple authentication methods to provide secure, flexible access across different use cases: web-based OAuth flows, passwordless magic links, and device code flow for CLI and headless environments.

Authentication Methods

OAuth 2.0

Industry-standard OAuth flows for Google and GitHub

Magic Links

Passwordless email-based authentication

Device Code Flow

CLI and VS Code authentication via browser

Okta SSO

Enterprise SAML/OIDC authentication

OAuth 2.0 Providers

Loom implements OAuth 2.0 / OpenID Connect flows for third-party authentication providers.

Google OAuth

Configure OAuth App

Set up a Google OAuth 2.0 application in the Google Cloud Console:

LOOM_SERVER_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
LOOM_SERVER_GOOGLE_CLIENT_SECRET=GOCSPX-...
LOOM_SERVER_GOOGLE_REDIRECT_URI=https://your-domain.com/auth/google/callback

OAuth Flow

The Google OAuth flow uses OpenID Connect with the following scopes:

openid - Required for OIDC
email - Access to user’s email address
profile - Access to user’s display name and avatar

Security features:

State parameter for CSRF protection (random, unguessable)
Nonce parameter for replay protection (validated in ID token)
ID token signature verification using Google’s public keys

User Claims

After successful authentication, Loom extracts user identity from the ID token:

// loom-server-auth-google/src/lib.rs:607
pub fn decode_id_token(&self, id_token: &str) -> Result<GoogleIdTokenClaims, OAuthError> {
    let parts: Vec<&str> = id_token.split('.').collect();
    if parts.len() != 3 {
        return Err(OAuthError::InvalidIdToken("ID token must have 3 parts".to_string()));
    }
    
    let payload = parts[1];
    let decoded = URL_SAFE_NO_PAD.decode(payload)
        .map_err(|e| OAuthError::InvalidIdToken(format!("failed to decode payload: {e}")))?
    
    let claims: GoogleIdTokenClaims = serde_json::from_slice(&decoded)
        .map_err(|e| OAuthError::InvalidIdToken(format!("failed to parse claims: {e}")))?
    
    Ok(claims)
}

Available claims:

sub - Google’s unique user ID (stable identifier)
email - User’s email address
email_verified - Whether email is verified by Google
name - User’s display name
picture - Avatar image URL

The ID token approach is preferred over the /userinfo endpoint because it avoids an extra API call and provides cryptographically verifiable claims.

GitHub OAuth

GitHub OAuth provides seamless authentication for developers already using GitHub.

# Configuration
LOOM_SERVER_GITHUB_CLIENT_ID=Iv1.abc123def456
LOOM_SERVER_GITHUB_CLIENT_SECRET=abc123...
LOOM_SERVER_GITHUB_REDIRECT_URI=https://your-domain.com/auth/github/callback

Requested scopes:

user:email - Read user’s email addresses (including private)
read:user - Read user profile information

Authentication flow:

Authorization URL Generation

// loom-server-auth-github/src/lib.rs:355
pub fn authorization_url(&self, state: &str) -> String {
    let mut url = Url::parse(GITHUB_AUTHORIZE_URL).expect("invalid authorize URL");
    
    url.query_pairs_mut()
        .append_pair("client_id", &self.config.client_id)
        .append_pair("redirect_uri", &self.config.redirect_uri)
        .append_pair("scope", &self.config.scopes_string())
        .append_pair("state", state);
    
    url.to_string()
}

Code Exchange

Exchange the authorization code for an access token:

// loom-server-auth-github/src/lib.rs:388
pub async fn exchange_code(&self, code: &str) -> Result<GitHubTokenResponse, OAuthError> {
    let response = self.http_client
        .post(GITHUB_TOKEN_URL)
        .header("Accept", "application/json")
        .form(&[
            ("client_id", self.config.client_id.as_str()),
            ("client_secret", self.config.client_secret.expose().as_str()),
            ("code", code),
            ("redirect_uri", self.config.redirect_uri.as_str()),
        ])
        .send()
        .await?
    
    // Parse token response...
}

Fetch User Data

Retrieve user profile and verified emails:

// Get user profile
let user = client.get_user(token.access_token.expose()).await?;

// Get all email addresses (including private)
let emails = client.get_emails(token.access_token.expose()).await?;

// Find primary verified email
let primary_email = emails.iter()
    .find(|e| e.primary && e.verified)
    .map(|e| e.email.clone());

Always use verified emails (email_verified: true for GitHub emails) for security. Unverified emails can be set by anyone and should not be trusted for authentication.

Magic Links

Magic links provide passwordless authentication via email. Users receive a unique, time-limited link that logs them in when clicked.

Security Properties

Single-Use

Each link can only be used once. After verification, the link is marked as used and cannot be reused.

Short-Lived

Links expire after 10 minutes to minimize the window for token interception.

Cryptographically Secure

Tokens are generated using 32 bytes of cryptographically secure random data (256 bits of entropy).

Argon2id Hashing

Tokens are hashed with Argon2id before storage, protecting against database leaks.

Flow Overview

Implementation Details

// loom-server-auth-magiclink/src/lib.rs:156
pub fn new(email: impl AsRef<str> + Into<String>) -> (Self, String) {
    let (token, hash) = generate_magic_link_token();
    let now = Utc::now();
    let id = Uuid::new_v4();
    
    let link = Self {
        id,
        email: email.into(),
        token_hash: hash,  // Argon2id hash, safe to store
        created_at: now,
        expires_at: now + Duration::minutes(MAGIC_LINK_EXPIRY_MINUTES),  // 10 minutes
        used_at: None,
    };
    
    (link, token)  // Return hash for storage, token for email
}

Token generation:

// loom-server-auth-magiclink/src/lib.rs:241
pub fn generate_magic_link_token() -> (String, String) {
    use rand::Rng;
    
    let mut rng = rand::thread_rng();
    let bytes: [u8; MAGIC_LINK_TOKEN_BYTES] = rng.gen();  // 32 bytes = 256 bits
    let token = hex::encode(bytes);  // 64 hex characters
    let hash = hash_magic_link_token(&token);  // Argon2id hash
    (token, hash)
}

Why Argon2id over SHA-256?

Argon2id provides stronger protection

While 32-byte tokens have 256 bits of entropy (making brute-force infeasible), Argon2id provides defense-in-depth:

Brute-force resistance - Memory-hard design makes GPU/ASIC attacks significantly more expensive
Future-proof - Additional protection if token generation is ever weakened
Industry best practice - OWASP recommends Argon2id for password and token hashing
Salt included - Each hash includes a unique salt, preventing rainbow table attacks

The trade-off is slightly higher CPU cost per verification (~50-100ms), which is acceptable for the low-frequency magic link flow.

Token verification:

// loom-server-auth-magiclink/src/lib.rs:225
pub fn verify(&self, token: &str) -> bool {
    let result = verify_magic_link_token(token, &self.token_hash);
    tracing::debug!(verified = result, "token verification complete");
    result
}

// loom-server-auth-magiclink/src/lib.rs:282
pub fn verify_magic_link_token(token: &str, hash: &str) -> bool {
    let parsed_hash = match PasswordHash::new(hash) {
        Ok(h) => h,
        Err(_) => return false,
    };
    argon2_instance()
        .verify_password(token.as_bytes(), &parsed_hash)
        .is_ok()
}

When a new magic link is requested, any previous links for that email are invalidated. This prevents accumulation of valid tokens and reduces the attack surface.

Device Code Flow

Device code flow enables authentication on headless or input-constrained devices (CLIs, VS Code) by offloading the authentication to a browser.

Flow Diagram

┌─────────┐                              ┌─────────┐                    ┌─────────┐
│   CLI   │                              │ Server  │                    │ Browser │
└────┬────┘                              └────┬────┘                    └────┬────┘
     │  POST /auth/device/start               │                              │
     │───────────────────────────────────────>│                              │
     │                                        │                              │
     │  {device_code, user_code, expires_at}  │                              │
     │<───────────────────────────────────────│                              │
     │                                        │                              │
     │  Display: "Enter 123-456-789 at URL"   │                              │
     │─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>│
     │                                        │                              │
     │                                        │   User visits /device        │
     │                                        │<─────────────────────────────│
     │                                        │                              │
     │                                        │   User enters code & logs in │
     │                                        │<─────────────────────────────│
     │                                        │                              │
     │  POST /auth/device/poll               │                              │
     │───────────────────────────────────────>│                              │
     │                                        │                              │
     │  {status: "completed", token: "..."}   │                              │
     │<───────────────────────────────────────│                              │

Two Codes: Why?

The flow uses two distinct codes for security and usability:

device_code (UUID)

Purpose: Internal identifier used by the CLI for polling.

Cryptographically random UUID (128 bits of entropy)
Hard to guess, making brute-force polling infeasible
Never displayed to users
Only travels in CLI ↔ Server communication

// loom-server-auth-devicecode/src/lib.rs:348
pub fn generate_device_code() -> String {
    Uuid::new_v4().to_string()
}

user_code (123-456-789)

Purpose: Human-readable code displayed to the user.

Format: 9 digits grouped by dashes (XXX-XXX-XXX)
Easy to read aloud and type on any keyboard
10^9 possibilities = ~30 bits of entropy
Users enter this in the browser to link authentication

// loom-server-auth-devicecode/src/lib.rs:334
pub fn generate_user_code() -> String {
    let mut rng = rand::thread_rng();
    format!(
        "{:03}-{:03}-{:03}",
        rng.gen_range(0..1000),
        rng.gen_range(0..1000),
        rng.gen_range(0..1000)
    )
}

Security benefit: Even if an attacker observes the user_code (e.g., shoulder surfing), they cannot poll for the result without the device_code.

Security Properties

Time-Limited

Device codes expire after 10 minutes to limit the attack window:

// loom-server-auth-devicecode/src/lib.rs:77
pub const DEVICE_CODE_EXPIRY_MINUTES: i64 = 10;

// loom-server-auth-devicecode/src/lib.rs:236
expires_at: now + Duration::minutes(DEVICE_CODE_EXPIRY_MINUTES)

Rate-Limited Polling

Polling is rate-limited to 1 request per second to prevent abuse:

// loom-server-auth-devicecode/src/lib.rs:83
pub const POLL_INTERVAL_SECONDS: u64 = 1;

The server may return slow_down if the client polls too frequently.

Single-Use Codes

User codes are single-use and bound to a specific device code. Once a user completes authentication:

// loom-server-auth-devicecode/src/lib.rs:305
pub fn complete(&mut self, user_id: UserId) {
    self.user_id = Some(user_id);
    self.completed_at = Some(Utc::now());
}

CSRF-Immune

The flow is immune to CSRF attacks because it doesn’t rely on browser cookies. The CLI holds the device_code secret, and the browser only knows the user_code.

State Machine

// loom-server-auth-devicecode/src/lib.rs:148
pub enum DeviceCodeStatus {
    /// Waiting for user to complete authentication in browser.
    Pending,
    /// User has completed authentication.
    Completed { user_id: UserId },
    /// The device code has expired without completion.
    Expired,
}

State transitions:

A code starts as Pending
It transitions to either Completed (user authenticated) or Expired (timeout)
Once in a terminal state, the status never changes

// loom-server-auth-devicecode/src/lib.rs:267
pub fn status(&self) -> DeviceCodeStatus {
    let status = if let Some(user_id) = self.user_id {
        if self.completed_at.is_some() {
            DeviceCodeStatus::Completed { user_id }
        } else if self.is_expired() {
            DeviceCodeStatus::Expired
        } else {
            DeviceCodeStatus::Pending
        }
    } else if self.is_expired() {
        DeviceCodeStatus::Expired
    } else {
        DeviceCodeStatus::Pending
    };
    
    status
}

Enterprise SSO (Okta)

For enterprise deployments, Loom supports Okta SAML/OIDC authentication.

LOOM_SERVER_OKTA_CLIENT_ID=0oa...
LOOM_SERVER_OKTA_CLIENT_SECRET=...
LOOM_SERVER_OKTA_REDIRECT_URI=https://your-domain.com/auth/okta/callback
LOOM_SERVER_OKTA_DOMAIN=your-org.okta.com

The Okta integration uses the same OAuth 2.0 patterns as Google and GitHub, with Okta-specific discovery endpoints and token validation.

Security Best Practices

Secret Protection

All secrets (API keys, client secrets, tokens) are wrapped in SecretString types that auto-redact in logs, Debug output, and serialization.

State Validation

Always validate the state parameter in OAuth callbacks to prevent CSRF attacks. Use cryptographically random values.

Nonce Validation

For OIDC flows, validate the nonce claim in ID tokens to prevent replay attacks.

Email Verification

Only trust verified email addresses from OAuth providers. Unverified emails can be set by anyone.

API Reference

Device Code Flow Endpoints

// Start device code flow
POST /auth/device/start
Response: {
  device_code: string,      // UUID for polling
  user_code: string,        // XXX-XXX-XXX format
  verification_uri: string, // URL to visit
  expires_at: string,       // ISO 8601 timestamp
  interval: number          // Polling interval in seconds
}

// Poll for completion
POST /auth/device/poll
Body: { device_code: string }
Response: {
  status: "pending" | "completed" | "expired",
  token?: string  // Only present when status = "completed"
}

Magic Link Flow

// Request magic link
POST /auth/magic-link/request
Body: { email: string }
Response: { success: true }

// Verify magic link token
GET /auth/magic-link/verify?token={token}
Response: {
  success: true,
  session_token: string
}

See loom-server/src/routes/auth/ for complete route implementations.

Get Started

Core Features

Architecture

Integrations

Observability

Deployment

Authentication

Authentication Methods

OAuth 2.0

Magic Links

Device Code Flow

Okta SSO

OAuth 2.0 Providers

Google OAuth

GitHub OAuth

Magic Links

Security Properties

Single-Use

Short-Lived

Cryptographically Secure

Argon2id Hashing

Flow Overview

Implementation Details

Device Code Flow

Flow Diagram

Two Codes: Why?

Security Properties

State Machine

Enterprise SSO (Okta)

Security Best Practices

Secret Protection

State Validation

Nonce Validation

Email Verification

API Reference

Device Code Flow Endpoints

Magic Link Flow

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Integrations

Observability

Deployment

​Authentication Methods

OAuth 2.0

Magic Links

Device Code Flow

Okta SSO

​OAuth 2.0 Providers

​Google OAuth

​GitHub OAuth

​Magic Links

​Security Properties

Single-Use

Short-Lived

Cryptographically Secure

Argon2id Hashing

​Flow Overview

​Implementation Details

​Device Code Flow

​Flow Diagram

​Two Codes: Why?

​Security Properties

​State Machine

​Enterprise SSO (Okta)

​Security Best Practices

Secret Protection

State Validation

Nonce Validation

Email Verification

​API Reference

​Device Code Flow Endpoints

​Magic Link Flow

Build docs developers (and LLMs) love

Authentication Methods

OAuth 2.0 Providers

Google OAuth

GitHub OAuth

Magic Links

Security Properties

Flow Overview

Implementation Details

Device Code Flow

Flow Diagram

Two Codes: Why?

Security Properties

State Machine

Enterprise SSO (Okta)

Security Best Practices

API Reference

Device Code Flow Endpoints

Magic Link Flow