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 Artifact Registry

This option requires authentication via the gcloud CLI.

uv pip install \
  --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" \
  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 all providers
uv pip install "gl-iam[all]"

---

Option 2: Install from PyPI

This option requires no authentication. However, it installs the binary wheel version of the package, which is fully usable but does not include source code.

uv pip install gl-iam-binary

---

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.