{"id":22975920,"url":"https://github.com/chornthorn/khode-two-factor-auth","last_synced_at":"2025-04-02T08:14:26.899Z","repository":{"id":262303558,"uuid":"886826732","full_name":"chornthorn/khode-two-factor-auth","owner":"chornthorn","description":"khode-2fa is a Keycloak extension that provides a REST API for managing Time-based One-Time Password (TOTP) authentication. ","archived":false,"fork":false,"pushed_at":"2024-11-19T01:49:09.000Z","size":59,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-07T22:49:56.309Z","etag":null,"topics":["2fa-mobile","2fa-security","keycloak","keycloak-extension","keycloak-rest-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chornthorn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-11T17:14:07.000Z","updated_at":"2024-12-20T21:02:36.000Z","dependencies_parsed_at":"2024-11-11T18:33:22.579Z","dependency_job_id":"fa26b9ee-57e8-41fc-9082-bc6b451c4776","html_url":"https://github.com/chornthorn/khode-two-factor-auth","commit_stats":null,"previous_names":["chornthorn/khode-two-factor-auth"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chornthorn%2Fkhode-two-factor-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chornthorn%2Fkhode-two-factor-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chornthorn%2Fkhode-two-factor-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chornthorn%2Fkhode-two-factor-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chornthorn","download_url":"https://codeload.github.com/chornthorn/khode-two-factor-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246777833,"owners_count":20832032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2fa-mobile","2fa-security","keycloak","keycloak-extension","keycloak-rest-api"],"created_at":"2024-12-15T00:40:45.541Z","updated_at":"2025-04-02T08:14:26.874Z","avatar_url":"https://github.com/chornthorn.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keycloak 2FA Rest API Extension\n\nkhode-2fa is a Keycloak extension that provides a REST API for managing Time-based One-Time Password (TOTP)\nauthentication. This extension allows you to set up, verify, enable, disable, and validate TOTP for users in a Keycloak\nrealm.\n\n## Features\n\n- Check if TOTP is configured for a user\n- Setup TOTP for a user\n- Verify and enable TOTP\n- Get TOTP status for a user\n- Validate TOTP code\n- Disable TOTP for a user\n- Flexible authentication support:\n   - Client credentials (service account) authentication\n   - User token authentication\n   - Per-endpoint authorization controls\n\nThis extension is designed to integrate seamlessly with existing Keycloak deployments, offering developers and\nadministrators greater flexibility in implementing and managing 2FA.\n\n## Installation\n\nYou can either build the JAR file from source or download a pre-built version from the releases page.\n\n### Option 1: Download from Releases\n\n1. Go to the [Releases](https://github.com/chornthorn/khode-two-factor-auth/releases) page\n2. Download the latest `khode-two-factor-auth-x.x.x.jar` file (e.g. `khode-two-factor-auth-1.1.0.jar`)\n3. Copy the JAR file to your Keycloak deployments directory:\n\n   ```\n   cp khode-two-factor-auth-1.1.0.jar /path/to/keycloak/providers/\n   ```\n\n### Option 2: Build from Source\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/chornthorn/khode-two-factor-auth.git\n   ```\n\n2. Change to the project directory:\n   ```\n   cd khode-two-factor-auth\n   ```\n\n3. Build the project using Maven:\n   ```\n   mvn clean package\n   ```\n\n4. Copy the resulting JAR file to the Keycloak deployments directory:\n   ```\n   cp target/khode-two-factor-auth-[version-number].jar /path/to/keycloak/providers/\n   ```\n\nAfter installing using either method, restart Keycloak to load the new extension.\n\n## Usage\n\nThis extension provides the following REST endpoints for managing TOTP authentication.\n\n**Note:** Requirement for before using it:\n   - Simple URL: `http://keycloak-server:[port]/realms/{realm}/khode-2fa`\n   - Replace `{realm}` and `{user_id}` with the appropriate values.\n\n**Authentication Requirements:**\n- The API supports two authentication methods:\n   1. Client Credentials (Service Account):\n      - Requires a bearer token from a service account\n      - Can access any user's TOTP settings\n   2. User Token:\n      - Requires a bearer token from a regular user\n      - Can only access their own TOTP settings\n- All requests must include an `Authorization: Bearer \u003ctoken\u003e` header\n\n### Authentication Examples\n\n**Using Client Credentials:**\n```bash\n# Get service account token\nTOKEN=$(curl -X POST \\\n  \"http://keycloak-server/realms/master/protocol/openid-connect/token\" \\\n  -d \"grant_type=client_credentials\" \\\n  -d \"client_id=your-client\" \\\n  -d \"client_secret=your-secret\" \\\n  | jq -r '.access_token')\n```\n\n**Using User Token:**\n```bash\n# Get user token\nTOKEN=$(curl -X POST \\\n  \"http://keycloak-server/realms/master/protocol/openid-connect/token\" \\\n  -d \"grant_type=password\" \\\n  -d \"client_id=your-client\" \\\n  -d \"username=your-username\" \\\n  -d \"password=your-password\" \\\n  | jq -r '.access_token')\n```\n\n### Setup TOTP\n\n```http\nPOST /realms/{realm}/khode-2fa/totp/setup/{user_id}\n```\n\nReturns:\n\n```json\n{\n  \"secret\": \"BASE32_ENCODED_SECRET\",\n  \"qrCode\": \"otpauth://totp/...\",\n  \"policy\": {\n    \"algorithm\": \"HmacSHA1\",\n    \"digits\": 6,\n    \"period\": 30,\n    \"type\": \"totp\"\n  },\n  \"supportedApplications\": [\n    \"FreeOTP\",\n    \"Google Authenticator\"\n  ],\n  \"userId\": \"user-123\",\n  \"code\": 0\n}\n```\n\nGenerates a TOTP secret for the user and returns the secret and QR code.\n\n### Verify and Enable TOTP\n\n```http\nPOST /realms/{realm}/khode-2fa/totp/verify/{user_id}\nContent-Type: application/json\n\n{\n    \"code\": \"123456\"\n}\n```\n\nReturns:\n\n```json\n{\n  \"message\": \"TOTP enabled successfully\",\n  \"enabled\": true,\n  \"code\": 0\n}\n```\n\nVerifies the TOTP code and enables TOTP for the user.\n\n### Get TOTP Status\n\n```http\nGET /realms/{realm}/khode-2fa/totp/status/{user_id}\n```\n\nReturns:\n\n```json\n{\n  \"enabled\": true,\n  \"message\": \"TOTP is configured for this user\",\n  \"userId\": \"user-123\",\n  \"code\": 0\n}\n```\n\nReturns the TOTP status and credentials for the user.\n\n### Validate TOTP Code\n\n```http\nPOST /realms/{realm}/khode-2fa/totp/validate/{user_id}\nContent-Type: application/json\n\n{\n    \"code\": \"123456\"\n}\n```\n\nReturns:\n\n```json\n{\n  \"message\": \"TOTP code validated successfully\",\n  \"valid\": true,\n  \"userId\": \"user-123\",\n  \"code\": 0\n}\n```\n\nValidates the TOTP code for an existing TOTP setup.\n\n### Disable TOTP\n\n```http\nDELETE /realms/{realm}/khode-2fa/totp/{user_id}\n```\n\nReturns:\n\n```json\n{\n  \"message\": \"TOTP disabled successfully\",\n  \"enabled\": false,\n  \"userId\": \"user-123\",\n  \"code\": 0\n}\n```\n\nDisables TOTP for the user.\n\n### Disable TOTP with Validation (Disable with single endpoint request)\n\n```http\nPOST /realms/{realm}/khode-2fa/totp/disable-with-validation/{user_id}\nContent-Type: application/json\n\n{\n    \"code\": \"123456\"\n}\n```\n\nReturns:\n\n```json\n{\n  \"message\": \"TOTP validated and disabled successfully\",\n  \"enabled\": false,\n  \"userId\": \"user-123\",\n  \"code\": 0\n}\n```\n\nValidates the TOTP code before disabling TOTP for the user. This provides an additional security layer when disabling 2FA.\n\n## Error Handling\n\nThe extension provides appropriate error responses for various scenarios, such as invalid codes, missing TOTP setup,\netc.\n\n### API Response Codes\n\nAll API endpoints return a standardized `code` field in their responses. Here's what each code means:\n\n| Code | Description | Common Scenarios |\n|------|-------------|------------------|\n| 0 | Success | Operation completed successfully |\n| 1 | Invalid User ID | Missing or malformed user ID |\n| 2 | Invalid Code Format | TOTP code is missing or malformed |\n| 3 | TOTP Not Enabled | Attempting operations on non-enabled TOTP |\n| 4 | TOTP Already Enabled | Attempting to enable already configured TOTP |\n| 5 | Server Error | Unexpected server-side errors |\n| 6 | TOTP Setup Required | Trying to verify without setup |\n| 7 | Invalid TOTP Code | Incorrect TOTP code provided |\n| 8 | Operation Failed | Failed to complete the requested operation |\n| 9 | Unauthorized | Missing or invalid authentication |\n| 10 | Forbidden | Insufficient permissions or access denied |\n\n## Compatibility Matrix\n\nThis table shows the compatibility between Keycloak versions and khode-2fa extension versions.\n\n| Keycloak Version | khode-2fa Version | Status      | Testing Status |\n|-----------------|-------------------|-------------|----------------|\n| 26.0.x          | 1.4.x            | ✅ Supported | ✅ Tested       |\n| 25.0.x          | 1.4.x            | ✅ Supported | ✅ Tested       |\n| 24.0.x          | 1.4.x            | ⚠️ Limited   | 🧪 In Testing   |\n| 23.0.x          | 1.4.x            | ⚠️ Limited   | ❌ Untested     |\n| 22.0.x          | 1.4.x            | ⚠️ Limited   | ❌ Untested     |\n| \u003c 22.0.0        | \u003c 1.4.x          | ❌ Unsupported| ❌ Untested     |\n\n### Notes\n\n- **Status**\n    - ✅ Supported: Fully tested and supported version combinations\n    - ⚠️ Limited: Should work but not officially tested\n    - ❌ Unsupported: Not tested or known to have compatibility issues\n\n- **Testing Status**\n    - ✅ Tested: Fully tested with automated and manual testing\n    - 🧪 In Testing: Currently undergoing testing\n    - ❌ Untested: No testing performed\n\n### Recommendations\n\n- For production use, we recommend using Keycloak 25.0.x or 26.0.x with khode-2fa 1.4.x\n- Other version combinations may work but are not officially tested\n\n## Dependencies\n\n- Keycloak\n- Jakarta RESTful Web Services (JAX-RS)\n- Microprofile OpenAPI\n- Lombok\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchornthorn%2Fkhode-two-factor-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchornthorn%2Fkhode-two-factor-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchornthorn%2Fkhode-two-factor-auth/lists"}