init push

docs/AUTH_SSO_FLOW.md

@@ -0,0 +1,96 @@
+# AUTH SSO FLOW (Frontend)
+
+## 1) New SSO Login Flow
+1. Frontend calls `GET /api/v1/auth/microsoft/login`.
+2. Redirect user to `data.attributes.url`.
+3. Provider redirects to backend callback `GET /api/v1/auth/microsoft/callback?code=...&state=...`.
+4. Backend checks existing SSO mapping (`provider=microsoft` + `provider_subject`).
+5. Result:
+- Mapping + user exists: login success, cookies/session issued.
+- Mapping not found: login rejected (`401`).
+- Mapping exists but user missing: login rejected (`404`).
+
+## 2) Important Rule
+SSO **does not create new account automatically**. User must already exist and be linked first.
+
+## 3) Link SSO (for logged-in existing user)
+Endpoint: `POST /api/v1/auth/sso/link`
+
+Auth: required (same auth cookie/session as normal login).
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_sso_link",
+    "attributes": {
+      "provider": "microsoft",
+      "code": "<microsoft_authorization_code>"
+    }
+  }
+}
+```
+
+Success `200`:
+```json
+{
+  "data": {
+    "type": "auth_sso_link",
+    "attributes": {
+      "provider": "microsoft",
+      "provider_subject": "00000000-0000-0000-0000-000000000000",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+## 4) Unlink SSO
+Endpoint: `DELETE /api/v1/auth/sso/unlink`
+
+Auth: required.
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_sso_unlink",
+    "attributes": {
+      "provider": "microsoft"
+    }
+  }
+}
+```
+
+Success `200`:
+```json
+{
+  "data": {
+    "type": "auth_sso_unlink",
+    "attributes": {
+      "provider": "microsoft",
+      "unlinked": true
+    }
+  }
+}
+```
+
+## 5) Endpoint Summary
+- `GET /api/v1/auth/microsoft/login`
+- `GET /api/v1/auth/microsoft/callback`
+- `POST /api/v1/auth/sso/link`
+- `DELETE /api/v1/auth/sso/unlink`
+
+## 6) Error Handling (Frontend)
+Handle these API errors explicitly:
+- `401 Unauthorized`
+- `403 Forbidden`
+- `404 user not found`
+- `401 sso not linked`
+- `409 sso already linked`
+- `409 sso linked to another user`
+
+Recommended behavior:
+- `401 sso not linked`: show message to login manually first, then link SSO in account settings.
+- `409` errors on link: inform user mapping conflict and stop retry loop.
+- `404 user not found`: force logout and ask user to re-authenticate.