Tyler Gillispie a85223f149 docs: generalize ONBOARDING.md into a universal, technology-agnostic integration guide

2026-08-23 19:04:57 -07:00

13 KiB

Raw Permalink Blame History

Auth-Yes — Application Integration & Architecture Guide

Auth-Yes is a standalone, zero-trust Identity and Access Management (IAM) fabric and WebAuthn Passkey authority. It provides microsecond session validation, cryptographic workload identity, and decoupled application-level Role-Based Access Control (RBAC).

This guide provides a universal, technology-agnostic architectural reference for developers and system administrators integrating services into the Auth-Yes ecosystem.

1. System Architecture & Defense-in-Depth Model

Auth-Yes implements a three-tier defense model, allowing applications to choose the integration depth that best fits their architecture:

                [ Public Internet / User Browser ]
                                │
                  1. WebAuthn Passkey Login
                  2. Wildcard Cookie: *.yourdomain.org
                                │
                                ▼
            ═════════════════════════════════════════
            Ingress Reverse Proxy (Traefik, Nginx, etc.)
            ═════════════════════════════════════════
                                │
           ┌────────────────────┴────────────────────┐
           ▼                                         ▼
[ Tier 1 & 2: Edge ForwardAuth ]          [ Tier 3: Native Zero-Trust ]
(Off-the-shelf UIs / 3rd-Party)              (Microservices & APIs)
           │                                         │
           │ GET /api/forward-auth                   │ 1. Extract session token
           │ (Valkey Cache Lookup)                   │ 2. Query Workload API Socket
           │                                         ▼
           │                        ┌─────────────────────────────────┐
           │                        │ SPIRE Agent (Workload API)      │
           │                        │ - Issues X.509 SVID             │
           │                        │ - spiffe://<trust-domain>/<app> │
           │                        └────────────────┬────────────────┘
           │                                         │
           │                                         │ ConnectRPC over HTTP/2
           ▼                                         ▼
═════════════════════════════════════════════════════════════════════
Auth-Yes Central Gateway (auth-api:8000)
- Microsecond Session Validation (Valkey L1/L2 with RESP3 Tracking)
- Cryptographic Workload SVID Attestation (spire_ffi)
- Default-Deny PostgreSQL Application RBAC Grants (grants table)
═════════════════════════════════════════════════════════════════════

The Three Integration Tiers:

Tier	Target Use Case	Integration Mechanism	Protocol / Transport	Code Required
Tier 1: Global Edge	Pre-release & unmapped internal services	Universal proxy perimeter fallback	HTTP 302 Redirect to `/login`	None
Tier 2: Edge ForwardAuth	Off-the-shelf apps, admin dashboards, legacy web UIs	Reverse proxy ForwardAuth route	HTTP `GET /api/forward-auth`	None
Tier 3: Zero-Trust RPC	Native microservices, custom APIs, streaming backends	Application SDK or direct ConnectRPC client	ConnectRPC / gRPC over HTTP/2 + SPIFFE mTLS	Minimal (Middleware / RPC)

2. Core Identity & Authorization Primitives

2.1. User Session Identifiers

Browser Clients: Auth-Yes issues an HTTP-only, secure session cookie (session_id) scoped to the parent domain (e.g., .yourdomain.org). Browsers automatically transmit this cookie across all subdomains.
API / Programmatic Clients: Applications accept standard Bearer authorization headers: Authorization: Bearer <session_token>.

2.2. Workload Identity (SPIFFE / SPIRE)

Microservices obtain cryptographic identities (X.509 SVIDs) by connecting to the local SPIRE Workload API UNIX domain socket at /var/run/spire/agent.sock.
SVIDs follow the standard SPIFFE ID URI format: spiffe://<trust-domain>/<workload-name> (e.g., spiffe://system.local/payment-service).
When an application calls Auth-Yes, Auth-Yes extracts and attests the caller's SPIFFE ID to verify application authenticity.

2.3. Decoupled Default-Deny RBAC

Auth-Yes decouples Authentication (who the user is) from Authorization (what application they are permitted to access):

Default-Deny: A valid user session has zero application permissions by default.
Grant Evaluation: When a service validates a session, Auth-Yes evaluates the internal grant matrix:
```
SELECT role FROM grants WHERE user_id = $1 AND app_id = $2;
```
Scope Payloads: If a grant exists, Auth-Yes returns { valid: true, uuid: "...", scopes: ["<role>"] }. If no grant exists, it returns { valid: false, error: "Validation failed" } resulting in an immediate 403 Forbidden.

3. Integration Patterns

Pattern A: Edge ForwardAuth (Zero-Code / Reverse Proxy)

For off-the-shelf web applications (e.g., Grafana, Portainer, PgAdmin), configure your ingress reverse proxy to query Auth-Yes before routing traffic to the upstream container.

Traefik Example:

# In Traefik dynamic configuration or container labels:
labels:
  - "traefik.http.routers.myapp.middlewares=auth-forward@docker"
  - "traefik.http.middlewares.auth-forward.forwardauth.address=http://auth-api:8000/api/forward-auth"
  - "traefik.http.middlewares.auth-forward.forwardauth.trustForwardHeader=true"
  - "traefik.http.middlewares.auth-forward.forwardauth.authResponseHeaders=X-Forwarded-User,X-Forwarded-User-Id"

