Corporate Authentication¶

SCOPE_ITEM: Authentication layer for internal tools that integrates with the client's corporate identity provider. Users never create a local account — identity is always federated.

Decision Tree¶

IF: Client uses Microsoft 365 / Azure AD / Entra ID. THEN: Implement SAML 2.0 SSO via Microsoft Entra ID.

IF: Client uses Google Workspace. THEN: Implement OIDC via Google Workspace.

IF: Client uses Okta, OneLogin, or other IdP. THEN: Implement SAML 2.0 with generic SP configuration.

IF: Client has no corporate IdP (rare for internal tools). THEN: Implement email + password with mandatory MFA. CHECK: Confirm this is truly internal-only, not a B2B scenario.

IF: Client has on-premises Active Directory without cloud IdP. THEN: Recommend Azure AD Connect to bridge to Entra ID. THEN: Fall back to LDAPS direct integration only if cloud is blocked.

Single Sign-On (SSO)¶

SAML 2.0 Integration¶

SCOPE_ITEM: SP-initiated SAML 2.0 login flow.

INCLUDES: - SP metadata generation (entity ID, ACS URL, signing cert). - IdP metadata import (XML upload or metadata URL). - SAML assertion validation (signature, audience, timestamps). - Attribute mapping (email, display name, groups, department). - Session creation from SAML response. - Single logout (SLO) support.

OPTIONAL: - IdP-initiated login (for IdP portal tile). - Multi-IdP support (for orgs with multiple identity providers). - IdP discovery (email domain routing to correct IdP).

CHECK: ACS URL must use HTTPS in production. CHECK: Clock skew tolerance set to 120 seconds max. CHECK: SAML assertions must be signed; encrypted is recommended.

Implementation — GE Stack¶

SCOPE_ITEM: SAML integration using BoxyHQ SAML Jackson.

NextAuth.js (Auth.js v5)
  └── BoxyHQ SAML Jackson provider
        └── SAML assertion processing
              └── Session JWT with user claims

INCLUDES: - NextAuth.js with boxyhq-saml provider. - SAML Jackson service (self-hosted, EU infrastructure). - Admin UI for IdP connection management. - Per-tenant IdP configuration (for multi-department setups).

CHECK: SAML Jackson stores IdP config in PostgreSQL (same DB). CHECK: Redirect URIs must be registered in client's IdP admin.

OIDC Integration¶

SCOPE_ITEM: OpenID Connect login for Google Workspace / Okta.

INCLUDES: - OIDC discovery (.well-known/openid-configuration). - Authorization code flow with PKCE. - Token validation (signature, issuer, audience, expiry). - Userinfo endpoint for additional claims. - Refresh token rotation.

OPTIONAL: - Back-channel logout. - Token introspection endpoint.

Active Directory / Microsoft Entra ID¶

User Provisioning¶

SCOPE_ITEM: Automatic user lifecycle management via SCIM.

INCLUDES: - SCIM 2.0 endpoint for user create/update/delete. - Group membership sync (map AD groups to app roles). - Just-in-time provisioning as fallback (create user on first SSO). - Deprovisioning: deactivate app user when removed from AD group.

OPTIONAL: - Scheduled full sync (reconciliation). - Custom attribute mapping beyond standard SCIM schema. - Nested group resolution.

CHECK: SCIM endpoint must be protected with bearer token. CHECK: Deprovisioning must deactivate, never hard-delete (audit trail).

Conditional Access¶

SCOPE_ITEM: Honour Entra ID conditional access policies.

INCLUDES: - Session respects IdP session lifetime. - Re-authentication on sensitive actions (step-up auth). - Device compliance signals passed via SAML claims (if available).

OPTIONAL: - IP-based access restrictions at application level. - Named location enforcement. - Compliant device requirement.

CHECK: Conditional access policies are configured in Entra ID admin, not in the application. Application must correctly handle denied access.

Multi-Factor Authentication (MFA)¶

Delegated MFA (Recommended)¶

SCOPE_ITEM: MFA enforced at the IdP level.

INCLUDES: - IdP handles MFA challenge during SSO flow. - Application trusts IdP MFA assertion. - amr (Authentication Methods References) claim validation.

CHECK: Document to client that MFA policy is their responsibility in their IdP admin console.

Application-Level MFA (Fallback)¶

SCOPE_ITEM: MFA within the application for non-SSO users.

IF: Non-SSO users exist (e.g., service desk, contractors). THEN: Implement TOTP-based MFA.

INCLUDES: - TOTP setup flow (QR code, manual key entry). - TOTP verification on login. - Recovery codes (one-time use, 10 codes generated). - MFA enforcement policy (required for all / admin-only).

OPTIONAL: - WebAuthn/passkey support. - SMS fallback (NOT recommended for security, but some clients require it).

CHECK: Recovery codes must be shown exactly once and stored hashed. CHECK: TOTP secret stored encrypted at rest (AES-256).

Service Accounts¶

SCOPE_ITEM: Machine-to-machine authentication for API integrations.

INCLUDES: - API key generation (admin UI). - API key rotation (generate new, grace period, revoke old). - Scope restrictions (read-only, specific endpoints). - Usage logging (requests per key, last used timestamp). - Rate limiting per key.

OPTIONAL: - OAuth 2.0 client credentials flow. - JWT bearer token authentication. - IP allowlist per service account.

CHECK: API keys must be hashed in database (bcrypt or SHA-256). CHECK: API keys must never appear in logs or error messages. CHECK: Default rate limit: 100 requests/minute per key.

Session Management¶

SCOPE_ITEM: Secure session handling after authentication.

INCLUDES: - JWT-based sessions (NextAuth.js default). - Session lifetime aligned with IdP policy (default 8 hours). - Sliding window refresh (extend on activity). - Secure cookie attributes (HttpOnly, Secure, SameSite=Lax). - Session revocation on user deprovisioning.

OPTIONAL: - Database-backed sessions (for immediate revocation). - Concurrent session limit. - Session activity log visible to user.

CHECK: Refresh tokens stored in httpOnly cookies, never localStorage. CHECK: CSRF protection enabled (NextAuth.js default). CHECK: Session cookie name must not reveal technology stack.

Compliance Requirements¶

COMPLIANCE: GDPR Article 25 — Authentication data minimisation. Only store: email, display name, role. Do not store IdP tokens beyond session lifetime.

COMPLIANCE: GDPR Article 17 — Right to erasure. User deactivation must anonymise personal data after retention period.

COMPLIANCE: Audit — All authentication events logged. Log: login success, login failure, logout, MFA challenge, role change, permission change, API key creation/revocation.

COMPLIANCE: Password policy (if applicable). Minimum 12 characters, bcrypt hashing (cost factor 12), breached password check (HaveIBeenPwned API, k-anonymity model).

Scoping Questions¶

CHECK: Which identity provider does the client use? CHECK: How many users will access the application? CHECK: Are there external users (contractors, auditors)? CHECK: Does the client require device compliance checks? CHECK: Are there service accounts / API integrations needed? CHECK: What is the required session timeout? CHECK: Does the client have existing conditional access policies?