GL-IAM

Description

A pluggable Identity and Access Management (IAM) SDK for GDP Labs applications. GL-IAM provides a unified interface for authentication, authorization, user management, and organization management following the Single Interface Multiple Implementation (SIMI) pattern.

Key Features

• Pluggable Authentication: Support for Stack Auth, Keycloak (with LDAP/SAML federation), PostgreSQL, and custom providers
• User Store Abstraction: Flexible user storage with JIT (Just-In-Time) provisioning
• Role-Based Access Control (RBAC): Comprehensive permission and role management
• Multi-Factor Authentication (MFA): TOTP and other second-factor methods
• Organization Management: Multi-tenancy support for enterprise applications
• FastAPI Integration: Ready-to-use dependencies for FastAPI applications

Installation

Prerequisites

Mandatory:

1. Python 3.11+ — Install here
2. pip — Install here
3. uv — Install here

For PostgreSQL provider: 4. PostgreSQL 13+ — Recommended for production (details)

Extras (required only for Artifact Registry installations):

1. gcloud CLI (for authentication) — Install here, then log in using:

   gcloud auth login
   

Option 1: Install from PyPI (recommended)

This option requires no authentication.

uv pip install gl-iam

With optional dependencies:

# With FastAPI integration
uv pip install "gl-iam[fastapi]"

# With Stack Auth provider
uv pip install "gl-iam[stackauth]"

# With LDAP provider
uv pip install "gl-iam[ldap]"

# With asymmetric (RS256/ES256) delegation token signing
uv pip install "gl-iam[asymmetric]"

# With all providers
uv pip install "gl-iam[all]"

Option 2: Install from Artifact Registry

This option requires authentication via the gcloud CLI. Use it when you need a build that is not yet released to PyPI.

uv pip install \
  --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" \
  gl-iam

Quick Start

Basic Usage

from gl_iam import IAMGateway
from gl_iam.providers.stackauth import StackAuthProvider

# Initialize with Stack Auth as full-stack provider
gateway = IAMGateway.from_fullstack_provider(
    provider=StackAuthProvider(
        api_url="https://api.stack-auth.com",
        project_id="your-project-id",
        secret_key="your-secret-key",
    )
)

# Authenticate a user
result = await gateway.authenticate(
    credentials={"email": "user@example.com", "password": "secret"}
)

if result.is_ok:
    user = result.user
    print(f"Authenticated: {user.display_name}")

Mix-and-Match Providers

from gl_iam import IAMGateway
from gl_iam.providers.ldap import LDAPAuthProvider
from gl_iam.providers.stackauth import StackAuthUserStore

# Use LDAP for authentication, Stack Auth for user storage
gateway = IAMGateway(
    auth_provider=LDAPAuthProvider(
        server_url="ldap://ad.company.com",
        base_dn="dc=company,dc=com",
    ),
    user_store=StackAuthUserStore(
        api_url="https://api.stack-auth.com",
        project_id="your-project-id",
    ),
    enable_jit_provisioning=True,  # Auto-create users on first login
)

FastAPI Integration

from fastapi import FastAPI, Depends
from gl_iam.fastapi import get_current_user, require_permission, require_role
from gl_iam.types import User

app = FastAPI()

@app.get("/profile")
async def get_profile(user: User = Depends(get_current_user)):
    return {"user_id": user.id, "email": user.email}

@app.delete("/admin/users/{user_id}")
async def delete_user(
    user_id: str,
    _: None = Depends(require_permission("users:delete")),
):
    # Only users with "users:delete" permission can access
    pass

@app.get("/admin/dashboard")
async def admin_dashboard(_: None = Depends(require_role("admin"))):
    # Only users with "admin" role can access
    pass

Local Development Setup

Prerequisites

1. Python 3.11+ — Install here

2. pip — Install here

3. uv — Install here

4. gcloud CLI — Install here, then log in using:

   gcloud auth login
   

5. Git — Install here

6. Access to the GDP Labs SDK GitHub repository

1. Clone Repository

git clone git@github.com:GDP-ADMIN/gl-sdk.git
cd gl-sdk/libs/gl-iam

2. Setup Authentication

Set the following environment variables to authenticate with internal package indexes:

export UV_INDEX_GEN_AI_INTERNAL_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_INTERNAL_PASSWORD="$(gcloud auth print-access-token)"
export UV_INDEX_GEN_AI_USERNAME=oauth2accesstoken
export UV_INDEX_GEN_AI_PASSWORD="$(gcloud auth print-access-token)"

3. Quick Setup

Run:

make setup

4. Activate Virtual Environment

source .venv/bin/activate

Local Development Utilities

The following Makefile commands are available for quick operations:

Install uv

make install-uv

Install Pre-Commit

make install-pre-commit

Install Dependencies

make install

Update Dependencies

make update

Run Tests

make test

Architecture

GL-IAM follows the Single Interface Multiple Implementation (SIMI) pattern:

┌─────────────────────────────────────────────────────────────┐
│                       IAMGateway                            │
│  (Central Orchestrator - Coordinates all IAM operations)    │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│ Authentication│    │  User Store   │    │   Session     │
│   Provider    │    │   Provider    │    │   Provider    │
└───────────────┘    └───────────────┘    └───────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  - Stack Auth │    │  - Stack Auth │    │  - Stack Auth │
│  - LDAP       │    │  - PostgreSQL │    │  - Redis      │
│  - SAML       │    │  - Custom     │    │  - JWT        │
│  - OAuth2     │    │               │    │               │
└───────────────┘    └───────────────┘    └───────────────┘

Migration Guides

Migrating from BOSA Core Auth

If you're currently using BOSA Core Authentication (bosa-core[authentication]) and want to migrate to GL-IAM, see the comprehensive migration guide:

📖 BOSA to GL-IAM Migration Guide

The guide covers:

• Step-by-step migration instructions
• API mapping reference (BOSA → GL-IAM)
• Data migration scripts
• Code examples for common patterns
• Testing and rollback strategies

Contributing

Please refer to the Python Style Guide for information about code style, documentation standards, and SCA requirements.