Authentication

JWT-based auth with 13 OAuth providers, TOTP/SMS MFA, magic links, RBAC, and session management — production-ready and self-hosted.

Quick Start

# Auth starts automatically with nself start
nself start

# Check auth service status
nself status | grep auth

# Auth service is at:
# Local:  http://auth.local.nself.org (proxied by Nginx)
# Port:   4000 (internal, not exposed)
# Image:  nhost/hasura-auth:0.36.0

# Enable OAuth providers
nself auth provider enable google   --client-id $GOOGLE_CLIENT_ID   --client-secret $GOOGLE_CLIENT_SECRET

nself auth provider enable github   --client-id $GITHUB_CLIENT_ID   --client-secret $GITHUB_CLIENT_SECRET

# Enable MFA
nself auth mfa enable --type totp

# Configure email (required for magic links, password reset)
nself auth email configure   --provider smtp   --host smtp.mailgun.org   --port 587

Architecture Overview

Authentication flow:

  Client
    |
    | POST /auth/signin/email-password
    | POST /auth/signin/provider/{provider}
    | POST /auth/signin/magic-link
    v
  Nginx (auth.{domain})
    |
    v
  nhost/hasura-auth:0.36.0  (port 4000, 127.0.0.1 only)
    |
    +-- Validates credentials
    +-- Issues JWT + refresh token
    +-- Writes session to np_auth_refresh_tokens
    |
    v
  Client stores JWT
    |
    | Authorization: Bearer <jwt>
    v
  Hasura GraphQL API
    |
    +-- Validates JWT signature (HASURA_GRAPHQL_JWT_SECRET)
    +-- Extracts x-hasura-* claims
    +-- Applies RBAC permissions
    +-- Enforces RLS policies
    v
  PostgreSQL

JWT Configuration

# .env.dev (team defaults — replace HASURA_GRAPHQL_JWT_SECRET in .env.secrets)
AUTH_JWT_SECRET=your-256-bit-secret-here
HASURA_GRAPHQL_JWT_SECRET='{"type":"HS256","key":"your-256-bit-secret-here"}'

# JWT token TTL
AUTH_ACCESS_TOKEN_EXPIRES_IN=900        # 15 minutes (default)
AUTH_REFRESH_TOKEN_EXPIRES_IN=43200     # 30 days in minutes

// JWT payload structure
{
  "sub": "uuid-of-user",
  "iat": 1715000000,
  "exp": 1715000900,
  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": ["user", "me"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "uuid-of-user",
    "x-hasura-source-account-id": "primary",
    "x-hasura-tenant-id": "uuid-of-tenant"   // Cloud only
  }
}

Custom JWT Claims

# Inject custom claims via Hasura actions
AUTH_CUSTOM_CLAIMS_WEBHOOK=https://api.nself.org/auth/custom-claims

// Custom claims webhook handler
export async function customClaimsHandler(userId: string) {
  const user = await db.select().from(npUsers)
    .where(eq(npUsers.id, userId))
    .limit(1)

  return {
    'x-hasura-source-account-id': user[0]?.sourceAccountId ?? 'primary',
    'x-hasura-tenant-id': user[0]?.tenantId ?? null,
    'x-hasura-plan': user[0]?.plan ?? 'free',
  }
}

Email and Password

# Enable email/password auth (default: enabled)
AUTH_EMAIL_SIGNIN_EMAIL_VERIFIED_REQUIRED=true   # require email verification
AUTH_PASSWORD_MIN_LENGTH=8
AUTH_GRAVATAR_ENABLED=true

# REST API
# Sign up
POST /auth/signup/email-password
{"email": "user@example.com", "password": "secure123", "options": {"displayName": "Alice"}}

# Sign in
POST /auth/signin/email-password
{"email": "user@example.com", "password": "secure123"}

# Response
{
  "session": {
    "accessToken": "eyJ...",
    "refreshToken": "uuid...",
    "accessTokenExpiresIn": 900,
    "user": { "id": "uuid", "email": "user@example.com" }
  }
}

OAuth Providers

13 providers are supported out of the box.

# OAuth sign-in URL (redirect user to this)
GET /auth/signin/provider/google?redirectTo=https://app.nself.org/dashboard

# After OAuth, user is redirected to:
# https://app.nself.org/dashboard?refreshToken=uuid&...

Magic Links

# Enable (requires email configured)
AUTH_EMAIL_PASSWORDLESS_EMAIL_ENABLED=true

# Request a magic link
POST /auth/signin/passwordless/email
{"email": "user@example.com", "options": {"redirectTo": "https://app.nself.org"}}

# User receives email with link:
# https://auth.nself.org/verify?ticket=otp:uuid...&type=signinPasswordless&redirectTo=...

# Verify the ticket (happens automatically via the link click)
GET /auth/verify?ticket=otp:uuid...&type=signinPasswordless

# Response: redirects to redirectTo with session in fragment/query

Multi-Factor Authentication

