Quickstart: PostgreSQL

A self-contained GL IAM quickstart using PostgreSQL - no external auth services required.

When to use PostgreSQL: Choose the PostgreSQL provider when you want full control over user data, the fastest local setup, or don't need external identity provider features like SSO or social login.

When to use this page: Use this Quickstart when you want the fastest "it works on my machine" proof. You can run GL IAM with PostgreSQL locally (no external IdP needed) and do the full lifecycle: register → login → validate.

What you'll build: A minimal local setup that runs PostgreSQL using Docker, installs GL IAM, and runs a Python script that creates a user with password and authenticates them.

Prerequisites

This example requires completion of all setup steps listed on the Prerequisites page. To summarize:

• Python 3.11+

• Docker (for PostgreSQL)

• Access to the GDP Labs' Gen AI SDK repository (request via form or [e-mail])

• gcloud CLI: Install, then run gcloud auth login

• uv — Install with: curl -LsSf https://astral.sh/uv/install.sh | sh

Setup PostgreSQL

Start PostgreSQL with Docker:

docker run -d --name gliam-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=gliam \
  -p 5432:5432 \
  postgres:16

Installation

Install GL IAM from the internal Google Artifact Registry (latest version).

Linux, macOS, or Windows WSL

uv init --bare
uv add --extra-index-url "https://oauth2accesstoken:$(gcloud auth print-access-token)@glsdk.gdplabs.id/gen-ai-internal/simple/" "gl-iam[postgresql]"

Windows PowerShell

Windows Command Prompt

Quick Start

1

Setup Provider

from gl_iam import IAMGateway
from gl_iam.core.types import PasswordCredentials, UserCreateInput
from gl_iam.core.types.result import ErrorCode
from gl_iam.providers.postgresql import PostgreSQLProvider, PostgreSQLConfig

config = PostgreSQLConfig(database_url="postgresql+asyncpg://postgres:postgres@localhost:5432/gliam")
provider = PostgreSQLProvider(config)
gateway = IAMGateway.from_fullstack_provider(provider)

2

Create User with Password

result = await gateway.create_user_with_password(
    user_data=UserCreateInput(email="[e-mail]", display_name="Alice"),
    password="SecurePass123",
    organization_id="default",
)

if result.is_ok:
    user = result.value
    print(f"Created user: {user.email}")
elif result.error.code == ErrorCode.USER_ALREADY_EXISTS:
    print("User already exists")

3

Authenticate User

result = await gateway.authenticate(
    credentials=PasswordCredentials(email="[e-mail]", password="SecurePass123"),
    organization_id="default",
)

if result.is_ok:
    user, token = result.unwrap()
    print(f"Hello, {user.display_name or user.email}!")

4

Expected Output

Created user: [e-mail]
Hello, Alice!

Congratulations! You've verified GL IAM is working with PostgreSQL.

Complete Example

This example includes user registration with password and authentication - the full auth lifecycle.

Create quickstart.py:

"""GL IAM Quickstart with PostgreSQL Provider."""

import asyncio

from gl_iam import IAMGateway
from gl_iam.core.types import PasswordCredentials, UserCreateInput
from gl_iam.core.types.result import ErrorCode
from gl_iam.providers.postgresql import PostgreSQLProvider, PostgreSQLConfig

DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/gliam"


async def main():
    # Step 1: Setup GL IAM
    config = PostgreSQLConfig(database_url=DATABASE_URL)
    provider = PostgreSQLProvider(config)
    gateway = IAMGateway.from_fullstack_provider(provider)

    # Step 2: Create user with password (registration)
    result = await gateway.create_user_with_password(
        user_data=UserCreateInput(
            email="[e-mail]",
            display_name="Alice",
        ),
        password="SecurePass123",
        organization_id="default",
    )

    if result.is_ok:
        user = result.value
        print(f"Created user: {user.email}")
    elif result.error.code == ErrorCode.USER_ALREADY_EXISTS:
        print("User [e-mail] already exists, skipping creation")
    else:
        print(f"Error creating user: {result.error.message}")

    # Step 3: Authenticate (login)
    result = await gateway.authenticate(
        credentials=PasswordCredentials(email="[e-mail]", password="SecurePass123"),
        organization_id="default",
    )

    # Step 4: Check result and print success message
    if result.is_ok:
        user, token = result.unwrap()
        print(f"Hello, {user.display_name or user.email}!")
        print(f"User ID: {user.id}")
        print(f"Token: {token.access_token[:50]}...")
    else:
        print(f"Authentication failed: {result.error.message}")

    await provider.close()


if __name__ == "__main__":
    asyncio.run(main())

Run it:

uv run quickstart.py

Expected output (first run):

Created user: [e-mail]
Hello, Alice!
User ID: 550e8400-e29b-41d4-a716-446655440000
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...

Expected output (subsequent runs):

User [e-mail] already exists, skipping creation
Hello, Alice!
User ID: 550e8400-e29b-41d4-a716-446655440000
Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...

Common Pitfalls

Pitfall	Solution
Port 5432 already in use	Map to another port: -p 5433:5432 and update DATABASE_URL
Wrong DB URL scheme	Keep asyncpg in the URL: postgresql+asyncpg://...
Org/Tenant confusion	organization_id="default" is a local placeholder—use your real tenant/org ID in production

Cleanup

Stop and remove the PostgreSQL container when done:

docker stop gliam-postgres && docker rm gliam-postgres

Other Providers

GL IAM supports multiple identity providers with the same application code. Only the configuration changes:

• Quickstart: Stack Auth - Modern managed authentication with UI components

• Quickstart: Keycloak - Enterprise identity management with SSO