Trusona RADIUS Appliance User Guide (Docker)

Getting up and running with the Trusona RADIUS appliance on Docker

By Tom Piscitell
Updated May 29, 2019

1. What’s in this doc

• 1. Introduction
• 2. Deployment modes
• 3. Password encoding and LDAP mode
• 4. Docker images
  • 4.1. quay.io/trusona/radius
  • 4.2. quay.io/trusona/radius-api
• 5. Network requirements
• 6. Deploying with docker-compose
• 7. Deploying with kubernetes
• 8. Using RADIUS to issue Trusonafications

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.

---