DjangoPlay ↔ AuthX Integration Architecture

This document describes how DjangoPlay integrates with AuthX for identity, authentication, and SSO.

DjangoPlay remains the application platform and domain owner, while AuthX acts as the centralized identity service.

1. Integration Overview

DjangoPlay and AuthX are separate applications with clearly defined responsibilities.

DjangoPlay owns application-level user data, domain relationships, authorization, and business workflows.

AuthX owns identity and authentication concerns such as credentials, authentication state, SSO identity linkage, and token handling.

flowchart LR

    USER["Users / Clients"]

    subgraph DJANGO["DjangoPlay"]
        UI["Web UI / API"]
        AUTHFLOW["Authentication Flows"]
        SYNC["Identity Synchronization"]
        CLIENT["AuthXClient"]
        LOCAL["Local UserIdentity Mirror"]
        POLICY["Application Authorization"]
    end

    subgraph AUTHX["AuthX"]
        API["Identity / Authentication API"]
        SERVICE["Identity Service"]
        DB["AuthX PostgreSQL"]
    end

    USER --> UI
    UI --> AUTHFLOW
    AUTHFLOW --> CLIENT
    CLIENT -->|"HTTP + X-Service-Token"| API

    API --> SERVICE
    SERVICE --> DB

    API -->|"Identity response"| SYNC
    SYNC --> LOCAL

    LOCAL --> POLICY

    classDef client fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef django fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef data fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER client
    class UI,AUTHFLOW,SYNC,CLIENT,LOCAL,POLICY django
    class API,SERVICE authx
    class DB data

Architectural principle

AuthX is the identity authority; DjangoPlay maintains a local application-level mirror of the identity.

The local mirror exists so that DjangoPlay can maintain application relationships, permissions, profiles, and domain-specific data without making AuthX the owner of the Django application's domain model.

2. Responsibility Boundary

The integration is intentionally divided into two responsibility domains.

DjangoPlay owns

User-facing application flows
Application-specific user and profile data
Local UserIdentity representation
Application relationships and foreign keys
Groups and application permissions
Policy-based authorization
Domain workflows
Integration with AuthX through AuthXClient

AuthX owns

Identity records
Authentication credentials
Password hashing
Authentication workflows
SSO identity linkage
Identity state
JWT/token operations
Authoritative identity information

This separation prevents authentication concerns from becoming distributed throughout the DjangoPlay application.

3. Identity Architecture

The identity relationship can be represented as:

flowchart TD

    USER["User"]

    subgraph DJANGO["DjangoPlay"]
        FLOW["Signup / Login / SSO Flow"]
        CLIENT["AuthXClient"]
        MIRROR["UserIdentity<br/><small>Local application mirror</small>"]
        DATA["Application Data<br/><small>Profiles • Relationships • Permissions</small>"]
    end

    subgraph AUTHX["AuthX"]
        IDENTITY["Authoritative Identity"]
        CREDENTIALS["Credentials / Authentication"]
        SSO["SSO Identity Linkage"]
        AUTHDB["AuthX PostgreSQL"]
    end

    USER --> FLOW
    FLOW --> CLIENT
    CLIENT --> IDENTITY

    IDENTITY --> CREDENTIALS
    IDENTITY --> SSO
    IDENTITY --> AUTHDB

    IDENTITY -->|"Identity data"| MIRROR
    MIRROR --> DATA

    classDef user fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef django fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef db fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER user
    class FLOW,CLIENT,MIRROR,DATA django
    class IDENTITY,CREDENTIALS,SSO authx
    class AUTHDB db

The important distinction is:

text

AuthX
    ↓
Authoritative identity

DjangoPlay
    ↓
Local identity mirror + application data

4. DjangoPlay Integration Components

The DjangoPlay side of the integration is centered around the AuthX client and identity synchronization services.

The general structure is:

text

Authentication Flow
       │
       ▼
