Shared Identity & Access Management (IAM) Platform

Product Requirements & Technical Specification

Version 1.0

1. Purpose

Develop a centralized Identity and Access Management (IAM) platform that will be used by all company SaaS applications.

The platform shall provide:

Authentication
Authorization
User Management
Role Management
Permission Management
Organization Management
Audit Logging
Single Sign-On Ready Architecture

The IAM platform shall become the single source of truth for all users and access rights.

Applications consuming IAM include:

Loan Management System (LMS)
CRM
Inventory Management System
Ticketing System
Collection Management System
Any future applications

2. Design Goals

Functional Goals

Centralized authentication
Centralized authorization
Multi-tenant architecture
JWT based authentication
Role Based Access Control (RBAC)
REST API driven
Web Admin Portal

Non-Functional Goals

Easy to maintain
Easy to extend
Suitable for a single development team
Capable of supporting 10,000+ users
Cloud deployable
AI-generated code friendly

3. Technology Stack

Backend

Python 3.13

Flask

SQLAlchemy

Alembic

PyJWT

Argon2 Password Hashing

Redis (optional)

PostgreSQL

Frontend

Bootstrap 5

jQuery

DataTables

Deployment

Nginx

AWS EC2

PostgreSQL

4. High-Level Architecture

User ↓ Identity Server ↓ JWT Token ↓ Applications * LMS * CRM * Inventory * Ticketing * Collections

Applications must not store passwords.

Applications must trust IAM for authentication.

5. Multi-Tenant Design

The platform must support multiple organizations.

Examples:

ABC Finance

XYZ Gold Loans

PQR Cooperative Society

A user may belong to multiple organizations.

A user may have different roles in different organizations.

Example:

User: John

Organization ABC Role: Branch Manager

Organization XYZ Role: Auditor

6. Database Design

organizations

Fields

uuid

name

code

status

created_at

updated_at

deleted_at

applications

Fields

uuid

name

code

description

status

created_at

updated_at

users

Fields

uuid

mobile

username

password_hash

first_name

middle_name

last_name

status

last_login_at

failed_login_attempts

created_at

updated_at

deleted_at

roles

Fields

uuid

name

code

description

status

created_at

updated_at

permissions

Fields

uuid

module

code

description

created_at

updated_at

Examples

loan.view

loan.create

loan.approve

loan.disburse

customer.view

customer.edit

inventory.view

inventory.edit

ticket.create

ticket.close

user_organizations

Fields

user_id

organization_id

created_at

user_roles

Fields

user_id

organization_id

role_id

assigned_by

assigned_at

role_permissions

Fields

role_id

permission_id

created_at

refresh_tokens

Fields

user_id

token

expires_at

created_at

revoked_at

audit_logs

Fields

organization_id

user_id

action

resource_type

resource_id

ip_address

user_agent

details_json

created_at

7. Authentication Requirements

Login

Username or Email

Password

Returns:

Access Token

Refresh Token

User Profile

Organization Context

Logout

Invalidate Refresh Token

Write Audit Log

Password Reset

Admin Reset

Self Reset

Forgot Password Workflow

Password Policy

Minimum 8 Characters

Uppercase

Lowercase

Number

Special Character

Store passwords using Argon2.

Never use MD5.

Never use SHA1.

Never use plain SHA256.

8. JWT Token Design

Access Token Expiry

15 Minutes

Refresh Token Expiry

30 Days

Sample Payload

{ "sub": "123", "org_id": "10", "roles": ["branch_manager"], "permissions": [ "loan.create", "loan.approve" ], "iat": 123456789, "exp": 123456999 }

9. Authorization Model

Applications must never check role names directly.

Bad Example

if role == "Manager"

Good Example

if user.has_permission("loan.approve")

Permissions are the source of truth.

Roles are permission bundles.

10. Standard Roles

System Administrator

Organization Administrator

Branch Manager

Branch Executive

Collection Officer

Inventory Officer

Auditor

Viewer

11. Audit Logging

The following actions must be logged:

Logout

Failed Login

Password Change

Password Reset

User Creation

User Update

User Disable

Role Assignment

Role Removal

Permission Changes

Organization Creation

Organization Update

Token Refresh

Every audit log entry must contain:

Who

When

From Which IP

What Action

Which Resource

