authx-identity

Standalone OpenID Connect (OIDC) identity microservice and Django client for application identity integration.

• Maintained by: https://djangoplay.org
• Documentation: https://docs.djangoplay.org

authx-identity provides a standalone FastAPI identity service together with a small Django client library.

AuthX is designed to be an independent identity authority that can be integrated into Django applications and other backend systems.

Features

• OIDC-style identity endpoints
• Email/password authentication
• SSO identity support
• RS256 JWT access and refresh tokens
• JWKS public-key endpoint
• Local JWT verification
• Server-to-server identity management API
• Django client library
• Stateless token validation
• PostgreSQL persistence
• Alembic migrations
• Configurable JWT issuer and audience
• Provider-independent consumer architecture

Architecture

AuthX is the identity and JWT authority.

                    AuthX
                      │
          ┌───────────┴───────────┐
          │                       │
       JWT signing             Identity
          │                       │
          ▼                       ▼
     Access tokens          User identities
          │
          ▼
   Consumer applications
          │
          └── verify locally
              using JWKS

A consuming application does not need the AuthX private key.

The private signing key remains exclusively inside AuthX.

Requirements

• Python 3.11 or later
• PostgreSQL
• FastAPI
• SQLAlchemy
• Alembic

A Django application using the client additionally requires Django.

Installation

Install the AuthX package:

pip install authx-identity

For Django consumers:

pip install "authx-identity[django]"

Running AuthX

Create a local environment:

cp env.example .env

Generate a new RSA key pair:

openssl genrsa -out jwt_private.pem 2048

openssl rsa \
  -in jwt_private.pem \
  -pubout \
  -out jwt_public.pem

Validate the private key:

openssl rsa -in jwt_private.pem -check -noout

Expected:

RSA key ok

Verify the public key:

openssl rsa \
  -in jwt_private.pem \
  -pubout \
  -outform PEM | diff - jwt_public.pem

No output indicates a matching public key.

Convert the PEM files into .env values:

awk 'NF {printf "%s\\n", $0}' jwt_private.pem
awk 'NF {printf "%s\\n", $0}' jwt_public.pem

Configure:

JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"

JWT_ALGORITHM=RS256
JWT_ISSUER=https://auth.example.com
JWT_AUDIENCE=your-application

AUTHX_SERVICE_TOKEN=<strong-random-secret>

Run migrations:

authx-migrate upgrade

authx-migrate is installed automatically alongside the authx-identity package and ships the migration scripts internally — no source checkout or direct Alembic usage required. It reads the same DATABASE_URL_SYNC your service config already provides, so make sure your environment variables (or .env file) are loaded into the shell before running it, e.g.:

set -a; source .env; set +a
authx-migrate upgrade

Other available subcommands: authx-migrate current, authx-migrate history.

Start AuthX:

uvicorn authx.main:app --host 0.0.0.0 --port 8100

Django integration

Configure the Django application with the AuthX service location and verification parameters:

AUTHX_BASE_URL = "https://auth.example.com"
AUTHX_SERVICE_TOKEN = "..."

AUTHX_JWT_ALGORITHM = "RS256"
AUTHX_JWT_ISSUER = "https://auth.example.com"
AUTHX_JWT_AUDIENCE = "your-application"

The service token is required only for trusted backend calls to AuthX's internal API.

The Django application does not require the AuthX private key.

Identity management

Create or look up identities through the client:

from authx_client import AuthXClient, AuthXConflictError

client = AuthXClient()

try:
    identity = client.create_identity(
        email="user@example.com",
        username="user",
        password="...",
    )
except AuthXConflictError:
    identity = client.get_by_email("user@example.com")

JWT verification

Consumers should verify AuthX tokens locally.

from authx_client import AuthXJWT

payload = AuthXJWT.decode(token)
identity_id = AuthXJWT.get_identity_id(token)

JWT verification validates:

• signature
• algorithm
• issuer
• audience
• token validity

The consumer can use AuthX's JWKS endpoint to obtain the public signing key.

Public API

Method	Endpoint	Purpose
GET	/.well-known/openid-configuration	OIDC discovery
GET	/jwks	Public signing keys
POST	/token	Issue tokens
POST	/token/refresh	Refresh tokens
GET	/userinfo	Identity information

Internal API

Method	Endpoint	Purpose
POST	/internal/identities	Create identity
GET	/internal/identities/{id}	Retrieve identity
GET	/internal/identities/by-email/{email}	Find identity by email
GET	/internal/identities/by-sso/lookup	Find SSO identity
PATCH	/internal/identities/{id}	Update identity
DELETE	/internal/identities/{id}	Soft-delete identity

Internal endpoints require X-Service-Token and are intended for trusted backend services.

Configuration

Variable	Description
APP_ENV	Runtime environment
APP_HOST	Service bind host
APP_PORT	Service port
APP_BASE_URL	AuthX service URL
DATABASE_URL	Async PostgreSQL URL
DATABASE_URL_SYNC	Sync PostgreSQL URL
JWT_PRIVATE_KEY	RSA private signing key
JWT_PUBLIC_KEY	RSA public verification key
JWT_ALGORITHM	JWT algorithm
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	Access-token lifetime
JWT_REFRESH_TOKEN_EXPIRE_DAYS	Refresh-token lifetime
JWT_ISSUER	JWT issuer
JWT_AUDIENCE	JWT audience
AUTHX_SERVICE_TOKEN	Internal API credential
CORS_ORIGINS	Allowed browser origins

JWT_ISSUER and JWT_AUDIENCE must be explicitly configured for every deployment.

Security

Never commit:

• .env
• RSA private keys
• service tokens
• database passwords

The AuthX private key must remain inside the AuthX deployment.

Consumer applications should use JWKS/public-key verification rather than receiving the private signing key.

License

MIT.