TOTP (Authenticator App)

# Enable TOTP globally
AUTH_MFA_TOTP_ENABLED=true

# 1. Generate TOTP secret for user
POST /auth/mfa/totp/generate
Authorization: Bearer <access-token>
# Returns: { "totpSecret": "BASE32...", "qrCodeDataUrl": "data:image/png..." }

# 2. User scans QR code in authenticator app

# 3. Activate TOTP with first code
POST /auth/mfa/totp/activate
Authorization: Bearer <access-token>
{"code": "123456"}

# 4. On future sign-in, after email/password step:
POST /auth/signin/mfa/totp
{"ticket": "mfaTotp:uuid...", "otp": "123456"}

SMS MFA

# Enable SMS MFA (requires Twilio or similar)
AUTH_MFA_SMS_ENABLED=true
AUTH_SMS_PROVIDER=twilio
AUTH_SMS_TWILIO_ACCOUNT_SID=ACxxx
AUTH_SMS_TWILIO_AUTH_TOKEN=xxx
AUTH_SMS_TWILIO_MESSAGING_SERVICE_ID=MGxxx

# Add phone number to account
POST /auth/user/phone
Authorization: Bearer <access-token>
{"phoneNumber": "+15551234567"}

# Verify phone
POST /auth/user/phone/verify
{"code": "123456"}

# On sign-in with MFA:
POST /auth/signin/mfa/sms
{"ticket": "mfaSms:uuid...", "otp": "123456"}

RBAC — Roles and Permissions

# Default roles (built in)
# user    — authenticated user (default)
# me      — alias for current user (for self-service queries)
# admin   — elevated access
# anonymous — unauthenticated

# Custom roles
AUTH_DEFAULT_ROLE=user
AUTH_ALLOWED_ROLES=user,admin,moderator,premium

# Assign role to user
nself auth user role add user@example.com --role admin

# Remove role
nself auth user role remove user@example.com --role admin

# List user roles
nself auth user role list user@example.com

Role-Based Hasura Permissions

// Hasura table permission — different rows per role

// 'user' role: can only see own documents
// SELECT permission:
{
  "user_id": {
    "_eq": "X-Hasura-User-Id"
  }
}

// 'admin' role: can see all documents in their source_account
{
  "source_account_id": {
    "_eq": "X-Hasura-Source-Account-Id"
  }
}

// 'me' role: user profile self-service
{
  "id": {
    "_eq": "X-Hasura-User-Id"
  }
}

Session Management

# Refresh access token (before it expires)
POST /auth/token
{"refreshToken": "uuid..."}
# Returns new accessToken + refreshToken

# Sign out (revoke refresh token)
POST /auth/signout
Authorization: Bearer <access-token>
{"refreshToken": "uuid..."}

# Sign out all sessions (revoke all refresh tokens)
POST /auth/signout
Authorization: Bearer <access-token>
{"all": true}

-- Session storage in PostgreSQL
-- np_auth_refresh_tokens table (managed by hasura-auth)
SELECT id, user_id, expires_at, created_at
FROM auth.refresh_tokens
WHERE user_id = $1
ORDER BY created_at DESC;

-- Revoke all sessions for a user
DELETE FROM auth.refresh_tokens WHERE user_id = $1;

User Management

# List users
nself auth user list
nself auth user list --role admin

# Get user details
nself auth user get user@example.com

# Disable user (blocks sign-in without deleting)
nself auth user disable user@example.com

# Enable user
nself auth user enable user@example.com

# Delete user (soft delete)
nself auth user delete user@example.com

# Force password reset (sends email)
nself auth user password-reset user@example.com

Email Templates

# Template locations
AUTH_EMAIL_TEMPLATES_DIR=./email-templates

# Template files:
# email-templates/verify-email.html
# email-templates/reset-password.html
# email-templates/magic-link.html
# email-templates/invite.html

# Override sender
AUTH_EMAIL_FROM=noreply@nself.org
AUTH_EMAIL_FROM_NAME="nSelf Team"

Security Configuration

Best Practices

• Rotate AUTH_JWT_SECRET on a schedule — old tokens become invalid immediately. Coordinate with a deployment.
• Set AUTH_ALLOWED_REDIRECT_URLS explicitly — open redirectors allow phishing attacks using your domain.
• Enable HIBP password check in production — blocks users from setting known-breached passwords.
• Use short access token TTL (15 min) — long-lived tokens are a risk if stolen. Refresh tokens handle the UX.
• Require email verification — prevents typo-registrations and bots.
• Enable MFA for admin accounts — set AUTH_MFA_TOTP_ENABLED=true and require TOTP for the admin role.
• Never expose the auth port (4000) directly — all traffic goes through Nginx. The port is bound to 127.0.0.1.

Related

• Hasura — JWT claims, RBAC permissions, row filters
• Multi-Tenancy — Injecting tenant context via JWT claims
• Architecture — How auth fits into the nSelf service mesh