# SRS-10: Identity & Access Management

## 1. Overview
Identity & Access Management (IAM) module provides user account management, role-based access control (RBAC), permission management, and group management.

## 2. Functional Requirements

### 2.1 User Management
**FR-IAM-001**: System shall allow admins to create users
- **Input**: Username, email, password, roles
- **Output**: Created user with ID
- **Validation**: Username uniqueness, valid email, strong password

**FR-IAM-002**: System shall allow admins to list users
- **Output**: User list with username, email, roles, status
- **Filtering**: By role, status, search

**FR-IAM-003**: System shall allow admins to view user details
- **Output**: User properties, roles, groups, permissions

**FR-IAM-004**: System shall allow admins to update users
- **Input**: User ID, updated properties
- **Validation**: Valid updated values

**FR-IAM-005**: System shall allow admins to delete users
- **Input**: User ID
- **Validation**: Cannot delete own account

**FR-IAM-006**: System shall allow users to view own profile
- **Output**: Own user properties, roles, permissions

**FR-IAM-007**: System shall allow users to update own profile
- **Input**: Updated profile properties (email, password)
- **Validation**: Valid updated values

### 2.2 Role Management
**FR-IAM-008**: System shall allow admins to create roles
- **Input**: Role name, description, permissions
- **Output**: Created role with ID
- **Validation**: Role name uniqueness

**FR-IAM-009**: System shall allow admins to list roles
- **Output**: Role list with name, description, permission count

**FR-IAM-010**: System shall allow admins to view role details
- **Output**: Role properties, assigned permissions, users with role

**FR-IAM-011**: System shall allow admins to update roles
- **Input**: Role ID, updated properties

**FR-IAM-012**: System shall allow admins to delete roles
- **Input**: Role ID
- **Validation**: Role not assigned to users

**FR-IAM-013**: System shall allow admins to assign permissions to roles
- **Input**: Role ID, permission ID
- **Action**: Add permission to role

**FR-IAM-014**: System shall allow admins to remove permissions from roles
- **Input**: Role ID, permission ID
- **Action**: Remove permission from role

### 2.3 Permission Management
**FR-IAM-015**: System shall list available permissions
- **Output**: Permission list with resource, action, description

**FR-IAM-016**: System shall display permission details
- **Output**: Permission properties, roles with permission

### 2.4 Group Management
**FR-IAM-017**: System shall allow admins to create groups
- **Input**: Group name, description
- **Output**: Created group with ID

**FR-IAM-018**: System shall allow admins to list groups
- **Output**: Group list with name, description, member count

**FR-IAM-019**: System shall allow admins to view group details
- **Output**: Group properties, members, roles

**FR-IAM-020**: System shall allow admins to update groups
- **Input**: Group ID, updated properties

**FR-IAM-021**: System shall allow admins to delete groups
- **Input**: Group ID

**FR-IAM-022**: System shall allow admins to add users to groups
- **Input**: Group ID, user ID
- **Action**: Add user to group

**FR-IAM-023**: System shall allow admins to remove users from groups
- **Input**: Group ID, user ID
- **Action**: Remove user from group

### 2.5 User-Role Assignment
**FR-IAM-024**: System shall allow admins to assign roles to users
- **Input**: User ID, role ID
- **Action**: Assign role to user

**FR-IAM-025**: System shall allow admins to remove roles from users
- **Input**: User ID, role ID
- **Action**: Remove role from user

### 2.6 Authentication
**FR-IAM-026**: System shall authenticate users
- **Input**: Username, password
- **Output**: JWT token on success
- **Validation**: Valid credentials

**FR-IAM-027**: System shall manage user sessions
- **Output**: Current user information, session expiration

**FR-IAM-028**: System shall allow users to logout
- **Action**: Invalidate session token

## 3. User Interface Requirements

### 3.1 IAM Dashboard
- User management tab
- Role management tab
- Group management tab
- Permission overview

### 3.2 User Management
- User list with filtering
- User creation modal
- User detail view
- User edit form

### 3.3 Role Management
- Role list with permission count
- Role creation modal
- Role detail view with permission assignment
- Role edit form

### 3.4 Group Management
- Group list with member count
- Group creation modal
- Group detail view with member management
- Group edit form

## 4. API Endpoints

```
GET    /api/v1/iam/users
GET    /api/v1/iam/users/:id
POST   /api/v1/iam/users
PUT    /api/v1/iam/users/:id
DELETE /api/v1/iam/users/:id

POST   /api/v1/iam/users/:id/roles
DELETE /api/v1/iam/users/:id/roles
POST   /api/v1/iam/users/:id/groups
DELETE /api/v1/iam/users/:id/groups

GET    /api/v1/iam/roles
GET    /api/v1/iam/roles/:id
POST   /api/v1/iam/roles
PUT    /api/v1/iam/roles/:id
DELETE /api/v1/iam/roles/:id

GET    /api/v1/iam/roles/:id/permissions
POST   /api/v1/iam/roles/:id/permissions
DELETE /api/v1/iam/roles/:id/permissions

GET    /api/v1/iam/permissions

GET    /api/v1/iam/groups
GET    /api/v1/iam/groups/:id
POST   /api/v1/iam/groups
PUT    /api/v1/iam/groups/:id
DELETE /api/v1/iam/groups/:id

POST   /api/v1/iam/groups/:id/users
DELETE /api/v1/iam/groups/:id/users/:user_id
```

## 5. Permissions
- **iam:read**: Required for viewing users, roles, groups
- **iam:write**: Required for creating, updating, deleting
- **admin role**: Required for all IAM operations

## 6. Error Handling
- Username already exists
- Invalid email format
- Weak password
- Role not found
- Permission denied
- Cannot delete own account
- Insufficient permissions