12. REST API Design

Authentication

POST /api/auth/login

POST /api/auth/logout

POST /api/auth/refresh

GET /api/auth/me

POST /api/auth/change-password

POST /api/auth/forgot-password

POST /api/auth/reset-password

Users

GET /api/users

POST /api/users

GET /api/users/{id}

PUT /api/users/{id}

DELETE /api/users/{id}

Roles

GET /api/roles

POST /api/roles

PUT /api/roles/{id}

DELETE /api/roles/{id}

Permissions

GET /api/permissions

POST /api/permissions

PUT /api/permissions/{id}

DELETE /api/permissions/{id}

Organizations

GET /api/organizations

POST /api/organizations

PUT /api/organizations/{id}

DELETE /api/organizations/{id}

Applications

GET /api/applications

POST /api/applications

PUT /api/applications/{id}

DELETE /api/applications/{id}

Audit Logs

GET /api/audit-logs

GET /api/audit-logs/{id}

13. Middleware Requirements

Create reusable decorators.

@login_required

@require_permission("loan.approve")

@require_role("admin")

@organization_required

14. Admin Portal

Modules

Dashboard

Organizations

Users

Roles

Permissions

Applications

Audit Logs

Profile

Settings

15. Folder Structure

src/

app.py

config/

models/

services/

repositories/

controllers/

middlewares/

decorators/

schemas/

utils/

templates/

static/

migrations/

tests/

docs/

16. Coding Standards

Use Flask Blueprints

Use Service Layer Pattern

Use Repository Pattern

Use SQLAlchemy ORM

Use Alembic Migrations

No raw SQL unless necessary

Type hints required

Pydantic request validation preferred

Consistent API response format

17. Security Requirements

HTTPS Only

JWT Signature Validation

CSRF Protection

Rate Limiting

Account Lockout after 5 failed attempts

Secure Password Hashing

Audit Logging

Input Validation

Parameterized Queries

Secret Key Rotation Support

18. Future Features (Do Not Build Now)

Google Login

Microsoft Login

LDAP

Active Directory

SAML

OpenID Connect Provider

Device Management

Session Management

API Keys

Service Accounts

Workflow Approvals

Build the architecture in a way that these features can be added later without major redesign.

19. Definition of Done

The system shall be considered complete when:

Users can login and logout.
JWT authentication works.
Organizations can be managed.
Roles can be created.
Permissions can be assigned.
Users can be assigned roles.
Applications can validate JWT tokens.
Audit logs are generated.
Admin UI is functional.
Alembic migrations are available.
Automated tests pass.

20. Expected Deliverables

Database Schema
ER Diagram
Flask Application
Alembic Migrations
REST APIs
Admin Portal
API Documentation
Test Suite
Deployment Guide
Sample Integration Example for LMS and CRM

Shared Identity & Access Management (IAM) Platform

Comprehensive Product Requirements & Technical Design Specification

Version 1.0

1. Objective

Build a centralized Identity and Access Management (IAM) platform that serves as the single source of truth for authentication, authorization, user management, role management, permission management, and organizational access control across all company SaaS applications.

The IAM platform will be used by:

Loan Management System (LMS)
CRM
Inventory Management System
Ticketing System
Collections Management System
HRMS
DMS
Future SaaS Applications

All applications must rely on IAM for identity and access management.

Applications must never store passwords.

2. Product Goals

Functional Goals

Centralized Authentication
Centralized Authorization
Multi-Tenant Support
Role-Based Access Control (RBAC)
Data Scope Authorization
JWT-Based Authentication
Organization Management
Audit Logging
API Security
SSO-Ready Architecture

Non-Functional Goals

Simple enough for a small development team
Scalable to 10,000+ users
Scalable to 100+ organizations
AI-assisted development friendly
Cloud deployable
Extensible without major redesign

3. Technology Stack

Backend

Python 3
Flask
SQLAlchemy
Alembic
PyJWT
Argon2 Password Hashing
PostgreSQL

Frontend

Bootstrap 5
jQuery
DataTables

Infrastructure

Nginx
PostgreSQL

4. High-Level Architecture

                     IAM SERVER

                            |
    -------------------------------------------------
    |             |             |             |
    v             v             v             v

   LMS           CRM       Inventory      Ticketing

                            |
                            v

                      JWT Validation

