97 lines
2.1 KiB
Markdown
97 lines
2.1 KiB
Markdown
# 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.
|