authx-identity 0.1.0rc1

Standalone OIDC identity microservice and client library for DjangoPlay and Python applications.

AuthX

Maintained by

https://djangoplay.org

Standalone OIDC identity microservice for codefleetx applications.

What it does

AuthX is a standards-compliant OpenID Connect (OIDC) identity provider built with FastAPI. It:

• Issues signed JWT access tokens and refresh tokens
• Exposes public OIDC endpoints (/token, /userinfo, /jwks, /.well-known/openid-configuration)
• Exposes an internal API (/internal/identities) for trusted services (e.g. DjangoPlay) to create and look up identities
• Supports email/password and SSO (Google, Apple) identity providers
• Is stateless and horizontally scalable

Architecture

┌──────────────────────────────────────┐
│  Client (browser, mobile, CLI)       │
│  → POST /token (login)               │
│  → GET  /userinfo (who am I?)        │
└────────────────┬─────────────────────┘
                 │ JWT
     ┌───────────▼──────────────────┐
     │         AuthX                │
     │  FastAPI + PostgreSQL        │
     │  Issues & validates JWTs     │
     └───────────┬──────────────────┘
                 │ Internal API (service token)
     ┌───────────▼──────────────────┐
     │       DjangoPlay             │
     │  Trusts AuthX JWTs           │
     │  Owns EmploymentProfile      │
     │  Owns MemberProfile          │
     └──────────────────────────────┘

Endpoints

Public OIDC

Method	Path	Description
GET	/.well-known/openid-configuration	OIDC discovery document
GET	/jwks	Public keys for JWT verification
POST	/token	Issue access + refresh token
POST	/token/refresh	Refresh access token
GET	/userinfo	Get identity info from token

Internal (service token required)

Method	Path	Description
POST	/internal/identities	Create identity
GET	/internal/identities/{id}	Get identity by ID
GET	/internal/identities/by-email/{email}	Lookup by email
GET	/internal/identities/by-sso	Lookup by SSO provider + ID
PATCH	/internal/identities/{id}	Update identity fields
DELETE	/internal/identities/{id}	Soft delete identity

Running locally

cp .env.example .env
# fill in values

docker compose up

Migrations run automatically on startup.

Running in production

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Environment variables

See .env.example for all required variables.

JWT verification (for consumers)

Consumers (DjangoPlay, etc.) should:

1. Fetch public keys from /jwks on startup (cache them)
2. Verify JWT signatures locally — no AuthX call needed per request
3. Only call /userinfo for server-to-server lookups without a JWT in hand