AuthX Integration Service
       │
       ▼
AuthXClient
       │
       ▼
AuthX HTTP API

The synchronization layer is responsible for keeping the local UserIdentity representation aligned with the authoritative AuthX identity.

Typical operations include:

Create identity
Update identity
Retrieve identity
Lookup identity by email
Synchronize identity information
Maintain the local identity mirror

5. AuthX Client

DjangoPlay communicates with AuthX through an HTTP client abstraction rather than making raw HTTP calls throughout the application.

Conceptually:

flowchart LR

    FLOW["DjangoPlay Authentication Flow"]
    SERVICE["Identity Sync / Auth Service"]
    CLIENT["AuthXClient"]
    HTTP["HTTP Request"]
    AUTHX["AuthX API"]

    FLOW --> SERVICE
    SERVICE --> CLIENT
    CLIENT --> HTTP
    HTTP -->|"X-Service-Token"| AUTHX

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef transport fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class FLOW,SERVICE,CLIENT app
    class HTTP transport
    class AUTHX authx

This provides a single integration boundary for:

Base URL configuration
Service authentication
HTTP communication
Request handling
AuthX API interaction

This also prevents AuthX-specific HTTP details from leaking into domain applications.

6. DjangoPlay → AuthX Communication

DjangoPlay communicates with AuthX over HTTP.

The internal AuthX API is protected using a service-to-service authentication header:

http

X-Service-Token: <AUTHX_SERVICE_TOKEN>

The high-level communication path is:

text

DjangoPlay
    │
    │ HTTPS / HTTP
    │ X-Service-Token
    ▼
AuthX Internal API
    │
    ▼
Identity Service
    │
    ▼
AuthX Database

In local development, AuthX may run on a local service endpoint such as:

text

http://localhost:8100

The actual endpoint is environment-specific and is supplied through DjangoPlay configuration.

7. Service Authentication

DjangoPlay authenticates itself to AuthX as a trusted internal service.

sequenceDiagram

    participant DP as DjangoPlay
    participant AX as AuthX

    DP->>AX: HTTP request
    DP->>AX: X-Service-Token
    AX->>AX: Validate service token

    alt Token valid
        AX->>DP: Process request
    else Token invalid
        AX->>DP: Reject request
    end

The service token is a shared secret between the two services.

It must be treated as infrastructure credential material and must not be exposed to browsers or client-side code.

8. Identity Creation Flow

When DjangoPlay needs to create a new identity, AuthX creates the authoritative identity first.

sequenceDiagram

    participant U as User
    participant DP as DjangoPlay
    participant SYNC as Identity Sync Service
    participant CLIENT as AuthXClient
    participant AX as AuthX
    participant DB as AuthX PostgreSQL
    participant MIRROR as DjangoPlay UserIdentity

    U->>DP: Signup
    DP->>SYNC: Create identity
    SYNC->>CLIENT: create_identity()
    CLIENT->>AX: POST identity request
    AX->>DB: Create authoritative identity
    DB-->>AX: Identity created
    AX-->>CLIENT: Identity response
    CLIENT-->>SYNC: Identity data
    SYNC->>MIRROR: Synchronize local identity
    MIRROR-->>DP: Local identity available

Design rule

The order is intentional:

text

Create authoritative AuthX identity
             ↓
Receive identity information
             ↓
Synchronize DjangoPlay mirror

DjangoPlay should not create an independent authentication identity that competes with AuthX.

9. Identity Update Flow

Updates follow the same authority model.

sequenceDiagram

    participant DP as DjangoPlay
    participant SYNC as Identity Sync
    participant CLIENT as AuthXClient
    participant AX as AuthX
    participant DB as AuthX PostgreSQL
    participant MIRROR as UserIdentity

    DP->>SYNC: Update identity
    SYNC->>CLIENT: update_identity()
    CLIENT->>AX: PUT identity request
    AX->>DB: Update authoritative identity
    DB-->>AX: Updated identity
    AX-->>CLIENT: Identity response
    CLIENT-->>SYNC: Updated identity
    SYNC->>MIRROR: Synchronize local mirror