IAM is the master authority for:

Users
Roles
Permissions
Organizations
Authentication
Authorization

5. Core Design Principles

Principle 1

Authentication and Authorization are separate concerns.

Authentication answers:

"Who are you?"

Authorization answers:

"What can you do?"

Principle 2

Permissions are authoritative.

Applications must never hardcode role names.

Bad:

if role == "Branch Manager":

Good:

if has_permission("loan.approve"):

Principle 3

Authorization consists of:

Permission
Scope

Example:

loan.view
+
own_branch

Permission defines action.

Scope defines visibility.

6. Multi-Tenant Architecture

The platform must support multiple organizations.

Examples:

ABC Finance
XYZ Gold Loans
PQR Cooperative Society

Users may belong to multiple organizations.

Users may have different roles in different organizations.

Example:

User: John

ABC Finance
Role: Branch Manager

XYZ Finance
Role: Auditor

7. Organizational Hierarchy

Support the following hierarchy:

Organization

    └── Region

        └── Area

             └── Branch

Example:

BB Finance

    └── West Region

        └── Pune Area

             ├── Pimpri Branch
             ├── Chinchwad Branch
             └── Nigdi Branch

This hierarchy will drive data access controls.

8. Database Schema

organizations

Field	Type
id	bigint
uuid	uuid
name	varchar
code	varchar
status	varchar
created_at	timestamp
updated_at	timestamp

offices

Self-referencing tree for organization hierarchy. Both organization_id and parent_id are indexed for efficient tree traversal.

Field	Type
id	bigint
organization_id	bigint
parent_id	bigint
name	varchar
code	varchar

applications

Field	Type
id	bigint
uuid	uuid
name	varchar
code	varchar
description	text
status	varchar

users

Field	Type
id	bigint
uuid	uuid
username	varchar
email	varchar
mobile	varchar
password_hash	text
first_name	varchar
middle_name	varchar
last_name	varchar
status	varchar
last_login_at	timestamp
failed_login_attempts	integer
created_at	timestamp

roles

Field	Type
id	bigint
name	varchar
code	varchar
description	text

permissions

Field	Type
id	bigint
module	varchar
code	varchar
description	text

Examples:

loan.view
loan.create
loan.approve
loan.disburse

customer.view
customer.edit

inventory.view
inventory.edit

ticket.close

user_organizations

Field	Type
id	bigint
user_id	bigint
organization_id	bigint

user_roles

Field	Type
id	bigint
user_id	bigint
role_id	bigint
organization_id	bigint
assigned_by	bigint
assigned_at	timestamp

role_permissions

Field	Type
id	bigint
role_id	bigint
permission_id	bigint

user_scopes

Field	Type
id	bigint
user_id	bigint
organization_id	bigint
office_id	bigint

refresh_tokens

Field	Type
id	bigint
user_id	bigint
token	text
expires_at	timestamp
revoked_at	timestamp

audit_logs

Field	Type
id	bigint
organization_id	bigint
user_id	bigint
action	varchar
resource_type	varchar
resource_id	varchar
ip_address	varchar
user_agent	text
details_json	jsonb
created_at	timestamp

9. Authentication

Login

Endpoint:

POST /api/auth/login

Input:

{
  "username":"admin",
  "password":"password"
}

Output:

{
  "access_token":"",
  "refresh_token":"",
  "user":{}
}

Logout

POST /api/auth/logout

Invalidate refresh token.

Refresh Token

POST /api/auth/refresh

Generate new access token.

Current User

GET /api/auth/me

Return profile and permissions.

10. Password Policy

Requirements:

Minimum 8 characters
Uppercase
Lowercase
Numeric
Special Character

Use:

Argon2

Never use:

MD5
SHA1
Plain SHA256

11. JWT Token Design

Access Token Expiry:

15 Minutes

Refresh Token Expiry:

30 Days

Sample Payload

{
  "sub": "123",
  "org_id": "10",
  "roles": ["branch_manager"],
  "permissions": [
    "loan.view",
    "loan.approve"
  ],
  "scope": {
    "level": "OWN_BRANCH",
    "office_id": 5
  },
  "iat": 123456,
  "exp": 123999
}

12. Authorization Framework

Every authorization decision shall use:

