# SSO or social login

**Flow key:** `sso-social-login`

## Outcome

A user authenticates through the intended provider, maps to the correct local identity and tenant, and receives only authorized access.

## Actors

- User
- Application
- Identity provider
- Tenant administrator

## Preconditions and entry points

- Provider integration is configured in test mode.
- Synthetic IdP users cover existing/new/disabled and multi-tenant states.
- Redirect URIs and claim mappings are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Provider user | `carbon-sso-001` with stable subject | new, linked existing, changed email, missing email, disabled |
| Claims | subject, issuer, verified email, name, groups | missing, extra, stale group, Unicode, wrong audience/issuer |
| Tenant | tenant `carbon-lab` | multiple matching tenants, no tenant, deactivated tenant |
| Protocol state | fresh state/nonce/PKCE | missing, tampered, replayed, expired, parallel tabs |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Choose the configured SSO/social provider. | The app creates scoped state/nonce/PKCE and redirects only to the trusted provider. |
| 2 | Authenticate as the synthetic provider user. | Provider consent and requested scopes match the product need. |
| 3 | Return through the registered callback. | Issuer, signature, audience, nonce, state, time, and redirect target validate. |
| 4 | Map or provision the local identity. | Stable subject—not mutable display data—binds to exactly one user and tenant. |
| 5 | Apply roles/groups and create the session. | Least privilege and tenant isolation are enforced. |
| 6 | Repeat login and revoke/change provider state. | No duplicate identity appears; changed authorization converges under policy. |

## Alternate paths

- Just-in-time provisioning
- Pre-provisioned/SCIM user
- Account linking
- Multiple identity providers
- IdP-initiated login if explicitly supported

## Failure and recovery paths

- State/nonce replay
- Email collision links wrong account
- Provider returns malformed or stale claims
- Callback succeeds but provisioning fails
- Role/group removal lags

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [login](../../items/identity/login.md)
- [account and user lifecycle](../../items/identity/account-and-user-lifecycle.md)
- [tenant and organization isolation](../../items/identity/tenant-and-organization-isolation.md)
- [team membership role owner assignment](../../items/identity/team-membership-role-owner-assignment.md)

[Back to Identity and access flows](index.md)
