--- since: 1.1.1 --- # AuthX — OIDC API AuthX exposes an OpenID Connect–oriented API surface for authentication, token issuance, token refresh, identity discovery, and local JWT verification. The OIDC endpoints form the public authentication boundary of AuthX. Trusted backend identity-management operations are exposed separately through the Internal Identity API and are not part of this interface. --- ## 1. OIDC Architecture ```mermaid flowchart TD CLIENT["Client Application
Web / Backend Consumer"] DISCOVERY["OIDC Discovery
/.well-known/openid-configuration"] TOKEN["Token Endpoint
/token"] REFRESH["Refresh Endpoint
/token/refresh"] USERINFO["UserInfo Endpoint
/userinfo"] JWKS["JWKS Endpoint
/jwks"] AUTHX["AuthX
Identity & Token Service"] DB[("PostgreSQL
Identity Store")] KEY["RSA Signing Key
RS256"] CLIENT --> DISCOVERY CLIENT --> TOKEN CLIENT --> REFRESH CLIENT --> USERINFO CLIENT --> JWKS DISCOVERY --> AUTHX TOKEN --> AUTHX REFRESH --> AUTHX USERINFO --> AUTHX JWKS --> KEY AUTHX --> DB AUTHX --> KEY classDef client fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a classDef endpoint fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444 classDef auth fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c classDef db fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef key fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 class CLIENT client class DISCOVERY,TOKEN,REFRESH,USERINFO,JWKS endpoint class AUTHX auth class DB db class KEY key ```` The main OIDC flow is: ```text Client │ ├── Discovery ───────────────► AuthX │ ├── Credentials ─────────────► /token │ │ │ ▼ │ Access Token │ Refresh Token │ ├── Refresh Token ───────────► /token/refresh │ │ │ ▼ │ New Token Pair │ ├── Access Token ────────────► /userinfo │ └── JWKS ────────────────────► /jwks │ ▼ Public Key ``` --- # 2. Discovery The OIDC discovery endpoint is: ```http GET /.well-known/openid-configuration ``` The discovery document describes the AuthX OIDC configuration and exposes the locations and capabilities required by compatible consumers. The response contains information including: ```text issuer token_endpoint userinfo_endpoint jwks_uri response_types_supported subject_types_supported id_token_signing_alg_values_supported scopes_supported grant_types_supported ``` --- ## 2.1 Current Advertised Capabilities The current implementation advertises: ```text response_types_supported ["token"] subject_types_supported ["public"] scopes_supported ["openid", "email", "profile"] grant_types_supported ["password", "refresh_token"] ``` These values describe the currently supported authentication/token interface. Consumers should use the discovery document as the authoritative source for the endpoint locations and advertised capabilities of a deployed AuthX instance. --- # 3. Issuer The discovery document exposes the configured AuthX issuer: ```text issuer ``` The issuer identifies the AuthX deployment that issues JWTs. JWT consumers should validate the issuer claim against their configured expected AuthX issuer. The issuer is configured through: ```text JWT_ISSUER ``` Production deployments should use an HTTPS issuer. Example: ```text JWT_ISSUER=https://auth.example.com ``` The issuer must be an HTTP(S) URL without a query string or fragment. --- # 4. JWKS AuthX exposes its public signing keys through: ```http GET /jwks ``` The endpoint returns a JSON Web Key Set containing the public RSA key used to verify AuthX-signed JWTs. The private signing key is never exposed through this endpoint. ```mermaid flowchart LR AUTHX["AuthX"] PRIVATE["RSA Private Key
Signing only"] JWT["Signed JWT
RS256"] JWKS["/jwks
Public JWK Set"] PUBLIC["RSA Public Key"] CONSUMER["JWT Consumer"] AUTHX --> PRIVATE PRIVATE -->|"sign"| JWT AUTHX --> JWKS JWKS --> PUBLIC PUBLIC --> CONSUMER JWT -->|"verify signature"| CONSUMER classDef auth fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c classDef key fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91 classDef token fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b classDef consumer fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a class AUTHX auth class PRIVATE,PUBLIC,JWKS key class JWT token class CONSUMER consumer ``` Consumers can cache the JWKS and perform JWT signature verification locally. --- ## 4.1 Current Key Metadata The current signing key metadata includes: ```text kty = RSA use = sig alg = RS256 kid = authx-key-1 ``` The `kid` allows consumers to select the appropriate public key when multiple keys are present in a JWKS document. --- # 5. Token Endpoint The token endpoint is: ```http POST /token Content-Type: application/json ``` The current implementation supports the password grant. --- ## 5.1 Password Grant Request: ```json { "grant_type": "password", "email": "user@example.com", "password": "..." } ``` AuthX validates the supplied credentials against the authoritative identity store. A successful authentication produces an access token and refresh token. Example response: ```json { "access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 3600 } ``` --- ## 5.2 Authentication Flow ```mermaid sequenceDiagram participant C as Client participant A as AuthX participant DB as PostgreSQL C->>A: POST /token A->>DB: Resolve identity DB-->>A: Identity + credential state A->>A: Validate credentials A->>A: Create access JWT A->>A: Create refresh JWT A->>DB: Persist refresh-token state A-->>C: Access + refresh tokens ``` The access token is intended for authenticated API operations. The refresh token is associated with server-side refresh-token state so that AuthX can perform rotation and revocation. --- # 6. Invalid Credentials Invalid authentication credentials result in: ```text HTTP 401 Unauthorized ``` The client must not interpret an authentication failure as an internal service failure. --- # 7. Access Tokens AuthX issues signed JWT access tokens. The access token is: ```text JWT + RS256 signature ``` The JWT contains identity and token metadata required by consumers. Current access-token claims include: ```text sub iss aud iat exp jti type = access email username is_verified is_staff is_superuser ``` The access token is intended to be validated by the consuming application. Consumers should validate at minimum: ```text Signature Issuer Audience Expiration Token type ``` where applicable to the consuming application's authentication policy. --- # 8. Refresh Tokens Refresh tokens are issued together with access tokens. A refresh request is sent to: ```http POST /token/refresh Content-Type: application/json ``` Request: ```json { "refresh_token": "..." } ``` The refresh token contains: ```text sub iss aud iat exp jti type = refresh ``` --- # 9. Refresh Token Rotation AuthX uses refresh-token rotation. When a valid refresh token is presented: ```text Existing refresh token │ ▼ Validate token │ ▼ Revoke presented token │ ▼ Issue new access token │ ▼ Issue new refresh token ``` The presented refresh token is marked revoked before the replacement token pair is issued. This makes refresh tokens stateful from the server's perspective even though the token itself is a JWT. --- ## 9.1 Refresh Flow ```mermaid sequenceDiagram participant C as Client participant A as AuthX participant DB as PostgreSQL C->>A: POST /token/refresh A->>A: Validate refresh JWT A->>DB: Check JTI / revocation state DB-->>A: Refresh token state A->>DB: Revoke presented token A->>A: Create new access JWT A->>A: Create new refresh JWT A->>DB: Persist new refresh-token state A-->>C: New access + refresh tokens ``` A previously rotated refresh token must not be reused as a valid refresh credential. --- # 10. UserInfo The UserInfo endpoint is: ```http GET /userinfo Authorization: Bearer ``` The endpoint requires a valid AuthX access token. Example response: ```json { "sub": "", "email": "user@example.com", "email_verified": true, "preferred_username": "user" } ``` The `sub` value identifies the AuthX identity. Consumers should use `sub` as the stable identity identifier rather than treating email as the primary immutable identity key. --- # 11. UserInfo Request Flow ```mermaid sequenceDiagram participant C as Client participant A as AuthX C->>A: GET /userinfo Note over C,A: Authorization: Bearer A->>A: Validate JWT A->>A: Resolve identity A-->>C: UserInfo response ``` --- # 12. Endpoint Summary | Endpoint | Method | Purpose | | ----------------------------------- | ------ | --------------------------------------------- | | `/.well-known/openid-configuration` | `GET` | OIDC discovery | | `/jwks` | `GET` | Public JWT verification keys | | `/token` | `POST` | Obtain access/refresh tokens | | `/token/refresh` | `POST` | Rotate refresh token and issue new token pair | | `/userinfo` | `GET` | Retrieve authenticated identity information | --- # 13. Public OIDC vs Internal API AuthX separates public authentication operations from trusted backend identity management. ```text AuthX │ ┌───────────┴───────────┐ │ │ ▼ ▼ Public OIDC Internal API │ │ │ │ X-Service-Token ▼ ▼ Clients Trusted Backends │ │ ▼ ▼ Token / UserInfo Identity Management Discovery / JWKS Create / Read / Update ``` The public OIDC surface is intended for authentication and token consumption. The Internal Identity API is intended for trusted backend applications such as DjangoPlay. --- # 14. JWT Verification by Consumers A consumer does not need access to the AuthX private signing key. The recommended model is: ```text AuthX │ ├── Private RSA key │ │ │ └── signs JWT │ └── /jwks │ └── exposes public key │ ▼ JWT Consumer │ └── verifies signature ``` A Django consumer such as DjangoPlay can therefore validate AuthX JWTs without making AuthX part of every authenticated API request. --- # 15. Security Considerations The following principles apply to the OIDC API: 1. AuthX retains the JWT signing private key. 2. Consumers receive only public verification keys. 3. Consumers should validate issuer and audience. 4. Access tokens should be treated as bearer credentials. 5. Refresh tokens must be protected as sensitive credentials. 6. Refresh-token rotation and revocation state are maintained by AuthX. 7. Credentials supplied to `/token` must only be transmitted over HTTPS in production. 8. The Internal Identity API must not be confused with the public OIDC API. --- # 16. Summary The AuthX OIDC API provides the public authentication and token interface for the identity platform. Its current capabilities are: | Capability | Implementation | | ----------------------- | ----------------------------------- | | Discovery | `/.well-known/openid-configuration` | | Token issuance | `/token` | | Grant | `password` | | Token refresh | `/token/refresh` | | Refresh rotation | Enabled | | User information | `/userinfo` | | Public key distribution | `/jwks` | | JWT algorithm | RS256 | | Key type | RSA | | Subject type | Public | | Scopes | `openid`, `email`, `profile` | | Identity authority | AuthX | The architectural boundary is straightforward: > **AuthX authenticates identities and issues signed tokens; consumers verify > those tokens using AuthX's published public keys.**