Skip to content

ConnectSoft Identity Platform Flows

Each flow below describes the target-state behavior from frontend to backend. Implementation-specific pages may refine endpoint names, but must preserve these responsibilities.

Shell Unauthenticated Startup

  1. User opens the Blazor Shell.
  2. Shell checks its local session/auth state.
  3. If no authenticated session exists, Shell renders public routes or starts login.
  4. Shell does not load protected MFE data until authentication succeeds.
  5. Protected API calls without a valid access token receive 401.

Shell Authenticated Startup

  1. Shell restores BFF cookie or token session.
  2. Shell loads user profile, tenant, roles, scopes, and MFA state.
  3. Shell exposes shared auth state to MFEs.
  4. MFEs render protected routes based on shared state.
  5. API access is still enforced by Gateway/backend.

Blazor WASM Authorization Code + PKCE Login

  1. Shell redirects the user to Authorization Server /connect/authorize.
  2. Request includes client_id, redirect_uri, scope, state, nonce, and PKCE challenge.
  3. Authorization Server authenticates the user locally or through federation.
  4. Authorization Server returns authorization code to Shell callback.
  5. Shell exchanges code and verifier at /connect/token.
  6. Authorization Server issues id_token, access_token, and optionally refresh_token.
  7. Shell stores access token only as permitted by the frontend security model and uses it for Gateway calls.

Failure paths: invalid redirect URI, missing PKCE, denied consent, failed MFA, invalid client, or account linking required.

Blazor Server or BFF Login

  1. Browser reaches Shell or BFF.
  2. Shell/BFF starts OIDC login with Authorization Server.
  3. Tokens are stored server-side.
  4. Browser receives HttpOnly/SameSite cookie.
  5. Shell and MFEs call APIs through BFF or Gateway.
  6. CSRF protection is required for cookie-authenticated write operations.

Local Registration

  1. User opens Identity Self-Service MFE.
  2. MFE calls Identity registration through Gateway or approved BFF route.
  3. Identity creates the local user in pending/active state according to policy.
  4. Identity sends email or phone confirmation when required.
  5. User confirms and then logs in through Authorization Server.
  6. Authorization Server issues platform tokens after successful login.

Registration does not issue platform access tokens by itself.

Email and Phone Confirmation

  1. Identity creates confirmation token and sends it through configured channel.
  2. User follows confirmation link or submits code.
  3. Identity validates the token/code.
  4. Identity updates user confirmation state.
  5. Authorization Server can include confirmed email/phone claims when allowed by requested scopes.

Local Password Login

  1. Authorization Server receives an interactive login or allowed password validation request.
  2. Authorization Server delegates credential verification to Identity.
  3. Identity validates password, lockout, status, and MFA requirement.
  4. If MFA is required, login pauses until MFA succeeds.
  5. Authorization Server issues tokens after all required checks pass.

Password Reset and Change Password

Password reset is self-service and starts unauthenticated with rate limiting. Identity validates reset tokens and updates credentials. Change password is authenticated and should require current password and, for sensitive environments, step-up MFA.

MFA Enrollment

  1. Authenticated user opens Identity Self-Service MFE.
  2. MFE requests MFA enrollment from Identity.
  3. Identity creates factor setup data, such as TOTP secret and recovery codes.
  4. User verifies the first challenge.
  5. Identity marks MFA enabled.
  6. Future token issuance can include stronger amr/acr after MFA is completed.

MFA Login Challenge

  1. Identity determines MFA is required after primary authentication.
  2. User completes TOTP, recovery code, passkey, or approved factor.
  3. Identity records successful MFA for the login transaction.
  4. Authorization Server emits amr/acr claims that reflect MFA.

Step-Up MFA

  1. User with an active session attempts a sensitive operation.
  2. Gateway or backend detects missing or insufficient MFA assurance.
  3. API returns mfa_required or Shell starts an authorization request with stronger acr_values.
  4. User completes MFA.
  5. Authorization Server issues a new token or session state with stronger assurance.
  6. Shell retries the sensitive operation.

Sensitive operations include admin client changes, MFA reset, payment/payout actions, tenant deletion, and privileged data export.

  1. Authorization Server evaluates client, scopes, and consent policy.
  2. If consent is required, the user is redirected to consent UI.
  3. User grants or denies requested scopes.
  4. Authorization Server records consent according to policy.
  5. Token issuance continues only after consent is granted.

