User Management and Security Design – AWS Cognito

Overview

This document describes the design and implementation of a secure, multi-tenant user management system for FacturaScan 360 using AWS Cognito. The system supports user authentication, role-based access control, tenant-level isolation, and extensibility toward enterprise SSO integration.

---

1. Identity Architecture

1.1. User Pools

FacturaScan 360 leverages AWS Cognito User Pools to provide the following functionality:

• Secure registration and login endpoints.
• Email verification for account activation.
• Multi-factor authentication (MFA) with SMS or authenticator apps.
• Password policies and reset workflows.

Each user is associated with:

• A verified email address (unique identifier).
• A tenant_id (custom attribute) for multi-tenant isolation.
• A role (custom attribute) representing access level.

1.2. Custom Attributes

Attribute	Type	Example Value	Purpose
tenant_id	String	org_12ab3c	Links user to their organization
role	Enum	admin, editor, reviewer, viewer	Defines access scope

These attributes are included in the user's JWT claims for backend authorization.

---

2. Role Definitions

The system supports four role types within each organization:

Role	Description	Permissions
Admin	Full access; manages users, settings, billing	CRUD on all invoices, users, settings
Editor	Uploads and edits invoices, but cannot manage users	CRUD on invoices
Reviewer	Views and annotates validation errors only	Read-only + add internal notes
Viewer	Read-only access to validated invoice data	View only

The roles are enforced in the backend via claims parsed from JWT tokens.

---

3. Authorization & Claims Handling

JWT tokens are generated by Cognito upon login. These tokens include both standard claims and custom attributes, for example:

{
  "email": "alice@example.com",
  "custom:tenant_id": "org_12ab3c",
  "custom:role": "editor"
}

3.1. Token Verification (Backend)

• Tokens are verified on each request via public keys (JWKS endpoint).
• Middleware extracts the user's tenant_id and role from claims.
• Access to endpoints is granted or denied accordingly.

---

4. Backend Enforcement (FastAPI / Flask)

4.1. Route Protection Example (FastAPI)

@router.post("/invoices/")
@requires_role(["admin", "editor"])
async def upload_invoice(user: User = Depends(get_current_user)):
    return process_invoice(user)

4.2. Multi-Tenant Isolation

In each request, the tenant_id from the token is used to:

• Filter database queries (e.g., WHERE tenant_id = :tenant_id)
• Prevent cross-tenant data access
• Automatically inject tenant_id on insertions

---

5. User Lifecycle Management

Operation	Mechanism
User invitation	Admin triggers email invitation via Cognito Admin API
Account deactivation	Admin can disable user account via AWS Console or API
Password reset	Triggered via email by user or admin
Token revocation	Issued via AWS Cognito Admin API (revokes refresh tokens)

---

6. Audit and Logging

Critical operations are logged and monitored via:

Event Type	Logged Fields
Login / logout	User email, IP, timestamp
Role change	Target user, old role, new role, admin responsible
Invoice modification	User, action (create, update, delete), invoice ID
Access violation	Endpoint attempted, user, reason for denial

Logs are stored in AWS CloudWatch Logs, and alerts can be configured using CloudWatch Alarms.

---

7. Future Extensions: Enterprise SSO Integration

For enterprise clients, FacturaScan 360 will support federation via:

• SAML 2.0 (e.g., Azure AD, Okta)
• OpenID Connect (OIDC)

Preparation steps:

• Define custom attributes mapping (e.g., external group → internal role).
• Configure Identity Providers in Cognito.
• Adjust backend role extraction to parse id_token accordingly.

---

8. Security and Compliance Features

Area	Implementation
Data segregation	Enforced via tenant_id filtering at all access points
Token expiration	Short-lived ID tokens; refresh via secure path
MFA enforcement	Enabled by default
Attribute immutability	tenant_id and role cannot be modified by user
Cognito policies	IAM roles restrict use of admin operations to specific backend

---

9. Summary

This Cognito-based identity and access model ensures:

• Robust authentication for all users.
• Fine-grained authorization through role-based access and tenant isolation.
• Scalability and maintainability, leveraging native AWS IAM and JWT standards.
• Compliance-readiness for enterprise contexts via audit logging and SSO readiness.