Skip to content

auth-mode.md

Latest commit

 

History

History
171 lines (131 loc) · 5.9 KB

auth-mode.md

File metadata and controls

171 lines (131 loc) · 5.9 KB

Authentication Modes & Guide

Pangolin supports two distinct operational modes: Auth Mode (Production) and No-Auth Mode (Development). This guide details how to configure, access, and manage identity in both scenarios.

1. Auth Mode vs. No-Auth Mode

Feature Auth Mode (Default) No-Auth Mode
Use Case Production, Multi-Tenancy, Public Internet Local Dev, CI/CD, Rapid Prototyping
Security Enforced via JWT Tokens Disabled (Open Access)
Identity Users must log in; Identity is verified Requests default to admin; Password checks bypassed
Setup Requires PANGOLIN_JWT_SECRET Requires PANGOLIN_NO_AUTH=true
Tenant Context Strict isolation; Users belong to 1 Tenant Default Tenant used automatically if unspecified

2. Configuration (Environment Variables)

Root User Credentials

The Root User is the system superadmin. These credentials are used to bootstrap the system (create the first tenant).

Auth Mode:

# Secure credentials for production
export PANGOLIN_ROOT_USER="super_admin"
export PANGOLIN_ROOT_PASSWORD="Start123!ComplexPassword"
export PANGOLIN_JWT_SECRET="<random-32-char-string>"

No-Auth Mode:

# Credentials are ignored, but variables can still be set
export PANGOLIN_NO_AUTH="true"

3. UI Login Nuances

The Management UI adapts its login form based on the detected mode.

Auth Mode UI

  • Standard Login (Root): By default, the "Tenant-specific login" checkbox is unchecked.
    • Entering just a Username/Password sends a null Tenant ID.
    • This triggers the Root Authentication flow (checking PANGOLIN_ROOT_USER).
  • Tenant User Login: Accessing a specific tenant requires:
    1. Checking the "Tenant-specific login" box.
    2. Entering the Tenant ID (UUID).
    3. Entering Username/Password.
  • Behavior: Invalid credentials return a 401 error. Session expires when the JWT expires.

No-Auth Mode UI

  • Auto-Detection: The UI detects NO_AUTH state on load.
  • Root Access (Bypass): To view the Root Dashboard (System Admin view), use these specific credentials:
    • Username: root
    • Password: root
    • Note: This is a client-side convenience bypass that gives you full UI access without needing a server token.
  • Tenant Admin Access: The UI may auto-login as the default admin, or you can use the credentials below.

4. Root User Workflows

The Root User's primary job is System bootstrapping. They generally do not query data.

Workflow A: Bootstrapping in No-Auth Mode

When Pangolin starts in No-Auth Mode (PANGOLIN_NO_AUTH=true), it automatically:

  1. Creates a default Tenant (00000000-0000-0000-0000-000000000000).
  2. Creates a default Tenant Admin with:
    • Username: tenant_admin
    • Password: password123
  3. Allows Anonymous API Access: Requests with no Authorization header are automatically treated as this tenant_admin.

Workflow B: Logging In as Root (Auth Mode)

Via API (cURL):

# Auth Mode: Must provide correct password & null tenant-id
curl -X POST http://localhost:8080/api/v1/users/login \
  -d '{"username":"super_admin", "password":"...", "tenant-id":null}'

Workflow B: Creating a Tenant & Admin (Bootstrapping)

Only the Root user can create tenants.

1. Create Tenant:

# Requires Root Token
POST /api/v1/tenants
{
  "name": "acme-corp"
}
# Response: Returns { "id": "uuid-for-acme", ... }

2. Create Tenant Admin:

# Requires Root Token
# Note: You are creating a user *inside* the new tenant
POST /api/v1/users
{
  "username": "acme_admin",
  "password": "temporary_password",
  "tenant_id": "uuid-for-acme",  # Critical: Links user to tenant
  "role": "TenantAdmin"
}

5. Token Generation Guide

Authentication tokens (JWTs) act as your API keys for all operations.

Generating a Token (Generic)

Endpoint: POST /api/v1/tokens (Requires Admin privileges) or POST /api/v1/users/login (Self-service).

Payload:

{
  "username": "data_engineer",
  "password": "secure_password",
  "tenant_id": "uuid-for-acme"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1Ni...",
  "expires_in": 86400,
  "tenant_id": "uuid-for-acme"
}

Using the Token

Pass it in the HTTP Header:

Authorization: Bearer eyJhbGciOiJIUzI1Ni...

6. Permissions Matrix: Who can touch what?

Pangolin employs a strict hierarchy. Here is what each user type can access.

Resource Root User Tenant Admin Tenant User
Manage Tenants ✅ Create/Delete ❌ No Access ❌ No Access
Manage Users ✅ (Global) ✅ (Own Tenant Only) ❌ No Access
Create Warehouses ❌ (Out of Scope) ✅ Full Control ❌ No Access
Create Catalogs ❌ (Out of Scope) ✅ Full Control ❌ No Access
Manage Roles ❌ (Out of Scope) ✅ Full Control ❌ No Access
Query Data ❌ No Access* ✅ Full Access ⚠️ By Permission Only
View Audit Logs ✅ (System Wide) ✅ (Own Tenant Only) ❌ No Access

*Note on Root Data Access: By design, the Root user cannot query data (tables/views) directly. They must authenticate as a Tenant Admin or specific User to modify actual data. This enforcement ensures "System Administrators" cannot casually browse sensitive data "Business Data".

Tenant User Permissions (RBAC)

A standard Tenant User starts with ZERO permissions. They cannot see Catalogs or query Tables until granted a Role:

  • Reader Role: Can SELECT from tables.
  • Writer Role: Can INSERT/UPDATE/DELETE.
  • Discovery Role: Can search for assets but not query contents.

See Permissions Management for how to assign these granular rights.