Skip to content

authentication.md

Latest commit

 

History

History
131 lines (99 loc) · 5.02 KB

authentication.md

File metadata and controls

131 lines (99 loc) · 5.02 KB

Authentication & Access Control

Pangolin supports secure authentication via JWT Tokens, API Keys (Service Users), and OAuth 2.0 / OIDC (Google, GitHub, Microsoft, Okta).

🚀 Authentication Modes

Pangolin can be configured in three primary authentication modes via environment variables:

1. No-Auth Mode (Development Only)

Disables all authentication checks. All requests are treated as being made by the root superadmin.

  • Environment Variable: PANGOLIN_NO_AUTH=true
  • Use Case: Local development, quick prototyping, automated integration tests.

Caution

Never use No-Auth mode in production or any environment accessible from the internet.

2. JWT Authentication (Standard)

The default mode for secure, stateless session management.

  • Root Credentials: Initial setup uses PANGOLIN_ROOT_USER (default: admin) and PANGOLIN_ROOT_PASSWORD (default: password).
  • Secret Key: You must set PANGOLIN_JWT_SECRET to a strong random string (at least 32 characters).
  • Flow: POST credentials to /api/v1/users/login -> Receive JWT -> Include in header: Authorization: Bearer <jwt>.

Tenant-Scoped Login

For multi-tenant deployments, users can have the same username across different tenants. To resolve username collisions, include the tenant-id field in login requests:

Root Login (no tenant context):

curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password","tenant-id":null}'

Tenant-Scoped Login (with tenant context):

curl -X POST http://localhost:8080/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"pass123","tenant-id":"<tenant-uuid>"}'

Important

The field name is tenant-id (kebab-case), not tenant_id (underscore). This is due to the LoginRequest struct using #[serde(rename_all = "kebab-case")].

3. OAuth 2.0 / OIDC (Enterprise SSO)

Allows users to sign in with external identity providers.

  • Supported Providers: Google, Microsoft (Entra ID), GitHub, Okta.
  • Configuration: Requires FRONTEND_URL and provider-specific Client IDs/Secrets. See Provider Setup below.

🔑 Service Users & API Keys

For programmatic access (CI/CD, ETL, automation), use Service Users.

  • Service users use X-API-Key authentication rather than JWTs.
  • They are managed via the UI or the pangolin-admin service-users CLI.
  • See the Service Users Guide for details.

🛠️ Provider Setup (OAuth)

Google

  1. Create a project in Google Cloud Console.
  2. Setup OAuth 2.0 Client ID for a Web Application.
  3. Redirect URI: https://<api-domain>/oauth/callback/google.
  • Env: OAUTH_GOOGLE_CLIENT_ID, OAUTH_GOOGLE_CLIENT_SECRET, OAUTH_GOOGLE_REDIRECT_URI.

Microsoft (Azure AD)

  1. Register an app in the Azure Portal.
  2. Add a Web platform and Redirect URI: https://<api-domain>/oauth/callback/microsoft.
  • Env: OAUTH_MICROSOFT_CLIENT_ID, OAUTH_MICROSOFT_CLIENT_SECRET, OAUTH_MICROSOFT_TENANT_ID, OAUTH_MICROSOFT_REDIRECT_URI.

GitHub

  1. Create an OAuth App in Settings > Developer settings.
  2. Callback URL: https://<api-domain>/oauth/callback/github.
  • Env: OAUTH_GITHUB_CLIENT_ID, OAUTH_GITHUB_CLIENT_SECRET, OAUTH_GITHUB_REDIRECT_URI.

🐍 Connecting with PyIceberg

Option A: Standard OAuth2 Credential Flow (Recommended)

Use a Service User's client_id (UUID) and client_secret (API Key) for automated authentication.

from pyiceberg.catalog import load_catalog

catalog = load_catalog(
    "pangolin",
    **{
        "uri": "http://localhost:8080/v1/default/",
        "type": "rest",
        "credential": "<service_user_uuid>:<api_key>",
        "oauth2-server-uri": "http://localhost:8080/v1/default/v1/oauth/tokens",
        "scope": "catalog"
    }
)

Note

The oauth2-server-uri must be the full path. Pangolin supports paths starting with both /v1/... and /api/v1/iceberg/....

Option B: Manual Token (Access Token)

If you have a JWT from a previous login:

from pyiceberg.catalog import load_catalog

catalog = load_catalog(
    "pangolin",
    **{
        "uri": "http://localhost:8080/v1/default/",
        "token": "YOUR_JWT_TOKEN",
    }
)

Option B: Credential Vending (Recommended)

Pangolin automatically vends S3/Cloud credentials if the Warehouse is configured with a role. You only need to provide the Pangolin token.

🛡️ Troubleshooting

401 Unauthorized

  • Cause: Token missing, expired, or invalid secret.
  • Fix: Verify PANGOLIN_JWT_SECRET matches across all instances. Regenerate token via login.

403 Forbidden

  • Cause: User lacks RBAC permissions for the resource (Catalog/Namespace/Asset).
  • Fix: Verify roles in the Management UI or via pangolin-admin permissions.