Sovereign Authentication & Authorization Flows

1. OpenIddict as Sovereign Identity Provider (IdP)

The GERCIA Platform operates OpenIddict running natively inside Gercia.Api as its sole central authority for identity, authorization, and token issuance. It eliminates third-party Identity-as-a-Service (BaaS) vendor lock-in, ensures zero-trust internal token validation, and maintains 100% data residency compliance under LGPD and CFM regulations.

---

2. The 4 Authentication Flows

Flow A: Internal GERCIA Staff (ops.gercia.com.br)

sequenceDiagram
    autonumber
    actor Dev as GERCIA Staff Member
    participant Web as Gercia.Web (ops.gercia.com.br)
    participant Google as Google Workspace OIDC
    participant API as Gercia.Api (OpenIddict STS)
    participant DB as PostgreSQL (core.users)

    Dev->>Web: Accesses ops.gercia.com.br
    Web->>Google: Auto-redirect (HTTP 302) with hd=gercia.com.br
    Dev->>Google: Authenticates with corporate @gercia.com.br account
    Google-->>Web: Returns OIDC Authorization Code & ID Token
    Web->>API: Validates Google token & resolves User in core.users
    API->>DB: Checks internal role (Operator / Admin)
    API-->>Web: Issues encrypted HttpOnly session cookie (SameSite=Strict)
    Web-->>Dev: Grants instant access to Operations backoffice

---

Flow B: B2B Multi-Tenant Clients (app.gercia.com.br)

sequenceDiagram
    autonumber
    actor User as Doctor / Pharmacist
    participant Web as Gercia.Web (app.gercia.com.br)
    participant API as Gercia.Api (OpenIddict STS)
    participant DB as PostgreSQL (core.users / tenant_user_accesses)

    User->>Web: Submits Email + Password (or selects Enterprise SSO)
    Web->>API: POST /connect/token (Authorization Code Flow with PKCE)
    API->>DB: Verifies Argon2id password hash & TOTP 2FA
    API->>DB: Resolves accessible tenants (TenantId, BranchId, Roles)
    API-->>Web: Issues secure session cookie with tenant claims
    Web-->>User: Renders tenant-scoped dashboard

---

Flow C: Mobile Patients (Gercia.Health.Mobile)

sequenceDiagram
    autonumber
    actor Patient as Mobile Patient
    participant App as GERCIA Saúde (MAUI)
    participant Social as Google / Apple Identity
    participant API as Gercia.Api (/connect/token)
    participant DB as PostgreSQL (core.user_logins)

    Patient->>App: Clicks "Sign in with Google / Apple"
    App->>Social: Prompts biometric authentication on smartphone
    Social-->>App: Returns signed id_token
    App->>API: POST /connect/token (grant_type=social_token, id_token=...)
    API->>API: Validates token signature via native C# (Google.Apis.Auth)
    API->>DB: Finds or provisions User in core.users & core.user_logins
    API-->>App: Emits Access Token (15 min) + Refresh Token (30 days)
    App->>App: Stores in hardware SecureStorage (Keychain / Keystore)

---

Flow D: Hardware Station Agents (Gercia.Edge)

sequenceDiagram
    autonumber
    actor Edge as Gercia.Edge Agent (Pharmacy Station)
    participant API as Gercia.Api (SignalR Hubs)
    participant DB as PostgreSQL (core.tenants)

    Edge->>API: Connects to /hubs/scale with X-Edge-Token
    API->>DB: Validates station token, resolves TenantId & BranchId
    API-->>Edge: Establishes persistent duplex WebSocket connection (TLS 1.3)
    Edge->>API: Streams analytical scale weigh events in real time