https://github.com/gpappsoft/keyrad
A Go-based RADIUS server that authenticates users against Keycloak
https://github.com/gpappsoft/keyrad
2fa challenge-response keycloak multifactor-authentication otp radius radius-accounting radius-protocol radius-server security server standalone token2 totp
Last synced: 3 months ago
JSON representation
A Go-based RADIUS server that authenticates users against Keycloak
- Host: GitHub
- URL: https://github.com/gpappsoft/keyrad
- Owner: gpappsoft
- License: apache-2.0
- Created: 2026-01-11T17:54:11.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T13:27:01.000Z (3 months ago)
- Last Synced: 2026-03-30T15:16:12.337Z (3 months ago)
- Topics: 2fa, challenge-response, keycloak, multifactor-authentication, otp, radius, radius-accounting, radius-protocol, radius-server, security, server, standalone, token2, totp
- Language: Go
- Homepage:
- Size: 15.6 MB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# keyrad: Keycloak RADIUS Server
A Go-based RADIUS server that authenticates users against Keycloak, supporting password and OTP (TOTP) flows.
Features include:
- Challenge-response for OTP
- YAML-based Keycloak and RADIUS config
- FreeRADIUS-style `clients.conf` for client secrets
- Optional Message-Authenticator
- Scope/group-to-RADIUS attribute mapping (with regexp support)
- **Vendor-Specific Attributes (VSA):** Return vendor-specific attributes (e.g. MikroTik, Cisco, Ubiquiti) in Access-Accept responses based on user roles, groups, or scopes
- **Configurable OTP mode:** Use standard challenge-response or style
- **Configurable OTP challenge message** via `otp_challenge_message` in config
- **Asynchronous/multi-request support:** Multiple RADIUS requests are handled concurrently for high performance
## Requirements
- Go 1.18+
- A running Keycloak instance (tested with Keycloak 21+)
## Compilation
```bash
git clone https://github.com/gpappsoft/keyrad.git
cd keyrad
go build -o keyrad main.go
```
## Configuration
### 1. Keycloak Setup
- **Create a confidential client** (e.g. `radius-client`) in your realm.
- Enable `Service Accounts Enabled`.
- Enable `Direct Access Grants`.
- Set `Valid Redirect URIs` to `*` (or as needed).
- **Assign roles to the client service account**:
- Go to `Service Account Roles` for your client.
- Assign at least:
- `view-users`
- `query-users`
- `view-realm`
- `view-authorization`
- **User setup**:
- Users must have credentials set for password or OTP (TOTP) as desired.
- To use OTP, users must enroll an OTP device in Keycloak.
### 2. keyrad.yaml
See `keyrad.yaml` for a full example.
- To customize the OTP challenge message, add `otp_challenge_message: "Your custom message"` to `keyrad.yaml`.
- The server supports multiple concurrent RADIUS requests (async worker pool, default 8 workers).
### 3. clients.conf
FreeRADIUS-style client definitions. See `clients.conf` for the format.
### 4. Scope-to-RADIUS Attribute Mapping
Map Keycloak realm roles, groups, or OAuth2 scopes to RADIUS attributes returned in Access-Accept responses. Supports both standard RADIUS attributes and Vendor-Specific Attributes (VSA).
After successful authentication, keyrad extracts the user's roles, groups, and scopes from the Keycloak JWT access token and matches them against the `scope_radius_map` keys.
#### Configuration format
```yaml
scope_radius_map:
# Exact match against role/group/scope name
admin:
- attribute: 6 # Service-Type
value: "6" # Administrative-User
value_type: integer
# Multiple attributes per scope
vpn:
- attribute: 8 # Framed-IP-Address
value: "10.0.0.1"
value_type: ipaddr
- vendor: 14988 # MikroTik Vendor ID
attribute: 3 # Mikrotik-Group
value: "full"
# Vendor-Specific Attributes (VSA)
wifi:
- vendor: 14988 # MikroTik
attribute: 8 # Mikrotik-Rate-Limit
value: "10M/10M"
# Regex matching with "re:" prefix
re:^group_.*:
- attribute: 11 # Filter-Id
value: "group-member"
```
#### Attribute fields
| Field | Required | Description |
|--------------|----------|--------------------------------------------------------------------|
| `vendor` | No | IANA vendor ID. Omit or set to `0` for standard RADIUS attributes. |
| `attribute` | Yes | Attribute type number. |
| `value` | Yes | Attribute value. |
| `value_type` | No | Encoding type: `string` (default), `integer`, or `ipaddr`. |
#### Common vendor IDs
| Vendor | ID | Reference |
|----------|-------|--------------------------------------------------------------|
| Cisco | 9 | [Cisco VSA documentation](https://www.cisco.com) |
| Microsoft| 311 | RFC 2548 |
| MikroTik | 14988 | [MikroTik RADIUS dictionary](https://help.mikrotik.com/docs/spaces/ROS/pages/328097/RADIUS) |
| Ubiquiti | 41112 | Ubiquiti RADIUS dictionary |
#### Keycloak setup for scope/group matching
For roles and scopes, no extra Keycloak configuration is needed -- they are included in the JWT by default.
For **group-based matching**, add a "groups" protocol mapper to your Keycloak client:
1. Go to your client's **Client Scopes** > **Dedicated scope** > **Add mapper** > **By configuration** > **Group Membership**.
2. Set **Token Claim Name** to `groups`.
3. Disable **Full group path** if you want short group names.
## Usage
### Start the server
```bash
./keyrad -c keyrad.yaml -r clients.conf
```
- Use `--disable-message-authenticator` to disable Message-Authenticator checks (for legacy clients).
- Use `--disable-challenge-response` to allow OTP users to authenticate with `` in the User-Password field (no challenge-response).
- Use `--version` to print version and author.
### Test with radtest
```bash
radtest testuser password 127.0.0.1 0 test
```
- For OTP (default): Enter password first, then respond to challenge with OTP code (customizable message).
- For OTP with `--disable-challenge-response`: Enter `` as the password (e.g. `mypassword123456`).
## Advanced Features
- **Challenge-response**: Standard RADIUS Access-Challenge for OTP, or disable for legacy OTP style.
- **Configurable OTP challenge message**: Set `otp_challenge_message` in your config for custom challenge text.
- **Scope/group mapping**: Map Keycloak realm roles, groups, or OAuth2 scopes to RADIUS attributes. Supports regexp keys (e.g. `re:^group_.*`).
- **Vendor-Specific Attributes (VSA)**: Return vendor-specific attributes in Access-Accept based on user roles/groups. Supports any vendor by IANA vendor ID (e.g. MikroTik 14988, Cisco 9, Microsoft 311).
- **TLS verification**: Set `insecure_skip_tls_verify: true` for self-signed Keycloak certs.
- **Asynchronous/multi-request support**: Multiple RADIUS requests are handled concurrently for high performance.
## Troubleshooting
- **403 errors**: Ensure your Keycloak client has the correct service account roles.
- **Invalid Message-Authenticator**: Check shared secrets in `clients.conf` and your RADIUS client.
- **OTP not working**: Ensure user has the credential enrolled in Keycloak.
- **Legacy OTP**: If your client cannot handle RADIUS challenge-response, use `--disable-challenge-response`.
## Support
If you need professional support, please write to
[info@sec73.io](mailto:info@sec73.io)
## Disclaimer
This project is provided as-is, without warranty of any kind. Use at your own risk. The maintainers are not responsible for any damage, data loss, or security issues resulting from the use or misuse of this software. Always review and test in a safe environment before deploying to production.
## License
Apache-2.0