Skip to content

🔗 Centralized Authentication

The Aetoskia Auth Server acts as the single identity provider for every application in the Aetos Platform ecosystem. The model is deliberately small and uniform.

🧬 The identity model

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
            ┌─────────────────────────────────────┐
            │        Aetoskia Auth Server         │
            │  users collection (MongoDB)         │
            │  HS256 JWT issuer                   │
            └──────────────┬──────────────────────┘
                           │ /login → JWT
                           │ /introspect ← verification
        ┌──────────────────┼───────────────────┐
        │                  │                   │
   App A (FastAPI)    App B (service)    CLI/web clients
   verifies via       verifies via
   jwtlib / OpenAPI   jwtlib introspect
   dependency
  • One issuer. All access tokens are signed with the same JWT_SECRET using HS256 and carry sub (the username) plus an exp claim.
  • One user store. Users live in the shared MongoDB users collection; passwords are bcrypt-hashed and never leave the server.
  • Shared trust. Any service can validate a token locally with jwtlib (decode + signature) or ask the server via /introspect for a live answer.
  • No shared sessions. Logout is stateless: the token is discarded by the client, and further use is prevented only by expiry or revocation through introspection-driven policies.

🎟️ Token contract

A valid access token is an HS256 JWT with exactly two claims:

1
2
3
4
{
  "sub": "alice",
  "exp": 1750000000
}
  • sub — the username of the authenticated user.
  • exp — UTC epoch seconds of expiry (60 minutes by default).

There are no scopes or roles inside the token; authorization decisions belong to the consuming service, while identity and authenticity belong here.

🤝 How the ecosystem trusts the server

  1. Users authenticate once via /login and receive a token.
  2. Services accept that token as proof of identity after verifying it (locally via jwtlib or remotely via /introspect).
  3. Sensitive endpoints recover the user profile from the token through get_current_user or the generated dependency — never by parsing JWTs by hand.

This keeps authentication centralized while leaving each service in control of its own authorization rules.

💡 Benefits

  • New services onboard with a client library call, not a new auth system.
  • Credential storage, hashing, and issuance policies evolve in one place.
  • A single JWT_SECRET rotation strategy protects the whole platform.