jlcox1970/magiclink-auth repository overview

# docker-compose.yml
services:

  magic-auth:
    image: jlcox1970/magic-auth:latest
    ports:
      - "8080:8080"
    environment:
      # ── Required ──────────────────────────────────────────────────────────
      ISSUER: "http://localhost:8080"
      JWT_SECRET: "change-me-32-chars-minimum!!"
      FINGERPRINT_SECRET: "change-me-32-chars-too!!"

      # ── Signing key (generate below) ──────────────────────────────────────
      JWK_PRIVATE_KEY: |
        -----BEGIN RSA PRIVATE KEY-----
        <paste your key here>
        -----END RSA PRIVATE KEY-----

      # ── Database ──────────────────────────────────────────────────────────
      DB_DRIVER: "rqlite"
      RQLITE_URL: "http://rqlite:4001"

      # ── Email via NATS ────────────────────────────────────────────────────
      NATS_URL: "nats://nats:4222"
      FROM_ADDRESS: "[email protected]"
      BASE_URL: "http://localhost:8080"

      # ── Optional ──────────────────────────────────────────────────────────
      LOG_LEVEL: "info"
      PORT: "8080"
      SECURE_COOKIES: "true"          # set false for local HTTP dev
      # LOGIN_UI_URL: ""              # leave empty to use the built-in login UI
      # CORS_ORIGINS: "http://localhost:3000"
      # ALLOWED_REDIRECT_DOMAINS: "app.example.com"
    depends_on:
      - rqlite
      - nats

  rqlite:
    image: rqlite/rqlite:8
    ports:
      - "4001:4001"
    volumes:
      - rqlite-data:/rqlite/file
    command: ["-node-id", "1", "-http-addr", "0.0.0.0:4001", "-raft-addr", "0.0.0.0:4002"]

  nats:
    image: nats:2-alpine
    ports:
      - "4222:4222"
    command: ["-js"]

volumes:
  rqlite-data:

# RSA (RS256) — recommended
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 \
  | openssl pkey -traditional > private.pem

export JWK_PRIVATE_KEY="$(cat private.pem)"

# EC (ES256) — smaller tokens, faster verification
openssl ecparam -name prime256v1 -genkey -noout \
  | openssl pkey > ec-private.pem

export JWK_EC_PRIVATE_KEY="$(cat ec-private.pem)"

# Confidential client (server-side app)
curl -X POST http://localhost:8080/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name":   "my-app",
    "redirect_uris": ["https://my-app.example.com/auth/callback"]
  }'

# Public client (SPA / mobile — uses PKCE, no secret)
curl -X POST http://localhost:8080/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name":                "my-spa",
    "redirect_uris":              ["https://my-spa.example.com/callback"],
    "token_endpoint_auth_method": "none"
  }'

{
  "sub":                "f2af861cfa40707e1b89ea2713b1d481",
  "email":              "[email protected]",
  "name":               "user",
  "preferred_username": "user",
  "picture":            "https://www.gravatar.com/avatar/<md5>?d=identicon&s=200",
  "roles":              ["user"],
  "iss":                "https://oidc.example.com",
  "aud":                ["your-client-id"],
  "exp":                1744000000,
  "iat":                1743996400
}

# 1. Request a magic link — email is sent via NATS
curl -X POST http://localhost:8080/api/auth/request \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

# 2. User clicks the link in their email
#    magic-auth sets session cookies and returns the authenticated user

# 3. Check the current session
curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer <access_token>"

# 4. Logout
curl -X POST http://localhost:8080/api/auth/logout

environment:
  RBAC_RULES: '[{"client_id":"*","principal":"[email protected]","principal_type":"email","roles":["global_admin"]}]'

RBAC_RULES: '[{"client_id":"*","principal":"example.com","principal_type":"domain","roles":["global_admin"]}]'

# Assign global_admin by email across all clients
curl -X POST http://localhost:8080/oauth/rbac/rules \
  -H "Authorization: Bearer <global_admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":      "*",
    "principal":      "[email protected]",
    "principal_type": "email",
    "roles":          ["global_admin"]
  }'

# Assign app_admin to everyone at a domain for a specific client
curl -X POST http://localhost:8080/oauth/rbac/rules \
  -H "Authorization: Bearer <global_admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":      "<client_id>",
    "principal":      "example.com",
    "principal_type": "domain",
    "roles":          ["app_admin"]
  }'

# Step 1 — Enable SSO globally (global_admin)
curl -X PUT http://localhost:8080/api/admin/config \
  -H "Authorization: Bearer <global_admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"sso_session_enabled": "true", "sso_session_ttl_hours": "168"}'

# Step 2 — Opt a client in (app_admin or global_admin)
curl -X PUT http://localhost:8080/api/admin/clients/<client_id>/sso \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Check SSO status for a client
curl http://localhost:8080/api/admin/clients/<client_id>/sso \
  -H "Authorization: Bearer <token>"
# {"client_id":"...","enabled":true,"global_sso_enabled":true,...}

curl -X PUT http://localhost:8080/api/admin/config \
  -H "Authorization: Bearer <global_admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sso_session_enabled":          "true",
    "sso_session_ttl_hours":        "720",
    "registration_open":            "true",
    "registration_allowed_domains": "app.example.com"
  }'

{
  "to":      ["[email protected]"],
  "subject": "Your sign-in link",
  "body":    "Click the link below to sign in:\n\nhttps://oidc.example.com/api/auth/verify?id=...&token=...",
  "is_html": false,
  "headers": {
    "From":     "[email protected]",
    "X-Mailer": "magiclink-auth"
  }
}

import { connect, StringCodec } from "nats";

const nc = await connect({ servers: "nats://localhost:4222" });
const js = nc.jetstream();
const sc = StringCodec();

const consumer = await js.consumers.get("EMAILS", "email-sender");
for await (const msg of await consumer.consume()) {
  const payload = JSON.parse(sc.decode(msg.data));
  await sendEmail({
    to:      payload.to,
    subject: payload.subject,
    text:    payload.body,
    from:    payload.headers["From"],
  });
  msg.ack();
}

nc, _ := nats.Connect("nats://localhost:4222")
js, _ := nc.JetStream()

js.Subscribe("emails.send", func(msg *nats.Msg) {
    var m struct {
        To      []string          `json:"to"`
        Subject string            `json:"subject"`
        Body    string            `json:"body"`
        Headers map[string]string `json:"headers"`
    }
    json.Unmarshal(msg.Data, &m)
    // deliver email using m.To, m.Subject, m.Body, m.Headers["From"]
    msg.Ack()
}, nats.Durable("email-sender"), nats.ManualAck())

curl http://localhost:8080/api/health
# {"status":"ok"}