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.

Flow Overview

flowchart LR
    shell["Blazor Shell / BFF"] -->|"login / logout / token renewal"| auth["Authorization Server"]
    shell -->|"API calls"| gateway["API Gateway"]
    mfe["Microfrontends"] -->|"API calls via Shell/Gateway"| gateway

    auth -->|"internal identity contract"| identity["Identity Service"]
    auth -->|"federation protocol"| provider["External IdP / Enterprise IdP"]
    identity -->|"optional bind/sync"| ldap["LDAP / AD"]

    gateway -->|"trusted identity + tenant context"| backend["Backend Services"]
    backend -->|"domain authorization"| data["Domain Data"]

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant User
    participant Shell as Blazor Shell
    participant Auth as Authorization Server
    participant Identity as Identity Service
    participant Gateway as API Gateway
    participant Backend as Backend Service

    User->>Shell: Open protected route
    Shell->>Auth: /connect/authorize with state, nonce, PKCE challenge
    Auth->>Identity: Evaluate sign-in / retrieve normalized user state
    Identity-->>Auth: User, tenant, roles, claims, MFA requirement
    Auth-->>Shell: Authorization code
    Shell->>Auth: /connect/token with code + PKCE verifier
    Auth-->>Shell: id_token + access_token (+ refresh_token when allowed)
    Shell->>Gateway: API request with access_token
    Gateway->>Gateway: Validate token, route policy, tenant, MFA claims
    Gateway->>Backend: Forward request with trusted context
    Backend-->>Gateway: Domain response
    Gateway-->>Shell: API response

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant User
    participant Auth as Authorization Server
    participant Identity as Identity Service
    participant Mfa as MFA Factor

    User->>Auth: Submit username/password
    Auth->>Identity: EvaluateSignInAsync
    Identity-->>Auth: Credential/account result + MFA requirement
    alt MFA required
        Auth->>Identity: CreateMfaChallengeAsync
        Identity-->>Auth: Challenge continuation
        Auth-->>User: Prompt for MFA
        User->>Auth: Submit MFA proof
        Auth->>Identity: VerifyMfaChallengeAsync
        Identity->>Mfa: Verify factor when needed
        Mfa-->>Identity: Factor result
        Identity-->>Auth: MFA verified
    end
    Auth->>Identity: GetUserClaimsAsync
    Identity-->>Auth: Normalized claims and tenant memberships
    Auth-->>User: Platform tokens / session

Hold "Alt" / "Option" to enable pan & zoom

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.

Consent

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

sequenceDiagram
    autonumber
    participant Shell as Shell / BFF
    participant Auth as Authorization Server
    participant Identity as Identity Service

    Shell->>Auth: /connect/token grant_type=refresh_token
    Auth->>Auth: Validate refresh token, client, session, revocation
    opt Revalidate user state
        Auth->>Identity: GetUserClaimsAsync / user state check
        Identity-->>Auth: Current claims, status, security stamp
    end
    Auth-->>Shell: New access token and rotated refresh token

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant User
    participant Shell
    participant Auth as Authorization Server
    participant Provider as Federated Provider
    participant MFE as Microfrontends

    User->>Shell: Logout
    Shell->>Auth: Logout / revocation request
    Auth->>Auth: End local session and revoke refresh tokens when configured
    opt Federated logout configured
        Auth->>Provider: Federated logout
        Provider-->>Auth: Logout response
    end
    Auth-->>Shell: Logout complete
    Shell->>MFE: Clear shared auth state

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant MFE as Shell / MFE
    participant Gateway as API Gateway
    participant Backend as Backend Service

    MFE->>Gateway: Request with Bearer access_token
    Gateway->>Gateway: Validate issuer, audience, signature, expiry
    Gateway->>Gateway: Evaluate route policy, tenant, scopes, roles, MFA
    Gateway->>Gateway: Strip spoofed trusted headers
    Gateway->>Backend: Forward with trusted identity, tenant, correlation headers
    Backend->>Backend: Enforce tenant isolation and resource authorization
    Backend-->>Gateway: Domain response
    Gateway-->>MFE: API response or ProblemDetails

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant User
    participant Auth as Authorization Server
    participant Provider as Google / Facebook
    participant Identity as Identity Service

    User->>Auth: Start login and choose provider
    Auth->>Provider: Authorization request
    Provider-->>Auth: Authorization response / external identity
    Auth->>Auth: Validate state, nonce, issuer, audience, signature
    Auth->>Identity: ResolveFederatedLoginAsync
    alt Link exists
        Identity-->>Auth: Internal user and normalized claims source
    else JIT/linking allowed
        Identity->>Identity: Create user, memberships, external link
        Identity-->>Auth: Internal user and normalized claims source
    else Approval/profile completion required
        Identity-->>Auth: account_link_required
    end
    Auth-->>User: Platform tokens or linking UX

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant User
    participant Auth as Authorization Server
    participant Provider as Keycloak / Entra ID / AD FS
    participant Identity as Identity Service

    User->>Auth: Start tenant/domain-specific login
    Auth->>Provider: OIDC or SAML request
    Provider-->>Auth: Enterprise identity response
    Auth->>Auth: Validate issuer, audience, signature, nonce/state, replay protection
    Auth->>Identity: ResolveFederatedLoginAsync with subject/groups
    Identity->>Identity: Map groups to roles, scopes, tenant memberships
    Identity-->>Auth: Internal user and normalized claims
    Auth-->>User: Platform tokens

Hold "Alt" / "Option" to enable pan & zoom

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

flowchart TB
    browser["Browser / MFE"] -. "not allowed: never direct" .-> ldap["LDAP / AD"]

    auth["Authorization Server"] -->|"delegates local sign-in"| identity["Identity Service"]
    identity -->|"LDAP bind pattern"| ldap
    identity -->|"sync users/groups pattern"| identityStore["Identity Store"]

    auth -->|"federation bridge pattern"| bridge["Keycloak / Entra ID / AD FS"]
    bridge -->|"directory integration"| ldap

Hold "Alt" / "Option" to enable pan & zoom

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

sequenceDiagram
    autonumber
    participant Client as Service Client
    participant Auth as Authorization Server
    participant Gateway as API Gateway
    participant Backend as Backend Service

    Client->>Auth: Client credentials or certificate
    Auth->>Auth: Validate client, secret/cert, scopes
    Auth-->>Client: Service access token with client_id and scopes
    Client->>Gateway: API request with service token
    Gateway->>Gateway: Validate token and service policy
    Gateway->>Backend: Forward trusted client context
    Backend->>Backend: Enforce service-level authorization and audit
    Backend-->>Gateway: Domain response
    Gateway-->>Client: API response

Hold "Alt" / "Option" to enable pan & zoom

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.