UserInfo

  1. Client calls UserInfo with a valid access token.
  2. Authorization Server validates token and requested scopes.
  3. Authorization Server retrieves normalized claims from Identity.
  4. Response includes only claims allowed by granted scopes.

Refresh Token Rotation

  1. Access token expires or nears expiry.
  2. Shell/BFF calls /connect/token with grant_type=refresh_token.
  3. Authorization Server validates refresh token, client, session, and revocation state.
  4. Authorization Server issues new access token and rotates refresh token where configured.
  5. Reuse of an old refresh token is treated as suspicious.

Logout, Revocation, and Session Expiry

  1. User initiates logout from Shell.
  2. Shell redirects or calls Authorization Server logout endpoint.
  3. Authorization Server ends local session and revokes refresh tokens where applicable.
  4. Shell clears local auth state and notifies MFEs.
  5. Optional federated logout is attempted when configured.
  6. Existing JWT access tokens remain valid until expiry unless reference tokens or introspection are used.

API Gateway Protected Request

  1. MFE calls Gateway with Authorization: Bearer <access_token>.
  2. Gateway validates issuer, audience, signature, expiry, and route policy.
  3. Gateway resolves tenant from validated token/context.
  4. Gateway forwards request and trusted context to backend.
  5. Backend performs domain authorization and returns response.

Failures: 401 for invalid/missing token, 403 for insufficient policy, mfa_required for step-up.

Backend Domain Authorization

  1. Backend receives validated caller context.
  2. Backend maps claims to current user and tenant context.
  3. Backend checks ownership, tenant isolation, role, permission, and aggregate-specific rules.
  4. Backend records audit context for sensitive operations.

Identity Admin Flows

Identity Admin MFE calls Gateway-protected Identity admin APIs. Required policy is identity.admin, with step-up MFA for sensitive operations such as MFA reset, external link removal, role elevation, tenant membership changes, and account disablement.

Authorization Server Admin Flows

Authorization Server Admin MFE manages clients, scopes, consent policy, token lifetimes, federation providers, and signing key visibility where supported. Required policy is auth.admin, with step-up MFA for client secret rotation, signing key changes, and high-privilege client updates.

Social Federation: Google and Facebook

  1. User starts login at Authorization Server.
  2. User selects Google or Facebook.
  3. Authorization Server redirects to provider.
  4. Provider authenticates user and returns authorization response.
  5. Authorization Server validates provider response.
  6. Identity resolves existing external account link or starts account linking/JIT provisioning.
  7. Authorization Server issues ConnectSoft platform tokens.

Provider tokens are not forwarded to backend APIs.

Enterprise Federation: Keycloak, Entra ID, and AD FS

  1. Authorization Server selects enterprise provider by tenant, domain, user choice, or route.
  2. User authenticates through OIDC or SAML.
  3. Authorization Server validates response, issuer, audience, signature, nonce/state, and replay protections.
  4. Identity maps external subject and groups to internal user, roles, scopes, and tenant memberships.
  5. Authorization Server emits platform tokens.

LDAP and Active Directory

Supported patterns:

  • Identity performs LDAP bind for credential validation.
  • Identity syncs users/groups from LDAP/AD into its own store.
  • Keycloak, Entra ID, or AD FS bridges LDAP/AD, and Authorization Server federates to that provider.

Browsers and MFEs never connect directly to LDAP.

JIT Provisioning

  1. Federated user authenticates successfully.
  2. Identity cannot find an existing external link.
  3. Identity applies tenant and provider policy.
  4. Identity creates internal user, memberships, and external link when allowed.
  5. If policy requires approval or profile completion, login pauses with account_link_required or equivalent UX.

Account Linking and Unlinking

Account linking connects an external provider subject to an internal user. Linking requires proof of both accounts or an admin-approved workflow. Unlinking is blocked when it would remove the user's last valid login method unless an admin recovery policy exists.

Service-to-Service Client Credentials

  1. Service client authenticates to Authorization Server.
  2. Authorization Server validates client credentials or certificate.
  3. Authorization Server issues service access token with service scopes and client_id.
  4. API Gateway/backend validates service token and service policy.
  5. Backend applies service-level authorization and audit.

Mock Provider Development Flows

Mock social, enterprise, and LDAP providers must implement the same contracts as real providers:

  • deterministic external subject;
  • configurable email, name, tenant, groups, and MFA state;
  • failure modes for denied login, missing email, duplicate account, stale group, and account linking required.

Mock providers are development substitutes, not production assurance.