---
since: 1.1.1
---
# **AuthX — Trust Boundaries**
---
## **1. Overview**
AuthX separates authentication responsibilities through explicit trust boundaries.
The boundaries define which components are considered untrusted, which operations require backend authentication, and where sensitive credentials or cryptographic material are allowed to exist.
The primary boundaries are:
1. Public client → AuthX
2. Trusted backend → AuthX
3. AuthX → PostgreSQL
4. AuthX → JWT consumers
5. Django application → AuthX integration layer
These boundaries are important because authentication-related responsibilities should not leak across system boundaries.
---
# **2. Trust Model**
At a high level:
```mermaid
flowchart TD
CLIENT["Public Client
Browser / Application"]
AUTHX["AuthX
Identity Service"]
INTERNAL["Trusted Backend
Service Consumer"]
DB["PostgreSQL
AuthX Persistence"]
CONSUMER["JWT Consumer
Django / API Service"]
CLIENT -->|"Public authentication endpoints"| AUTHX
INTERNAL -->|"X-Service-Token
Internal API"| AUTHX
AUTHX -->|"Database credentials"| DB
AUTHX -->|"Signed JWT
Public verification key"| CONSUMER
classDef untrusted fill:#fff4e6,stroke:#d97706,stroke-width:2px,color:#7c2d12
classDef trusted fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef authx fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e
classDef database fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#374151
class CLIENT untrusted
class INTERNAL,CONSUMER trusted
class AUTHX authx
class DB database
```
The important distinction is between **public authentication operations** and **privileged internal identity operations**.
---
# **3. Boundary 1 — Public Client → AuthX**
Public clients are considered **untrusted**.
```text
UNTRUSTED CLIENT
│
│ Public authentication request
▼
┌─────────────────────┐
│ AuthX │
│ │
│ Public OIDC/Auth │
│ Endpoints │
└─────────────────────┘
```
Public clients may interact with the authentication endpoints exposed for normal user authentication.
Typical operations include:
* Login
* Signup
* Authentication flows
* Token acquisition
* Public identity operations exposed by AuthX
The client must **not** be trusted simply because it successfully reaches an AuthX endpoint.
### Trust rule
```text
Public client
≠
Trusted backend
```
A public authentication request must not provide access to privileged internal identity-management operations.
---
# **4. Boundary 2 — Trusted Backend → AuthX**
Backend consumers operate across a separate trust boundary.
```text
TRUSTED BACKEND
│
│ X-Service-Token
▼
┌─────────────────────┐
│ AuthX │
│ │
│ /internal/* │
└─────────────────────┘
```
Internal AuthX endpoints require a service-level authentication mechanism.
The `X-Service-Token` is intended for trusted backend services rather than browser clients.
### Trust requirements
The service token should:
* Remain server-side.
* Never be embedded in frontend code.
* Never be exposed to browser clients.
* Never be committed to source control.
* Be supplied through protected configuration.
* Be rotated when necessary.
The internal API therefore establishes a stronger trust boundary than the public authentication API.
---
# **5. Public vs Internal API Boundary**
The distinction can be represented as:
```mermaid
flowchart LR
PUBLIC["Public Client
UNTRUSTED"]
BACKEND["Backend Service
TRUSTED"]
PUBLIC -->|"Public authentication APIs"| AUTHX["AuthX"]
BACKEND -->|"X-Service-Token"| INTERNAL["AuthX /internal/*"]
INTERNAL --> AUTHX
classDef untrusted fill:#fff4e6,stroke:#d97706,stroke-width:2px,color:#7c2d12
classDef trusted fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef service fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e
class PUBLIC untrusted
class BACKEND trusted
class AUTHX,INTERNAL service
```
This prevents the public authentication surface from becoming an implicit identity-administration interface.
---
# **6. Boundary 3 — AuthX → PostgreSQL**
The AuthX runtime is trusted to access its persistence layer.
```text
┌───────────────┐
│ AuthX │
│ Runtime │
└───────┬───────┘
│
│ Database credentials
▼
┌───────────────┐
│ PostgreSQL │
│ │
│ Identity Data │
│ Token State │
└───────────────┘
```
Database credentials belong only to the AuthX runtime.
Neither:
* Public clients
* Browser applications
* JWT consumers
* External API consumers
should have direct access to the AuthX PostgreSQL database.
The database is therefore behind the AuthX application boundary.
---
# **7. Database Trust Boundary**
The intended relationship is:
```mermaid
flowchart TD
CLIENT["Public Client"]
BACKEND["Backend Consumer"]
AUTHX["AuthX Runtime"]
DB["PostgreSQL
Identity + Token Persistence"]
CLIENT -. "No direct access" .-> DB
BACKEND -. "No direct access" .-> DB
AUTHX -->|"Private DB connection"| DB
classDef untrusted fill:#fff4e6,stroke:#d97706,stroke-width:2px,color:#7c2d12
classDef trusted fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef database fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#374151
class CLIENT untrusted
class BACKEND,AUTHX trusted
class DB database
```
Application consumers should use AuthX's supported API boundaries rather than connecting directly to its database.
---
# **8. Boundary 4 — JWT Signing and Verification**
JWT signing creates a separate cryptographic trust boundary.
```text
AuthX
│
│ Private signing key
▼
JWT Signing
│
▼
Signed JWT
│
▼
Consumer Application
│
│ Public key
▼
JWT Verification
```
AuthX holds the **private signing key**.
JWT consumers require only the corresponding **public verification key**.
### Critical rule
```text
Signing Private Key
│
└── AuthX only
Verification Public Key
│
└── JWT consumers
```
A consumer must never require the private signing key merely to validate a JWT.
---
# **9. Cryptographic Trust Boundary**
```mermaid
flowchart LR
AUTHX["AuthX
JWT Authority"]
PRIVATE["Private Signing Key"]
JWT["Signed JWT"]
CONSUMER["JWT Consumer"]
PUBLIC["Public Verification Key"]
AUTHX --> PRIVATE
PRIVATE --> JWT
JWT --> CONSUMER
PUBLIC --> CONSUMER
classDef authority fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e
classDef secret fill:#fff1f2,stroke:#be123c,stroke-width:2px,color:#881337
classDef token fill:#f5f3ed,stroke:#777,stroke-width:2px,color:#444
classDef consumer fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
class AUTHX authority
class PRIVATE secret
class JWT token
class CONSUMER,PUBLIC consumer
```
The private key is a high-value secret and must be protected accordingly.
---
# **10. Boundary 5 — DjangoPlay → AuthX**
DjangoPlay integrates with AuthX through two conceptually different mechanisms.
```text
DjangoPlay
│
┌───────────┴───────────┐
│ │
▼ ▼
AuthXClient AuthXJWT
│ │
│ HTTP │ Local verification
▼ ▼
AuthX JWT validation
```
### `AuthXClient`
`AuthXClient` handles HTTP-based identity operations between DjangoPlay and AuthX.
It is used when DjangoPlay needs to communicate with the identity service.
### `AuthXJWT`
`AuthXJWT` handles JWT validation within the consuming application.
This allows DjangoPlay to validate authentication credentials without implementing AuthX's identity persistence or password-management mechanisms itself.
---
# **11. Responsibility Boundary**
DjangoPlay should not duplicate AuthX's identity authority.
```mermaid
flowchart TD
DJANGO["DjangoPlay"]
CLIENT["AuthXClient"]
JWT["AuthXJWT"]
AUTHX["AuthX
Identity Authority"]
DB["AuthX Database"]
DJANGO --> CLIENT
DJANGO --> JWT
CLIENT -->|"Identity operations"| AUTHX
JWT -->|"Validate signed JWT"| AUTHX
AUTHX --> DB
classDef django fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef integration fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a
classDef authx fill:#e8eaf6,stroke:#3949ab,stroke-width:2px,color:#1a237e
classDef database fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#374151
class DJANGO django
class CLIENT,JWT integration
class AUTHX authx
class DB database
```
The consuming Django application should **not** independently implement:
* AuthX password hashing
* AuthX identity persistence
* AuthX refresh-token persistence
* AuthX identity-management semantics
Those responsibilities belong to AuthX.
---
# **12. Trust Boundary Summary**
| Boundary | Source | Destination | Trust Mechanism |
| --------------------- | --------------- | ------------ | --------------------------------------------- |
| Public authentication | Public client | AuthX | Public authentication endpoints |
| Internal API | Backend service | AuthX | `X-Service-Token` |
| Persistence | AuthX | PostgreSQL | Private database credentials |
| JWT signing | AuthX | JWT consumer | Private signing key / public verification key |
| Django integration | DjangoPlay | AuthX | `AuthXClient` / `AuthXJWT` |
---
# **13. Security Principles**
The trust-boundary design follows several important principles:
### **Least Privilege**
A component receives only the credentials and access required for its responsibility.
### **Server-Side Secrets**
Service tokens, database credentials, and private signing keys remain server-side.
### **Cryptographic Key Separation**
JWT consumers receive verification capability, not signing capability.
### **Identity Authority Separation**
AuthX remains responsible for identity persistence and authentication authority.
### **API Boundary Enforcement**
Public clients and trusted backend services use different access paths.
### **Database Isolation**
Consumers interact with identity data through AuthX rather than directly accessing its database.
---
# **14. Summary**
AuthX establishes explicit trust boundaries between public clients, trusted backend services, persistent identity data, JWT consumers, and integrating Django applications.
The most important boundary is the distinction between:
```text
Public Client
│
▼
Public AuthX API
```
and:
```text
Trusted Backend
│
│ X-Service-Token
▼
AuthX Internal API
```
Similarly, cryptographic trust is separated so that:
```text
AuthX
│
└── Private signing key
Consumer
│
└── Public verification key
```
This keeps identity authority, privileged backend operations, database access, and JWT signing responsibilities separated across well-defined security boundaries.