# Users & RBAC

User management, role-based access control, and multi-factor authentication in FluxiQ PIX.

## Prerequisites

- Admin access to the FluxiQ PIX admin portal
- Understanding of your institution's role hierarchy

## Default Users

| User | Password | Role |
|------|----------|------|
| admin | Admin@2026! | System Administrator |
| operator | Operator@2026! | Transaction Operator |
| viewer | Viewer@2026! | Read-only Viewer |
| integration | FluxiQ@2026! | FluxiQ Integration |

## RBAC Architecture

```mermaid
graph TD
    USER[User] -->|belongs to| GROUP[Group]
    GROUP -->|has| FEATURES[Features/Permissions]
    FEATURES -->|checked by| PLUG[RequirePermission Plug]
    PLUG -->|ETS cache<br/>5-min TTL| ETS[(ETS Table)]
    ETS -->|refresh from| DB[(group_features table)]
```

### Permission Check Flow

1. Request arrives with JWT cookie
2. `JWTAuth` plug extracts user and checks token blacklist
3. `RequirePermission` plug checks user's group features in ETS cache
4. Cache miss -> query `monetarie_auth.group_features` table -> cache for 5 minutes
5. Permission denied -> HTTP 403 (RFC 7807 format)

### Key Properties

- **Fail-closed**: Database errors result in access denied (not granted)
- **SSO passthrough**: Core Banking Guardian tokens bypass RBAC checks
- **ETS-cached**: Permission lookups are fast (no DB query per request)
- **35 protected actions**: Controller actions annotated with required permissions

## Groups and Permissions

Groups are defined in `monetarie_auth.groups` and linked to features via `monetarie_auth.group_features`:

| Group | Typical Permissions |
|-------|-------------------|
| System Administrator | All permissions |
| Transaction Operator | Create/view transactions, manage keys |
| Viewer | Read-only access to all sections |
| Integration | API access for Core Banking integration |

## Multi-Factor Authentication

FluxiQ PIX supports TOTP-based MFA with backup codes:

### Setup Flow

1. User enables MFA in profile settings
2. System generates TOTP secret and QR code
3. User scans QR code with authenticator app
4. User verifies with a TOTP code
5. System provides backup codes

### Login with MFA

```mermaid
sequenceDiagram
    User->>+Backend: POST /auth/login (credentials)
    Backend-->>-User: {mfa_required: true, mfa_token: "..."}
    User->>+Backend: POST /auth/mfa/verify (code + mfa_token)
    Backend-->>-User: Set-Cookie: pix_session
```

### MFA Schema

| Field | Type | Description |
|-------|------|-------------|
| `mfa_enabled` | boolean | Whether MFA is active |
| `mfa_secret` | string | TOTP secret (encrypted) |
| `mfa_backup_codes` | array | One-time backup codes |
| `mfa_last_used_at` | datetime | Last MFA verification |

## Account Security

### Login Rate Limiting

- 10 login attempts per 15 minutes per IP address
- Applies to both `/auth/login` and `/auth/mfa/verify`
- Redis token bucket algorithm
- Returns HTTP 429 with `Retry-After` header

### Account Lockout

- After 10 failed login attempts, account is automatically blocked (`is_blocked = true`)
- Generic error response prevents account enumeration
- Admin must manually unblock the account

### Password Expiry

- `password_expires` field checked during authentication
- Expired passwords require reset before login

### Token Blacklist

- On logout, JWT is added to Redis blacklist with remaining TTL
- Every authenticated request checks the blacklist
- Prevents use of stolen tokens after logout

## Audit Logging

All user actions are logged in `monetarie_audit.activity_log` (monthly partitioned):

| Field | Description |
|-------|-------------|
| `user_id` | Acting user UUID |
| `action` | Action performed |
| `entity_type` | Resource type |
| `entity_id` | Resource UUID |
| `ip_address` | Client IP |
| `created_at` | Timestamp |

Audit logs can be exported as CSV via the admin portal.

## Expected Outcome

After configuring users and RBAC:

- Users can log in with their assigned roles
- RBAC restricts access based on group permissions
- MFA provides additional security for sensitive accounts
- Rate limiting and lockout protect against brute force
- All actions audited for compliance