Permission + Scope

Examples:

loan.view + own_branch

loan.view + own_region

loan.view + all

13. Scope-Based Access Control

Supported scopes:

OWN_BRANCH

OWN_AREA

OWN_REGION

ORGANIZATION

GLOBAL

Examples:

Branch Manager

loan.view

Scope:
OWN_BRANCH

Area Manager

loan.view

Scope:
OWN_AREA

Regional Manager

loan.view

Scope:
OWN_REGION

Auditor

loan.view

Scope:
ORGANIZATION

Super Admin

GLOBAL

14. Approval Authority Framework

Support future approval limits.

Examples:

loan.approve.limit_50000

loan.approve.limit_500000

loan.approve.unlimited

Used later in LMS workflows.

15. Standard Roles

Super Administrator

Organization Administrator

CEO

COO

Credit Head

Regional Manager

Area Manager

Branch Manager

Branch Executive

Collection Officer

Inventory Officer

Auditor

Viewer

16. REST APIs

Authentication

POST /api/auth/login
POST /api/auth/logout
POST /api/auth/refresh
GET  /api/auth/me
POST /api/auth/change-password
POST /api/auth/reset-password

Users

GET    /api/users
POST   /api/users
GET    /api/users/{id}
PUT    /api/users/{id}
DELETE /api/users/{id}

Roles

GET    /api/roles
POST   /api/roles
PUT    /api/roles/{id}
DELETE /api/roles/{id}

Permissions

GET    /api/permissions
POST   /api/permissions
PUT    /api/permissions/{id}
DELETE /api/permissions/{id}

Organizations

GET    /api/organizations
POST   /api/organizations
PUT    /api/organizations/{id}
DELETE /api/organizations/{id}

Offices

GET    /api/organizations/{org_id}/offices
POST   /api/organizations/{org_id}/offices
GET    /api/offices/{id}/children
POST   /api/offices/{id}/children
PUT    /api/offices/{id}
DELETE /api/offices/{id}

Audit Logs

GET /api/audit-logs

17. Reusable Authorization Decorators

Required decorators:

@login_required

@require_permission("loan.approve")

@require_scope("OWN_BRANCH")

@organization_required

18. Audit Logging Requirements

Log:

Login
Logout
Failed Login
Password Change
Password Reset
User Create
User Update
User Disable
Role Assignment
Role Removal
Permission Changes
Organization Create
Branch Create
Token Refresh

Each log entry must contain:

Who
When
What
Where
IP Address
User Agent

19. Admin Portal

Modules:

Dashboard
Organizations
Regions
Areas
Branches
Users
Roles
Permissions
Applications
Audit Logs
Profile
Settings

20. Folder Structure

src/

├── app.py
├── config/
├── models/
├── repositories/
├── services/
├── controllers/
├── middlewares/
├── decorators/
├── schemas/
├── utils/
├── templates/
├── static/
├── migrations/
├── tests/
└── docs/

21. Development Standards

Flask Blueprints
Service Layer Pattern
Repository Pattern
SQLAlchemy ORM
Alembic Migrations
Type Hints
DTO/Schema Validation
Consistent API Responses
Unit Tests
Integration Tests

22. Security Requirements

Mandatory:

HTTPS Only
JWT Validation
CSRF Protection
Input Validation
Rate Limiting
Account Lockout After 5 Failures
Secure Headers
Parameterized Queries
Secret Rotation Support

23. Future Features (Not In Scope For V1)

Google Login
Microsoft Login
LDAP
Active Directory
SAML
OpenID Connect Provider
Device Management
Session Tracking
API Keys
Service Accounts
Workflow Approvals

Architecture must allow future implementation without redesign.

24. Definition of Done

Project is complete when:

Users can authenticate.
JWT authentication works.
Roles work.
Permissions work.
Scopes work.
Organizations work.
Branch hierarchy works.
Audit logging works.
Admin UI works.
APIs are documented.
Alembic migrations exist.
Automated tests pass.

25. Deliverables

Development team must provide:

Source Code
Database Schema
ER Diagram
Alembic Migrations
REST API Documentation
Test Suite
Deployment Guide
Sample LMS Integration
Sample CRM Integration

This specification shall be considered the baseline architecture for all current and future SaaS applications within the organization.

Back to documentation index