This keeps AuthX as the authoritative source while allowing DjangoPlay to maintain its local representation.

10. Identity Lookup

DjangoPlay can retrieve identity information from AuthX when required.

Typical operations include:

text

Get identity by ID
Get identity by email
Create identity
Update identity

Conceptually:

flowchart LR

    DP["DjangoPlay"]
    CLIENT["AuthXClient"]

    GETID["Get by identity ID"]
    GETEMAIL["Get by email"]
    CREATE["Create identity"]
    UPDATE["Update identity"]

    AX["AuthX Identity API"]

    DP --> CLIENT

    CLIENT --> GETID
    CLIENT --> GETEMAIL
    CLIENT --> CREATE
    CLIENT --> UPDATE

    GETID --> AX
    GETEMAIL --> AX
    CREATE --> AX
    UPDATE --> AX

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef operation fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class DP,CLIENT app
    class GETID,GETEMAIL,CREATE,UPDATE operation
    class AX authx

11. Local `UserIdentity` Mirror

DjangoPlay maintains a local identity representation because the Django application needs to associate identity with its own domain model.

The local representation can provide application access to information such as:

text

authx_id
username
email
sso_provider
sso_id
is_active
is_verified
is_staff
is_superuser

The exact fields are determined by the current DjangoPlay implementation.

The architectural distinction is:

Data	Authority
Authentication identity	AuthX
Password credentials	AuthX
SSO identity linkage	AuthX
Application profile data	DjangoPlay
Application relationships	DjangoPlay
Application permissions	DjangoPlay
Domain-specific data	DjangoPlay

The mirror is therefore not a second authentication authority.

12. Authentication and Authorization Boundary

Authentication and authorization are separate concerns.

flowchart LR

    USER["User"]

    AUTH["Authentication"]
    AX["AuthX"]

    IDENTITY["Authenticated Identity"]

    POLICY["DjangoPlay Policy / Authorization"]
    ACCESS["Allow / Deny"]

    USER --> AUTH
    AUTH --> AX
    AX --> IDENTITY
    IDENTITY --> POLICY
    POLICY --> ACCESS

    classDef user fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef auth fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef policy fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef result fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER user
    class AUTH,AX,IDENTITY auth
    class POLICY policy
    class ACCESS result

AuthX

Answers:

Who is this user?

DjangoPlay

Answers:

What is this user allowed to do in this application?

This distinction is fundamental to the integration architecture.

13. Secrets and Configuration

DjangoPlay and AuthX maintain their own service configuration.

DjangoPlay contains the configuration required to communicate with AuthX, while AuthX maintains its own service-side credentials and database configuration.

Conceptually:

text

DjangoPlay configuration
    │
    ├── AUTHX_BASE_URL
    ├── AUTHX_SERVICE_TOKEN
    └── AUTHX_TIMEOUT


AuthX configuration
    │
    ├── AUTHX_SERVICE_TOKEN
    ├── AUTHX database configuration
    └── AuthX cryptographic configuration

AuthX-specific secrets should remain under AuthX's own configuration boundary.

Secrets must never be committed to source control or exposed to client-side applications.

14. Environment Separation

The integration supports environment-specific AuthX configuration.

flowchart TD

    ENV["DjangoPlay Environment"]

    DEV["Development"]
    STAGING["Staging"]
    PROD["Production"]

    DEVAX["Development AuthX"]
    STAGEAX["Staging AuthX"]
    PRODAX["Production AuthX"]

    ENV --> DEV
    ENV --> STAGING
    ENV --> PROD

    DEV --> DEVAX
    STAGING --> STAGEAX
    PROD --> PRODAX

    classDef env fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class ENV,DEV,STAGING,PROD env
    class DEVAX,STAGEAX,PRODAX authx