Behavior:
- If valid: Auth-Yes returns HTTP 200 OK and injects upstream identity headers (X-Forwarded-User: <username>, X-Forwarded-User-Id: <uuid>).
- If missing / invalid: Auth-Yes returns HTTP 401 Unauthorized or redirects unauthenticated browsers to /login.

Pattern B: Native ConnectRPC / gRPC (Language-Agnostic)

For services written in Go, Rust, Python, Java, or C#, applications can communicate directly with the Auth-Yes ConnectRPC endpoint over internal HTTP/2 multiplexing.

Protobuf Contract (`auth.proto`):

syntax = "proto3";
package auth.v1;

service AuthService {
  rpc ValidateSession (ValidateSessionRequest) returns (ValidateSessionResponse);
}

message ValidateSessionRequest {
  string token = 1;
}

message ValidateSessionResponse {
  bool valid = 1;
  string uuid = 2;
  repeated string scopes = 3;
  string error = 4;
}

Endpoint: http://auth-api:8000/auth.v1.AuthService/ValidateSession (or internal mesh DNS).
Workload Identity: Pass client TLS certificates fetched from the SPIRE Workload API socket to enable mTLS attestation.

Pattern C: TypeScript & Deno Applications (`@auth-yes/sdk`)

For TypeScript/JavaScript runtimes, @auth-yes/sdk provides a zero-dependency client with built-in RESP3 client-side cache tracking (L1 memory cache invalidated in real time via Valkey broadcast events).

1. Import Reference:

{
  "imports": {
    "@auth-yes/sdk": "https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts",
    "@auth-yes/sdk/hono": "https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/hono.ts"
  }
}

2. Service Integration:

import { createAuthSdk } from "@auth-yes/sdk";

// Initialize SDK with internal mesh endpoints
const authSdk = createAuthSdk({
  authApiUrl: Deno.env.get("AUTH_API_URL") || "http://auth-api:8000",
  valkeyUrl: Deno.env.get("VALKEY_URL"), // Optional: Enables real-time L1 cache tracking
});

// Validate any session token (cookie or header)
const result = await authSdk.validateSession(sessionToken);

if (result.valid) {
  console.log(`User Authenticated: ${result.uuid}, Roles:`, result.scopes);
} else {
  console.warn(`Access Denied: ${result.error}`);
}

4. Container & Infrastructure Topology

To connect any application container to Auth-Yes and SPIRE, ensure two infrastructure prerequisites:

Network Mesh: Attach the container to the internal bridge network (auth-internal-net) and ingress proxy network (traefik-net).
Workload Socket: Mount the pre-existing named volume spire-socket as read-only (:ro).

Generic Compose Template:

version: "3.8"

services:
  my-service:
    image: ${REG}/library/my-service:latest
    container_name: my-service
    environment:
      - AUTH_API_URL=http://auth-api:8000
      - VALKEY_URL=redis://auth-valkey:6379
      - SPIFFE_ENDPOINT_SOCKET=/var/run/spire/agent.sock
    networks:
      - default # auth-internal-net
      - traefik-net # Ingress proxy
    volumes:
      # Read-only SPIRE Workload API UNIX domain socket
      - spire-socket:/var/run/spire:ro

volumes:
  spire-socket:
    external: true

networks:
  default:
    name: auth-internal-net
    external: true
  traefik-net:
    external: true

5. Administrative Lifecycle & Access Provisioning

Administrative operations are managed via the Auth-Yes Admin Console (https://auth.<domain>/admin):

5.1. Application Registration (`/admin/apps`)

Every internal service connecting to Auth-Yes must be registered:

Application Name: Human-readable label (e.g., Analytics Engine).
SPIFFE ID: Cryptographic workload URI matching the service's container attestation (e.g., spiffe://system.local/analytics-engine).
Description: Functional description of the application.

5.2. User Onboarding & Invite Token Taxonomy (`/admin/invites`)

Auth-Yes uses a structured invite token model for user registration:

Site-Scoped Token (Recommended for subsidiary applications):
- Pre-binds an invite code to a specific application and role (user, operator, admin).
- When a user registers their passkey using this token, their account is automatically activated and granted immediate access to the designated application.
Global Admin Token:
- Grants system-wide administrative access across Auth-Yes management views.
Open / Pending Token:
- Creates an account in pending state requiring explicit administrator review and role assignment before login is permitted.

5.3. Dynamic Role Assignment & Instant Revocation (`/admin/users/:id`)

Grant Management: Administrators can attach or adjust application roles directly in the user profile matrix.
Instant Session Revocation: Terminating a session or revoking an application grant purges active tokens from Valkey in < 1 millisecond, immediately blocking subsequent requests across all microservices.

6. Verification & Troubleshooting

Check	Verification Command / Procedure	Expected Diagnostic
1. Workload Socket Availability	`ls -la /var/run/spire/agent.sock` inside container	File exists with type `s` (UNIX domain socket).
2. Auth Mesh Connectivity	`curl -I http://auth-api:8000/health` inside container	Returns HTTP `200 OK`.
3. Unregistered Service Check	Calling `ValidateSession` from an unassigned application	Returns HTTP `403 Forbidden: Validation failed`.
4. Grant Authorization Check	Calling `ValidateSession` with an active user grant	Returns `{ valid: true, uuid: "...", scopes: ["..."] }`.
5. Revocation Propagation	Revoke session in Admin Console `\rightarrow` Re-issue request	Instant transition to HTTP `401 Unauthorized` without server restarts.

13 KiB Raw Permalink Blame History