1. Introduction
For use with VPNs, and other Network Access Systems, Trusona provides Docker containers that can be used to issue Trusonafications via RADIUS. These docker containers are publicly available on quay.io, but require Trusona API Tokens to communicate with Trusona.
One docker container (quay.io/trusona/radius) acts as a RADIUS Server and accepts RADIUS requests with email addresses as usernames. The second container (quay.io/trusona/radius-api) handles all communication with Trusona’s backend APIs. They communicate with each other over port 8080 and need to be linked together when using Docker Swarm.
2. Deployment modes
The containers can be deployed in two different modes, Trusona Only, and LDAP Mode. Trusona Only mode expects email addresses as the RADIUS username and issues Trusonafications to the Trusona user who owns that email address. In LDAP mode, the RADIUS server will attempt to validate credentials against an LDAP server.
Whether or not credential validation against LDAP can be performed depends on the password encoding scheme used in the RADIUS request. See Password Encoding and LDAP Mode for more information. It will also use that server to lookup the user’s email address. This email address will then be issued a Trusonafication.
By default, the containers operate in Trusona Only mode. LDAP can be enabled via environment variables of the radius-api image.
3. Password encoding and LDAP mode
In order for the RADIUS containers to be able to verify the user’s password in LDAP mode, the RADIUS Access-Request must use PAP. If PAP is not able to be used, we also support MSCHAP and MSCHAPv2 without password validation via LDAP. We will still lookup the user in LDAP to find their email address, and check that they are a member of the configured LDAP Group, but we are unable to verify their password with the LDAP server.
If you want to verify the provided password, you must do so outside of the RADIUS transaction.
4. Docker images
4.1. quay.io/trusona/radius
A RADIUS server that exposes ports 1812/udp and 1813/udp to accept RADIUS Access-Requests. This image will need to communicate with the quay.io/trusona/radius-api image in order to issue Trusonafications. It exposes a volume that is used to provide the RADIUS client configuration. This is where you will define what clients can connect to the RADIUS service and what secret they will use.
The volume is defined for /etc/raddb/config, and the image expects it to contain a file called clients.conf. The file should contain a list of client entries that fit the following form:
client <name> {
ipaddr = <ipaddr>
secret = <secret>
}
The ipaddr can be a single IP Address, a network expressed in CIDR notation (10.0.0.0/24), or a * to indicate all clients. For example, you can specify a shared secret for a specific network range, and then a default one for all others:
client subnetA {
ipaddr = 10.0.100.0/24
secret = go2vgjQQZWPLkEsrm
}
client default {
ipaddr = *
secret = HUrpbEBojkgBrjywU2A
}
4.2. quay.io/trusona/radius-api
The radius-api image handle all communication with Trusona and is configured via environment variables. The variables are:
| Variable | Required? | Description |
|---|---|---|
| TRUSONA_API_HOST | Yes | A URL for the Trusona API To talk to (default: https://api.trusona.net) |
| TRUSONA_TOKEN | Yes | Your Trusona API Token |
| TRUSONA_SECRET | Yes | Your Trusona API Secret |
| TRUSONA_TIMEOUT | No | How long to wait for the Trusonafication to be accepted. (default: 60) |
| TRUSONA_EMAIL_DOMAIN | No | If configured, this domain will be appended to RADIUS usernames to create an email address. Ex. if set to example.com, and the RADIUS request is for user, the email address user@example.com will be Trusonafied. |
| TRUSONA_LDAP_ENABLED | No | Set this to enable Trusona with LDAP. See Deployment Modes above for more information. |
| LDAP_HOST | No* | The IP Address or Hostname of the LDAP Server |
| LDAP_PORT | No* | The port of the LDAP Server |
| LDAP_BIND_DN | No* | The DN to use when binding to LDAP for user lookups |
| LDAP_BIND_PW | No* | The password to use when binding to LDAP for user lookups |
| LDAP_USER_ATTR | No* | The user attribute that holds the username being sent in the RADIUS request |
| LDAP_BASE_DN | No* | A Base DN to use when looking up users |
| LDAP_GROUP_DN | No | A group that users must be a member of to be authorized |
| LDAP_TLS | No | Set this to use TLS when communicating with the LDAP server |
| LDAP_TLS_NO_VERIFY | No | Set this to disable TLS certificate verification when communicating with the LDAP server |
*Required when using Trusona with LDAP
5. Network requirements
The radius container exposes 1812/udp and 1813/udp and those ports must be reachable by the downstream service that is issuing RADIUS requests. The radius-api needs external access on port 443 so it can reach the Trusona Backend Services via HTTPS.
6. Deploying with docker-compose
The following is an example Docker Compose file to illustrate how to deploy the containers:
version: '3'
services:
radius:
image: quay.io/trusona/radius:latest
links:
- radius-api
ports:
- "1812-1813:1812-1813/udp"
command: "-x"
volumes:
- ./config:/etc/raddb/config:ro
radius-api:
image: quay.io/trusona/radius-api:latest
env_file:
- ./credentials.env
The local folder config should contain a clients.conf file. Here is an example one that sets the RADIUS secret to “shared-secret” for all clients:
client all {
ipaddr = *
secret = shared-secret
}
The environment variables for the radius-api container are provided by the credentials.env which is a list of environment variables in the format of <variable>=value. Here is an example credentials.env file:
TRUSONA_API_HOST=https://api.trusona.net
TRUSONA_TIMEOUT=60
TRUSONA_TOKEN=token-goes-here
TRUSONA_SECRET=secret-goes-here
This file will contain your Trusona API Token and Secret which is how you authenticate to trusona. It is important to prevent unauthorized access to the env file.
7. Deploying with kubernetes
In the manifests/ directory, we provide some sample Kubernetes Manifests that you can use to deploy the containers. They are:
| Name | Description |
|---|---|
000-namespace.yaml |
Creates a namespace called “trusona” where the app gets deployed to |
configmap.yaml |
Config map that provides the clients.conf file. Edit this to provide your RADIUS secret. |
deployment.yaml |
The deployment definition. Edit this file to configure the Environment variables for the radius-api container |
service.yaml |
The service definition that exposes 1812/udp and 1813/udp. It is currently a LoadBalancer, you may need to change this as needed for your specific deployment (Ex. ClusterIP, NodePort) |
After editing the above files as needed you can apply with kubectl:
kubectl apply -f manifests/
8. Using RADIUS to issue Trusonafications
Sending the email address as the User-Name attribute will create a trusonafication for the Trusona user with that email address.. For example, you could use radclient to send a trusonafication to test@example.com with the following command:
echo "User-Name=test@example.com,User-Password=trusona" | radclient -r1 -t65 $SERVICE_IP auth $RADIUS_SECRET
Even though Trusona does not use passwords, you will still need to send a RADIUS request with the User-Password attribute for the request to work.