The AuthX base URL and service credentials are supplied through the configuration for the active environment.

This prevents development configuration from being coupled to production infrastructure.

15. Failure Boundary

Because AuthX is a separate service, DjangoPlay treats communication with AuthX as an external service boundary.

flowchart LR

    DP["DjangoPlay"]

    CLIENT["AuthXClient"]

    NETWORK["HTTP / Network"]

    AX["AuthX"]

    DB["AuthX PostgreSQL"]

    DP --> CLIENT
    CLIENT --> NETWORK
    NETWORK --> AX
    AX --> DB

    FAIL["Integration Failure"]

    NETWORK -.-> FAIL
    AX -.-> FAIL
    DB -.-> FAIL

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef transport fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef failure fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class DP,CLIENT app
    class NETWORK transport
    class AX,DB authx
    class FAIL failure

Failures can occur at several boundaries:

Network connectivity
AuthX availability
Service authentication
Request validation
Identity operations
AuthX database operations

The integration layer provides a controlled boundary for handling these failures rather than allowing AuthX-specific exceptions and HTTP behavior to spread throughout the application.

16. Integration Design Principles

The DjangoPlay ↔ AuthX integration follows these principles:

Principle	Description
Identity Authority	AuthX owns authoritative identity information
Local Mirror	DjangoPlay maintains a local identity representation
Service Boundary	Communication occurs through `AuthXClient`
Service Authentication	Internal calls use `X-Service-Token`
Separation of Concerns	Authentication and application authorization remain separate
Application Ownership	DjangoPlay owns application/domain data
Credential Isolation	AuthX credentials remain within the AuthX boundary
Environment Isolation	AuthX configuration varies by environment
Centralized Integration	AuthX communication is not scattered across apps
Explicit Synchronization	Identity changes are synchronized into DjangoPlay

17. Integration Summary

The overall relationship can be summarized as:

text

                    USER
                     │
                     ▼
              DJANGOPLAY
                     │
          Authentication Flow
                     │
                     ▼
                AuthXClient
                     │
             HTTP + Service Token
                     │
                     ▼
                  AUTHX
                     │
              Identity Service
                     │
                     ▼
             AuthX PostgreSQL

Alongside the authoritative AuthX identity, DjangoPlay maintains:

text

AuthX Identity
      │
      ▼
DjangoPlay UserIdentity
      │
      ├── Application relationships
      ├── Profiles
      ├── Permissions
      └── Domain data

The resulting architecture keeps identity centralized in AuthX while application ownership remains within DjangoPlay.

For detailed implementation documentation, refer to the DjangoPlay authentication architecture and the AuthX service documentation.

#1. Integration Overview

#Architectural principle

#2. Responsibility Boundary

#DjangoPlay owns

#AuthX owns

#3. Identity Architecture

#4. DjangoPlay Integration Components

#5. AuthX Client

#6. DjangoPlay → AuthX Communication

#7. Service Authentication

#8. Identity Creation Flow

#Design rule

#9. Identity Update Flow

#10. Identity Lookup

#11. Local UserIdentity Mirror

#12. Authentication and Authorization Boundary

#AuthX

#DjangoPlay

#13. Secrets and Configuration

#14. Environment Separation

#15. Failure Boundary

#16. Integration Design Principles

#17. Integration Summary

1. Integration Overview

Architectural principle

2. Responsibility Boundary

DjangoPlay owns

AuthX owns

3. Identity Architecture

4. DjangoPlay Integration Components

5. AuthX Client

6. DjangoPlay → AuthX Communication

7. Service Authentication

8. Identity Creation Flow

Design rule

9. Identity Update Flow

10. Identity Lookup

11. Local `UserIdentity` Mirror

12. Authentication and Authorization Boundary

AuthX

DjangoPlay

13. Secrets and Configuration

14. Environment Separation

15. Failure Boundary

16. Integration Design Principles

17. Integration Summary