This file describes the client-side configuration + auth integration layer used by all web portals.
sequenceDiagram
autonumber
participant User as User Browser
participant Portal as Portal (mt_user_portal)
participant IDP as Authentication Server (IdP)
participant API as Protected API Service
User->>Portal: Access protected route
Portal->>Portal: No valid access token
Portal->>IDP: Redirect /authorize (with PKCE)
IDP->>User: Login + MFA pages
User->>IDP: Credentials + MFA
IDP->>Portal: Redirect with Authorization Code
Portal->>IDP: POST /token (code + PKCE)
IDP->>Portal: Access & Refresh tokens
Portal->>Portal: Store tokens in secure cookies
User->>Portal: Access protected route again
Portal->>API: Send access token
API->>IDP: Validate via JWKS
API->>Portal: Authorized response
Provide a reusable OAuth2/OIDC client module for:
mt_user_portalmt_vendor_portalmt_admin_portal- future portals
Portals authenticate users only via the centralized IdP; no local passwords or MFA logic exists in the portal.
- Redirects users to IdP
/authorize
- Exchanges authorization codes for tokens
- Stores tokens in secure cookies
- Validates JWT access tokens using JWKS
- Injects
UserCtx into handlers
- Provides
/auth/refresh and /auth/logout
- Provides guards (scope checks)
- It does NOT store or verify passwords
- It does NOT issue tokens
- It does NOT handle MFA
- It does NOT store IdP signing keys
- It does NOT manage refresh token families
All identity and MFA logic stays in the Authentication Server.
Portal-specific infrastructure:
- DB connections (portal-only data)
- Redis caches / queues
- API keys for portal-specific features
- Namespaces for caching/session
IdP-facing configuration:
issuertoken_endpointjwks_uriclient_idclient_secret (confidential only)audienceredirect_uri- TTL hints
Combined container:
infra: Arc<InfraState>auth: Arc<AuthClientCfg>
- Stored in
Secure; HttpOnly; SameSite=Strict cookie
- Short TTL (5–10 minutes)
- Read by server middleware for API calls
- Stored in
Secure; HttpOnly; SameSite=Lax cookie
- Silent renewal via
/auth/refresh
Portal uses a JWT extractor that:
-
Reads access_token cookie
-
If missing, checks Authorization: Bearer
-
Validates:
- signature (via JWKS)
issaudexp
-
Injects UserCtx into request extensions
Redirect to IdP with PKCE parameters.
- Exchange code for tokens
- Set access/refresh cookies
- Redirect into portal
- Use refresh token to request new access token
- Silent refresh when access expired
- Clear cookies
- (Optional) Call IdP logout endpoint
-
Every portal must define at least:
PORTAL_CLIENT_IDPORTAL_AUDIENCEPORTAL_REDIRECT_URIPORTAL_DB_MAIN_URLPORTAL_REDIS_CACHE_URL
-
Every portal must register its own client record in the IdP.
-
No DB of the portal shall store passwords or MFA information.
Portals may define new scopes:
user:profileuser:inventoryportal:admin
IdP must approve and issue these scopes.
- Device posture integration
- OIDC back-channel logout
- OIDC front-channel logout
- Service-to-service tokens
- Zero sensitive secret sharing
- Portals remain stateless w.r.t identity
- Token validation and session refresh handled automatically
- Easy addition of new portals
- OIDC-compliant and interoperable with mobile applications
If you'd like, I can also generate:
- Mermaid diagrams for all three docs
- Rendered PDF versions
- Example
Dockerfile / deployment manifests for each component