Identity & Auth

{
  "overview": "# Identity Service Documentation\n\nThe **identity** service is a critical component of the Vivified platform, responsible for user authentication and identity management. This service is designed to be secure, scalable, and HIPAA-compliant, ensuring that sensitive information is protected according to regulatory standards.\n\n## Key Features\n- JWT-based authentication\n- Role-based access control\n- Multi-factor authentication (MFA)\n\n!!! note\n    This service is part of the Vivified Phase 2 deployment and includes FastAPI dependencies to protect endpoints.\n\n## Architecture\n\n```mermaid\ngraph TD;\n    A[User] -->|Requests Access| B[Identity Service];\n    B -->|Validates Credentials| C[JWT Token];\n    C -->|Returned to| A;\n    A -->|Uses JWT| D[Protected Resource];\n```\n\n## Security Considerations\n- Ensure that all JWT tokens are signed with a secure algorithm.\n- Regularly rotate encryption keys and secrets.\n- Implement MFA for enhanced security.\n\n!!! warning\n    Never expose JWT tokens or secrets in client-side code.\n\n## Troubleshooting\n\n1. **Issue**: Users cannot log in.\n   - **Solution**: Verify if the user account is active and the password is correct.\n\n2. **Issue**: JWT token expiration issues.\n   - **Solution**: Check server time synchronization and token expiration settings.\n\n3. **Issue**: MFA not working as expected.\n   - **Solution**: Ensure the MFA secret is correctly configured in the user profile.\n",
  "api": "# API Reference\n\n## Endpoints\n\n### Authentication\n\n- **POST /auth/login**\n  - Description: Authenticate a user and return a JWT token.\n  - Request Body:\n    ```json\n    {\n      \"username\": \"string\",\n      \"password\": \"string\"\n    }\n    ```\n  - Response:\n    ```json\n    {\n      \"token\": \"string\"\n    }\n    ```\n\n- **GET /auth/validate**\n  - Description: Validate a provided JWT token.\n  - Request Header:\n    ```\n    Authorization: Bearer <token>\n    ```\n  - Response:\n    ```json\n    {\n      \"valid\": true\n    }\n    ```\n\n## Models\n\n### User\n- **Fields**:\n  - `id`: UUID\n  - `username`: string\n  - `email`: string\n  - `password_hash`: string\n  - `mfa_enabled`: boolean\n  - `is_active`: boolean\n",
  "config": "# Configuration Guide\n\n## Environment Variables\n\n| Variable Name        | Description                     | Default Value |\n|----------------------|---------------------------------|---------------|\n| `JWT_SECRET`         | Secret key for JWT signing      | `change_me`   |\n| `JWT_ALGORITHM`      | Algorithm for JWT signing       | `HS256`       |\n| `DB_CONNECTION`      | Database connection string      | `postgresql://user:pass@localhost/db` |\n| `MFA_REQUIRED`       | Enforce MFA for all users       | `false`       |\n\n!!! tip\n    Ensure all environment variables are set in a secure manner and not hard-coded in your application code.\n",
  "examples": "# Usage Examples\n\n=== \"Python\"\n\n    ```python\n    import requests\n\n    response = requests.post('https://api.vivified.com/auth/login', json={\n        'username': 'user@example.com',\n        'password': 'securepassword'\n    })\n    token = response.json()['token']\n    headers = {'Authorization': f'Bearer {token}'}\n    validation_response = requests.get('https://api.vivified.com/auth/validate', headers=headers)\n    print(validation_response.json())\n    ```\n\n=== \"curl\"\n\n    ```bash\n    curl -X POST https://api.vivified.com/auth/login \\\n         -H \"Content-Type: application/json\" \\\n         -d '{\"username\": \"user@example.com\", \"password\": \"securepassword\"}'\n\n    token=\"<JWT_TOKEN>\"\n\n    curl -X GET https://api.vivified.com/auth/validate \\\n         -H \"Authorization: Bearer $token\"\n    ```\n"
}