ADR-027: Internal staff authentication — Cognito and corporate SSO¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, Chief Information Security Officer |
| Affects repos | bank-platform, bank-app |
Context¶
Internal staff require access to the back-office web application and supporting internal tooling. Staff authentication has different requirements from customer authentication (ADR-026): it is web-based, must integrate with the bank's corporate identity directory, and carries higher risk per session (staff can access all customer data within their role scope). It must also connect to AWS console and CLI access for the engineering and operations teams.
A separate authentication system for staff — rather than staff groups within the customer Cognito pool — is required to enforce different security policies, session durations, and MFA requirements without compromise.
Decision¶
AWS Cognito User Pool (staff pool, separate from the customer pool in ADR-026). SAML/OIDC federation from the bank's corporate identity provider. Web-based. MFA mandatory for all staff.
| Concern | Decision |
|---|---|
| Identity store | Cognito staff User Pool — separate from customer pool |
| Federation | SAML 2.0 or OIDC from corporate IdP (provider not mandated — Google Workspace, Microsoft 365, Okta, and equivalents all supported) |
| Interface | Web browser (back-office app); all customer-facing surfaces remain mobile-only per ADR-026 |
| MFA | Required for all staff on every session. TOTP or WebAuthn hardware key |
| Session duration | Shorter than customer sessions — maximum 8 hours, re-authentication required for sensitive operations |
| AWS access | AWS IAM Identity Center (separate concern) — handles console and CLI access, federated from the same corporate IdP. Not part of this ADR |
Authentication flow¶
- Staff opens back-office web app → redirected to corporate IdP login (SSO)
- Corporate IdP authenticates (existing credentials + MFA) → issues SAML assertion / OIDC token
- Cognito staff pool accepts the federation → issues JWT with staff role claims
- API Gateway validates JWT on every request; role claims enforce RBAC (MOD-044, MOD-046)
- For privileged operations (bulk data access, configuration changes): step-up MFA challenge via Cognito custom auth trigger
Separation from customer pool rationale¶
| Property | Customer pool (ADR-026) | Staff pool (this ADR) |
|---|---|---|
| Auth method | Passkey / biometric | Corporate SSO federation |
| MFA | Step-up on high-risk actions | Required on every session |
| Session length | Mobile app session (longer) | ≤ 8 hours |
| Access surface | Mobile app only | Web browser |
| User lifecycle | Customer self-service | HR-driven via corporate IdP |
| Risk profile | Consumer account takeover | Privileged insider access |
Mixing these in one pool would require complex conditional policy logic that is error-prone and difficult to audit. Separation is cleaner and more defensible.
Offboarding¶
When a staff member leaves, disabling their account in the corporate IdP immediately revokes Cognito federation — no separate deprovisioning step required in the Cognito pool. This satisfies the joiner/mover/leaver process without manual intervention.
Consequences¶
Positive: - Staff use their existing corporate credentials — no new passwords to manage - Offboarding via IdP is immediate and complete; no orphaned Cognito accounts - Corporate IdP is the single source of truth for staff identity — consistent with PAM policy (MOD-046) - Separation of customer and staff pools means different security policies can be applied independently without risk of cross-pool configuration error - Provider-agnostic federation means the bank is not locked to a specific IdP vendor
Negative: - Requires the corporate IdP to be configured and operational before back-office access can be tested — a dependency on IT/people operations - SAML/OIDC federation configuration must be tested thoroughly; a misconfiguration could lock all staff out of the back-office app - Two Cognito pools to manage — additional operational surface area, though both are managed services
Alternatives considered¶
Staff as a group in the customer Cognito pool: Rejected. Mixing customer and staff identity in a single pool with group-based separation is an audit and misconfiguration risk. Separate pools are cleaner, independently auditable, and allow different security policies without compromise.
AWS IAM users for back-office access: Rejected. IAM users are for AWS resource access, not application authentication. Does not support web app SSO. Long-lived credentials are incompatible with SG-008.
Dedicated identity provider (Okta, Auth0): Rejected. Additional vendor outside AWS boundary; adds cost and complexity. Cognito with corporate IdP federation achieves the same result within the existing AWS infrastructure.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-029 | Immutable audit log | governed — all staff actions are traceable to a federated identity |
| CAP-074 | Role-scoped API gateway | enabled — staff JWT role claims enforce RBAC at API gateway |
| CAP-109 | Session lifecycle management | enabled — 8-hour staff session maximum; step-up MFA for privileged operations |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-023 | Cloud provider and region strategy | Cognito staff pool in same AWS region |
| ADR-026 | Customer authentication — Cognito, mobile-first, passwordless | separate pool rationale documented relative to customer pool |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-027.yaml