1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Aetoskia Auth Server","text":"<p>The Aetoskia Auth Server is the central identity service of the Aetos Platform ecosystem. It issues, validates, and introspects short-lived JWT access tokens against a single shared user store backed by MongoDB, so every service can trust one issuer instead of shipping its own auth logic.</p>"},{"location":"#why-centralize-authentication","title":"Why centralize authentication?","text":"<ul> <li>Single source of identity \u2014 one user database, one issuer, one secret.</li> <li>Uniform token contract \u2014 every service verifies the same HS256 JWT.</li> <li>No auth code duplication \u2014 services delegate with <code>jwtlib</code> or a generated OpenAPI dependency.</li> <li>Instant revocation surface \u2014 introspection gives services a live <code>active</code> check rather than trusting expiry alone.</li> </ul>"},{"location":"#sections","title":"Sections","text":"Section What you'll find Centralized Auth The identity model and how the ecosystem trusts the server How to Use Register, login, and call endpoints with tokens Platform Integration How services authenticate requests Deployment Environment, Docker, and CI/CD Development Local setup, tests, and regenerating the spec"},{"location":"#endpoints-at-a-glance","title":"Endpoints at a glance","text":"Method Path Purpose POST <code>/register</code> Create a user account POST <code>/login</code> Authenticate and issue a JWT GET <code>/me</code> Current user (Bearer) POST <code>/logout</code> Stateless logout (Bearer) POST <code>/introspect</code> Service-to-service token verification GET <code>/health</code> Health check"},{"location":"#service-identity","title":"Service identity","text":"<ul> <li>Title: Aetoskia Auth Server</li> <li>Version: 0.0.5</li> <li>API spec: <code>docs/api/openapi.json</code> (rendered in the API reference site)</li> </ul>"},{"location":"01_centralized_auth/","title":"Centralized Authentication","text":"<p>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.</p>"},{"location":"01_centralized_auth/#the-identity-model","title":"The identity model","text":"<pre><code> \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 Aetoskia Auth Server \u2502\n \u2502 users collection (MongoDB) \u2502\n \u2502 HS256 JWT issuer \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 /login \u2192 JWT\n \u2502 /introspect \u2190 verification\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u2502 \u2502\n App A (FastAPI) App B (service) CLI/web clients\n verifies via verifies via\n jwtlib / OpenAPI jwtlib introspect\n dependency\n</code></pre> <ul> <li>One issuer. All access tokens are signed with the same <code>JWT_SECRET</code> using HS256 and carry <code>sub</code> (the username) plus an <code>exp</code> claim.</li> <li>One user store. Users live in the shared MongoDB <code>users</code> collection; passwords are bcrypt-hashed and never leave the server.</li> <li>Shared trust. Any service can validate a token locally with <code>jwtlib</code> (decode + signature) or ask the server via <code>/introspect</code> for a live answer.</li> <li>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.</li> </ul>"},{"location":"01_centralized_auth/#token-contract","title":"Token contract","text":"<p>A valid access token is an HS256 JWT with exactly two claims:</p> <pre><code>{\n \"sub\": \"alice\",\n \"exp\": 1750000000\n}\n</code></pre> <ul> <li><code>sub</code> \u2014 the username of the authenticated user.</li> <li><code>exp</code> \u2014 UTC epoch seconds of expiry (60 minutes by default).</li> </ul> <p>There are no scopes or roles inside the token; authorization decisions belong to the consuming service, while identity and authenticity belong here.</p>"},{"location":"01_centralized_auth/#how-the-ecosystem-trusts-the-server","title":"How the ecosystem trusts the server","text":"<ol> <li>Users authenticate once via <code>/login</code> and receive a token.</li> <li>Services accept that token as proof of identity after verifying it (locally via <code>jwtlib</code> or remotely via <code>/introspect</code>).</li> <li>Sensitive endpoints recover the user profile from the token through <code>get_current_user</code> or the generated dependency \u2014 never by parsing JWTs by hand.</li> </ol> <p>This keeps authentication centralized while leaving each service in control of its own authorization rules.</p>"},{"location":"01_centralized_auth/#benefits","title":"Benefits","text":"<ul> <li>New services onboard with a client library call, not a new auth system.</li> <li>Credential storage, hashing, and issuance policies evolve in one place.</li> <li>A single <code>JWT_SECRET</code> rotation strategy protects the whole platform.</li> </ul>"},{"location":"02_how_to_use/","title":"How to Use","text":"<p>This page covers the plain HTTP usage of the auth server: creating users, logging in, and calling protected endpoints with a bearer token.</p>"},{"location":"02_how_to_use/#register-a-user","title":"Register a user","text":"<pre><code>curl -X POST http://localhost:8000/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\": \"alice\", \"email\": \"alice@aetoskia.com\", \"password\": \"s3cret!\"}'\n</code></pre> <ul> <li><code>username</code> \u2014 3 to 50 characters (required).</li> <li><code>email</code> \u2014 valid email (optional).</li> <li><code>password</code> \u2014 at least 6 characters (required; stored hashed).</li> </ul> <p>Response <code>201 Created</code>:</p> <pre><code>{\n \"username\": \"alice\",\n \"email\": \"alice@aetoskia.com\",\n \"is_active\": true\n}\n</code></pre> <p>The password is never returned.</p>"},{"location":"02_how_to_use/#log-in-to-get-a-token","title":"Log in to get a token","text":"<pre><code>curl -X POST http://localhost:8000/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\": \"alice\", \"password\": \"s3cret!\"}'\n</code></pre> <p>Response <code>200 OK</code>:</p> <pre><code>{\n \"access_token\": \"<jwt>\",\n \"user\": {\n \"username\": \"alice\",\n \"email\": \"alice@aetoskia.com\",\n \"is_active\": true\n }\n}\n</code></pre> <p>Invalid credentials return <code>401</code> with <code>{\"detail\": \"Invalid credentials\"}</code>.</p>"},{"location":"02_how_to_use/#call-a-protected-endpoint","title":"Call a protected endpoint","text":"<p>Send the token as a bearer token:</p> <pre><code>curl http://localhost:8000/me \\\n -H \"Authorization: Bearer <jwt>\"\n</code></pre> <p>Response <code>200 OK</code> with the current user profile. A missing or invalid token returns <code>401</code> with <code>WWW-Authenticate: Bearer</code>.</p>"},{"location":"02_how_to_use/#log-out","title":"Log out","text":"<pre><code>curl -X POST http://localhost:8000/logout \\\n -H \"Authorization: Bearer <jwt>\"\n</code></pre> <p>Logout is stateless \u2014 the server returns a confirmation and the client must discard the token:</p> <pre><code>{ \"message\": \"Successfully logged out. Please discard your token on the client.\" }\n</code></pre>"},{"location":"02_how_to_use/#token-lifecycle-quick-reference","title":"Token lifecycle quick reference","text":"Event Endpoint Result Create identity <code>POST /register</code> user profile Obtain token <code>POST /login</code> <code>access_token</code> + user Verify (self) <code>GET /me</code> user profile or <code>401</code> End session <code>POST /logout</code> discard-token confirmation Verify (other services) <code>POST /introspect</code> <code>active</code> + user <p>Interactive examples are available in the API Reference site (Swagger UI), rendered from <code>docs/api/openapi.json</code>.</p>"},{"location":"03_platform_integration/","title":"Platform Integration","text":"<p>This page is for service authors wiring authentication into Aetos applications. It covers both supported integration paths.</p>"},{"location":"03_platform_integration/#path-1-jwtlib-client-py-jwt","title":"Path 1: <code>jwtlib</code> client (<code>py-jwt</code>)","text":"<p>Services that depend on the <code>py-jwt</code> library can authenticate requests without an OpenAPI generator. Set the auth server base URL:</p> <pre><code>export JWT_SERVER=http://auth.aetoskia.com\n</code></pre> <p>Then verify incoming requests:</p> <pre><code>from jwtlib.introspection import authenticate_request\n\nauthorized = await authenticate_request(\n should_skip_authentication, # e.g. allow public paths\n method,\n path,\n authorization_token, # \"Bearer <jwt>\" or None\n)\n</code></pre> <p><code>authenticate_request</code> POSTs <code>{\"token\": \"<jwt>\"}</code> to <code>{JWT_SERVER}/introspect</code> (3 second timeout) and treats <code>{\"active\": true, \"user\": {...}}</code> as valid. Transport errors surface as <code>AuthServiceUnavailable</code>.</p> <p>For zero-request validation (offline token decode), <code>jwtlib</code> also exposes the token payload helpers used by the auth server itself \u2014 see the <code>py-jwt</code> documentation.</p>"},{"location":"03_platform_integration/#path-2-openapi-first-generated-dependencies","title":"Path 2: <code>openapi-first</code> generated dependencies","text":"<p>Services declared with an OpenAPI-first contract can generate their FastAPI dependencies from the spec. Declare a bearer security scheme pointing at the auth server:</p> <pre><code>securitySchemes:\n HTTPBearer:\n type: http\n scheme: bearer\n x-server-url: https://auth.aetoskia.com\n x-introspect-path: /introspect\n</code></pre> <p>The generated dependency then POSTs <code>{\"token\": token}</code> to the introspection path and returns the user on <code>active == true</code>, raising <code>401</code> on invalid or inactive tokens and <code>503</code> when the auth server is unreachable.</p>"},{"location":"03_platform_integration/#the-introspect-contract","title":"The <code>/introspect</code> contract","text":"Field Type Description request <code>token</code> (string) The JWT to verify response <code>active</code> (bool) Whether the token is valid and active response <code>user</code> (PublicUser | null) The profile when active <p>The endpoint always answers <code>200</code> \u2014 validity is expressed through <code>active</code>. <code>IntrospectResponse</code> never raises, so the caller can act on the tri-state (valid / invalid / user missing) without exception handling.</p>"},{"location":"03_platform_integration/#protecting-endpoints-in-fastapi","title":"Protecting endpoints in FastAPI","text":"<p>For first-party services, mount the auth router's dependency directly:</p> <pre><code>from fastapi import Depends\nfrom jwtlib import PublicUser\nfrom jwt import get_current_user\n\n@app.get(\"/profile\")\nasync def profile(current_user: PublicUser = Depends(get_current_user)):\n return current_user\n</code></pre>"},{"location":"03_platform_integration/#golden-rules","title":"Golden rules","text":"<ol> <li>Never trust an unverified token \u2014 always decode through <code>jwtlib</code> or introspect before handling the request.</li> <li>Treat <code>active: false</code> as unauthenticated, even if the JWT decodes.</li> <li>Do not implement your own JWT parsing \u2014 use a generated dependency or the <code>jwtlib</code> client so revocation and issuer changes stay centralized.</li> </ol>"},{"location":"04_deployment/","title":"Deployment","text":"<p>How the auth server is configured and shipped.</p>"},{"location":"04_deployment/#environment-variables","title":"Environment variables","text":"Variable Required Default Purpose <code>MONGO_HOST</code> yes \u2014 MongoDB host <code>MONGO_USER</code> no \u2014 MongoDB username <code>MONGO_PASS</code> no \u2014 MongoDB password <code>MONGO_PORT</code> no <code>27017</code> MongoDB port <code>MONGO_DB_NAME</code> no <code>auth</code> Database name <code>JWT_SECRET</code> no* <code>superstrongsecretkey</code> Token signing secret (*set in production!) <p>Credentials and the token secret live in the environment / Deploy secrets \u2014 see <code>.env.example</code> for the shape. <code>.env</code> is gitignored.</p>"},{"location":"04_deployment/#running-locally","title":"Running locally","text":"<pre><code>cp .env.example .env # fill in MONGO_HOST, JWT_SECRET\nuvicorn main:app --reload --port 8000\n</code></pre> <p>The health endpoint is available at <code>GET /health</code>.</p>"},{"location":"04_deployment/#container-image","title":"Container image","text":"<p>The <code>Dockerfile</code> is a multi-stage build on <code>python:3.13-slim</code>:</p> <ol> <li>Builder installs <code>requirements.txt</code> from the private pip index using build args <code>PIP_USERNAME</code>, <code>PIP_PASSWORD</code>, <code>PIP_REPO_URL</code>.</li> <li>Runtime copies Python 3.13 from the builder, installs <code>curl</code>, exposes port <code>8000</code>, and runs <code>uvicorn main:app</code>. A <code>HEALTHCHECK</code> curls <code>/health</code>.</li> </ol>"},{"location":"04_deployment/#cicd-drone","title":"CI/CD (Drone)","text":"<p><code>.drone.yml</code> ships on git tag events (arm64):</p> <ol> <li>Resolve the latest tag.</li> <li>Skip if the image already exists.</li> <li><code>docker build</code> with pip credentials (secrets) \u2192 <code>aetos/auth-server:$TAG</code> and <code>:latest</code>.</li> <li>Push to <code>$REGISTRY_HOST/aetos/auth-server:*</code>.</li> <li>Restart the running container <code>auth-server</code>.</li> </ol> <p>The deployed container runs with <code>--restart always</code>, maps host <code>9003</code> \u2192 <code>8000</code>, resolves <code>private-pi</code> to <code>192.168.1.111</code> for Mongo, and receives <code>MONGO_*</code> + <code>JWT_SECRET</code> from secrets.</p>"},{"location":"04_deployment/#environments","title":"Environments","text":"Environment Base URL Production <code>https://auth.aetoskia.com</code> Internal staging <code>http://server-pi:9002</code> Local development <code>http://localhost:8000</code>"},{"location":"05_development/","title":"Development","text":"<p>Working on the auth server itself.</p>"},{"location":"05_development/#repository-layout","title":"Repository layout","text":"Path Purpose <code>main.py</code> FastAPI app factory, environment wiring, lifespan, OpenAPI customization <code>jwt/</code> The auth routes package (<code>router</code>, <code>get_current_user</code>) <code>generate_spec.py</code> Regenerates the committed OpenAPI spec <code>docs/api/</code> API reference (Swagger UI embed + <code>openapi.json</code>) <code>docs/lib/</code> Generated library reference (docforge) <code>docs/wiki/</code> This hand-written wiki <code>tests/</code> Async route tests against an in-memory Mongo mock"},{"location":"05_development/#setup","title":"Setup","text":"<pre><code>python -m venv .venv\n.venv/Scripts/pip install -r requirements.txt\n</code></pre> <p>Dependencies are installed from the private pip index (see <code>requirements.txt</code> and the <code>Dockerfile</code>). Core runtime packages:</p> <ul> <li><code>py-jwt==0.0.4</code> \u2014 provides <code>jwtlib</code> (applications logic, models, security, introspection)</li> <li><code>mongo-ops==0.1.3</code> \u2014 MongoDB persistence layer</li> <li><code>fastapi</code>, <code>uvicorn</code>, <code>python-jose</code>, <code>passlib</code>, <code>bcrypt</code>, <code>pymongo</code></li> </ul>"},{"location":"05_development/#tests","title":"Tests","text":"<p>Run the suite (no network or Mongo required \u2014 an in-memory mock is used):</p> <pre><code>.venv/Scripts/pytest --asyncio-mode=auto\n</code></pre> <p>Coverage spans the full HTTP flow: register \u2192 login \u2192 wrong-password <code>401</code> \u2192 <code>/me</code> with and without a token \u2192 stateless logout.</p>"},{"location":"05_development/#regenerating-the-openapi-spec","title":"Regenerating the OpenAPI spec","text":"<p>The committed <code>docs/api/openapi.json</code> is produced offline:</p> <pre><code>set MONGO_HOST=127.0.0.1\npython generate_spec.py\n</code></pre> <p><code>MONGO_HOST</code> only needs to be set for the import; no connection is opened.</p>"},{"location":"05_development/#building-documentation-docforge","title":"Building documentation (docforge)","text":"<p>The site is generated by <code>docforge</code> and served per kind under <code>site/{kind}</code>:</p> <pre><code>doc-forge build \\\n --api --openapi-spec docs/api/openapi.json \\\n --mkdocs --wiki \\\n --module-is-source --module jwt \\\n --site-name \"Aetoskia Auth Server\"\n</code></pre> <ul> <li><code>--api</code> renders <code>openapi.json</code> with Swagger UI.</li> <li><code>--mkdocs</code> renders the library reference from <code>jwt</code> docstrings.</li> <li><code>--wiki</code> builds this wiki.</li> <li>Navigation layout is defined in <code>docforge.nav.yml</code>.</li> </ul> <p>Preview locally:</p> <pre><code>doc-forge serve --api\ndoc-forge serve --lib\ndoc-forge serve --wiki\n</code></pre>"}]} |