[DOCS][AUTH]: Administrator Password Reset & Recovery Guide

# 📚 Documentation: Administrator Password Reset & Recovery Guide

## Goal

Create comprehensive **documentation for administrators** on all available methods to reset user passwords and recover account access. This guide covers emergency recovery procedures, Helm-based resets, database operations, and API-based methods to ensure administrators can restore access in any scenario.

## Why Now?

Recent user reports (#2539) highlight the need for clear documentation on password recovery:

1. **Knowledge Gap**: Administrators are unsure how to reset passwords in Kubernetes/Helm deployments
2. **Emergency Preparedness**: Organizations need documented procedures for account lockouts
3. **Self-Service Gaps**: Until self-service reset is implemented (#2542), admins must handle all resets
4. **Compliance Requirements**: SOC2 and ISO 27001 require documented access recovery procedures
5. **Onboarding**: New administrators need clear guidance on user management tasks
6. **Multi-Environment**: Recovery procedures differ between Docker, Kubernetes, and bare-metal deployments

---

## 📖 User Stories

<details>
<summary>US-1: Platform Admin - Reset User Password via Admin UI</summary>

**As a** platform administrator
**I want** step-by-step instructions for resetting passwords via Admin UI
**So that** I can quickly help users who have forgotten their passwords

**Documentation Requirements:**

```gherkin
Feature: Admin UI Password Reset Documentation

 Scenario: Document Admin UI reset flow
 Given the documentation is complete
 Then it should include:
 | Section | Content |
 | Prerequisites | Admin account with user_management permission |
 | Navigation | Admin Panel → Users → Select User → Edit |
 | Password Field | Enter new password (leave blank to keep) |
 | Confirmation | Re-enter password to confirm |
 | Validation | Password policy requirements shown |
 | Success Indication | "User updated successfully" message |
 | User Communication | Template email to notify user |

 Scenario: Document common errors
 Then error documentation should include:
 | Error | Cause | Solution |
 | "Passwords do not match" | Typo in confirmation | Re-enter carefully |
 | "Password validation failed" | Doesn't meet policy | Use stronger password |
 | "Cannot modify last admin" | Preventing lockout | Create another admin |
```

</details>

<details>
<summary>US-2: DevOps Engineer - Reset Password via Helm/Kubernetes</summary>

**As a** DevOps engineer
**I want** instructions for resetting the admin password in Kubernetes deployments
**So that** I can recover access when locked out of the Admin UI

**Documentation Requirements:**

```gherkin
Feature: Kubernetes Password Reset Documentation

 Scenario: Document Helm values.yaml reset method
 Given the documentation is complete
 Then it should include:
 | Step | Action |
 | 1 | Edit values.yaml: PLATFORM_ADMIN_PASSWORD |
 | 2 | Run: helm upgrade mcp-stack . -f values.yaml -n ns |
 | 3 | Wait for pods to restart |
 | 4 | Login with new password |

 Scenario: Document direct database reset method
 Then it should include kubectl commands for:
 | Step | Command Purpose |
 | 1 | Generate Argon2id hash via gateway pod |
 | 2 | Connect to PostgreSQL pod |
 | 3 | UPDATE email_users SET password_hash=... |
 | 4 | Clear lockout: failed_login_attempts=0, locked_until=NULL |

 Scenario: Document account unlock procedure
 Then it should include:
 | Scenario | Command |
 | Unlock account | UPDATE email_users SET locked_until=NULL... |
 | Reset attempts | UPDATE email_users SET failed_login_attempts=0 |
 | Clear change flag | UPDATE email_users SET password_change_required=false |
```

</details>

<details>
<summary>US-3: Security Admin - API-Based Password Reset</summary>

**As a** security administrator
**I want** documentation for programmatic password resets
**So that** I can integrate with our identity management systems

**Documentation Requirements:**

```gherkin
Feature: API Password Reset Documentation

 Scenario: Document REST API reset
 Given the documentation is complete
 Then it should include:
 | Endpoint | Method | Purpose |
 | /auth/email/admin/users/{email} | PUT | Update user password |
 | /auth/email/change-password | POST | User self-change |

 Scenario: Document API examples
 Then it should include curl examples for:
 | Action | Authentication Required |
 | Admin resets user password | Admin JWT token |
 | User changes own password | User JWT token |

 Scenario: Document JWT token generation
 Then it should include:
 | Method | Use Case |
 | python -m mcpgateway.utils.create_jwt_token | Generate admin token |
 | /auth/email/login endpoint | Standard login flow |
```

</details>

<details>
<summary>US-4: Operations Team - Emergency Recovery Procedures</summary>

**As an** operations team member
**I want** documented emergency procedures for complete lockout scenarios
**So that** I can restore access even when all admin accounts are locked

**Documentation Requirements:**

```gherkin
Feature: Emergency Recovery Documentation

 Scenario: Document complete lockout recovery
 Given all admin accounts are locked or passwords unknown
 Then documentation should cover:
 | Step | Recovery Action |
 | 1 | Access database directly (kubectl exec) |
 | 2 | Identify admin accounts: SELECT * FROM email_users |
 | 3 | Generate new password hash |
 | 4 | Update password and clear lockout flags |
 | 5 | Verify login works |
 | 6 | Document incident per security policy |

 Scenario: Document bootstrap re-initialization
 Then documentation should cover:
 | Method | When to Use |
 | Change PLATFORM_ADMIN_PASSWORD | Admin password unknown |
 | helm upgrade | Apply new password via bootstrap |
 | Database verification | Confirm password was updated |
```

</details>

---

## 📋 Documentation Structure

### Proposed Documentation Outline

```
docs/
└── administration/
 └── password-management.md
 ├── Overview
 │ ├── Password Storage (Argon2id)
 │ ├── Password Policy Configuration
 │ └── Account Lockout Settings
 │
 ├── Admin UI Password Reset
 │ ├── Prerequisites
 │ ├── Step-by-Step Guide
 │ ├── Screenshots
 │ └── Troubleshooting
 │
 ├── Kubernetes/Helm Password Reset
 │ ├── Method 1: Helm Values Update
 │ ├── Method 2: Direct Database Update
 │ ├── Generating Password Hashes
 │ └── Unlocking Accounts
 │
 ├── API-Based Password Management
 │ ├── Authentication Requirements
 │ ├── Endpoint Reference
 │ ├── curl Examples
 │ └── Python SDK Examples
 │
 ├── Emergency Recovery
 │ ├── Complete Lockout Scenario
 │ ├── Bootstrap Re-initialization
 │ ├── Database Recovery Commands
 │ └── Post-Recovery Checklist
 │
 └── Appendix
 ├── Password Policy Reference
 ├── Environment Variables
 ├── SQL Command Reference
 └── Security Considerations
```

---

## 📋 Implementation Tasks

### Phase 1: Core Documentation
- [ ] Create `docs/administration/password-management.md`
- [ ] Write Overview section (password storage, policy, lockout)
- [ ] Document Admin UI password reset with screenshots
- [ ] Document password policy configuration options

### Phase 2: Kubernetes/Helm Documentation
- [ ] Document Helm values.yaml password reset method
- [ ] Document direct database reset with kubectl commands
- [ ] Create script for generating Argon2id hashes
- [ ] Document account unlock procedures
- [ ] Add troubleshooting for multi-replica deployments

### Phase 3: API Documentation
- [ ] Document REST API endpoints for password management
- [ ] Add curl examples with proper authentication
- [ ] Add Python SDK examples
- [ ] Document JWT token generation for automation

### Phase 4: Emergency Procedures
- [ ] Document complete lockout recovery procedure
- [ ] Document bootstrap re-initialization method
- [ ] Create emergency recovery checklist
- [ ] Add incident documentation template

### Phase 5: Review & Polish
- [ ] Technical review by security team
- [ ] Test all documented procedures
- [ ] Add to mkdocs navigation
- [ ] Cross-reference from Helm chart README
- [ ] Add FAQ section based on user questions

---

## 📝 Key Content to Include

### Password Hash Generation (kubectl)

```bash
# Generate Argon2id hash for a new password
kubectl exec -n mcp-private -it $(kubectl get pod -n mcp-private \
 -l app.kubernetes.io/name=mcp-context-forge -o jsonpath='{.items[0].metadata.name}') -- \
 python3 -c "
from mcpgateway.services.argon2_service import Argon2PasswordService
import asyncio
password = 'YourNewSecurePassword123!'
hash = asyncio.run(Argon2PasswordService().hash_password_async(password))
print(hash)
"
```

### Database Password Reset (kubectl)

```bash
# Connect to PostgreSQL and reset password
kubectl exec -n mcp-private -it $(kubectl get pod -n mcp-private \
 -l app.kubernetes.io/component=postgresql -o jsonpath='{.items[0].metadata.name}') -- \
 psql -U admin -d postgresdb -c "
UPDATE email_users 
SET password_hash = 'PASTE_HASH_HERE',
 password_change_required = false,
 failed_login_attempts = 0,
 locked_until = NULL,
 password_changed_at = NOW()
WHERE email = 'admin@example.com';
"
```

### Helm Bootstrap Reset

```bash
# Update values.yaml
mcpContextForge:
 secret:
 PLATFORM_ADMIN_PASSWORD: "NewSecurePassword123!"

# Apply changes
helm upgrade mcp-stack . -f values.yaml -n mcp-private

# Verify pods restarted
kubectl rollout status deployment/mcp-context-forge -n mcp-private
```

### API Password Reset

```bash
# Generate admin JWT token
export TOKEN=$(python -m mcpgateway.utils.create_jwt_token \
 --username admin@example.com --exp 60 --secret $JWT_SECRET_KEY)

# Reset user password via API
curl -X PUT "https://mcp.example.com/auth/email/admin/users/user%40example.com" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "full_name": "User Name",
 "password": "NewUserPassword123!"
 }'
```

---

## ✅ Success Criteria

- [ ] Documentation covers all password reset methods
- [ ] Kubernetes/Helm procedures tested and verified
- [ ] API examples work correctly
- [ ] Emergency recovery procedure validated
- [ ] Screenshots included for Admin UI steps
- [ ] Reviewed by security team
- [ ] Added to mkdocs site navigation
- [ ] FAQ addresses common issues from #2539

---

## 🔗 Related Issues

- #2539 - Login fails after password reset (user report that highlighted need)
- #2542 - Self-service password reset workflow (future feature)
- Helm chart documentation

---

## 📚 References

- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
- [Argon2 Password Hashing](https://argon2.online/)
- [Kubernetes kubectl exec documentation](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS][AUTH]: Administrator Password Reset & Recovery Guide #2543

📚 Documentation: Administrator Password Reset & Recovery Guide

Goal

Why Now?

📖 User Stories

📋 Documentation Structure

Proposed Documentation Outline

📋 Implementation Tasks

Phase 1: Core Documentation

Phase 2: Kubernetes/Helm Documentation

Phase 3: API Documentation

Phase 4: Emergency Procedures

Phase 5: Review & Polish

📝 Key Content to Include

Password Hash Generation (kubectl)

Database Password Reset (kubectl)

Helm Bootstrap Reset

API Password Reset

✅ Success Criteria

🔗 Related Issues

📚 References

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[DOCS][AUTH]: Administrator Password Reset & Recovery Guide #2543

Description

📚 Documentation: Administrator Password Reset & Recovery Guide

Goal

Why Now?

📖 User Stories

📋 Documentation Structure

Proposed Documentation Outline

📋 Implementation Tasks

Phase 1: Core Documentation

Phase 2: Kubernetes/Helm Documentation

Phase 3: API Documentation

Phase 4: Emergency Procedures

Phase 5: Review & Polish

📝 Key Content to Include

Password Hash Generation (kubectl)

Database Password Reset (kubectl)

Helm Bootstrap Reset

API Password Reset

✅ Success Criteria

🔗 Related Issues

📚 References

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions