fm_be/docs/AUTH_SSO_FLOW.md

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:

{
  "data": {
    "type": "auth_sso_link",
    "attributes": {
      "provider": "microsoft",
      "code": "<microsoft_authorization_code>"
    }
  }
}

Success 200:

{
  "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:

{
  "data": {
    "type": "auth_sso_unlink",
    "attributes": {
      "provider": "microsoft"
    }
  }
}

Success 200:

{
  "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.