Trusona RADIUS Appliance User Guide (CentOS)

Getting up and running with the Trusona RADIUS appliance on CentOS

What’s in this doc

Introduction

The Trusona RADIUS Appliance is a Linux service that allows you to integrate Trusona into your existing environment using RADIUS. It has two operating main operating modes, Trusona Only and LDAP Modes.

In Trusona Only mode, the appliance expects email addresses as the RADIUS User-Name attribute the Trusona user with that email address will be receive a push notification on their phone asking them to either accept or reject the authentication request. The appliance can also be configured to append an email domain to the RADIUS User-Name attribute to form a complete email address. This allows users to enter just the username instead of the full email address when authenticating.

In LDAP Mode, the appliance will use LDAP to both authenticate users and lookup their email address for use with Trusona. This enables a near drop in replacement for existing setups that authenticate users against an LDAP store, like Active Directory. The appliance can also be configured to verify that users are members of an LDAP group when authenticating them. More information on LDAP mode can be found later in this document in the LDAP Mode section.

Quick start

  1. Enable the EPEL Repository by running the following command.
    sudo yum install -y epel-release
    
  2. Install Docker CE. The exact steps vary slightly by the Linux distribution you are running. The following commands are for CentOS 7, for other distributions see the Docker CE Install Documentation.
      sudo yum install -y yum-utils \
       device-mapper-persistent-data \
       lvm2
      sudo yum-config-manager \
      --add-repo \
      https://download.docker.com/linux/centos/docker-ce.repo
      sudo rpm --import https://download.docker.com/linux/centos/gpg
      sudo yum install -y docker-ce docker-ce-cli containerd.io
    
  3. Install the Trusona RADIUS service using the provided RPM file.
    sudo yum install -y trusona-radius-v1.1.1-1.noarch.rpm
    
  4. Configure the RADIUS service with configure service. You will need your RADIUS Secret, Trusona API Token, and Trusona API Secret.
    sudo configure service
    
  5. Start the RADIUS services with sudo trusona-service start
    sudo trusona-service start
    

When the command finishes, networking will be restarted and DHCP will be used Once the services start, the appliance will accept RADIUS requests on port 1812

Configuring the RADIUS service

  1. Run configure service
  2. Enter your RADIUS secret
  3. Hit Enter to accept the default API Host of https://api.trusona.net
  4. Enter a timeout value for RADIUS requests, or hit enter to accept the default of 60.
  5. Enter your Trusona API Token
  6. Enter your Trusona API Secret
  7. Enter y or n to enable or disable the Email Domain feature. See Appending an Email Domain for more information.
    1. If you answered y, enter an email domain to be appended.
  8. Enter y or n to enable or disable LDAP Mode. See LDAP Mode for more information. If you answered y:
    1. Enter the LDAP Host
    2. Enter the LDAP Port
    3. Enter the LDAP User Attribute that matches the RADIUS User-Name received by the appliance or hit enter to accept the default of sAMAccountName.
    4. Enter a Base DN that users exist under. The whole subtree will be searched for users.
    5. Enter a DN that can bind to the LDAP Host and search for users.
    6. Enter the password for the Bind DN.
    7. Enter y to have the appliance check that users belong to a specific LDAP Group, or n to skip the check. If you answered y:
      1. enter the DN of the group
    8. Enter y to communicate with the LDAP Host over TLS, or n to use plain LDAP. If you entered y:
      1. Enter y to skip verification of the LDAP Host’s TLS certificate, or n to perform TLS certificate verification.
  9. Restart the service with sudo trusona-service restart for changes to take effect

Appending email domain

By default, the appliance requires that the User-Name attribute of incoming RADIUS requests are email addresses. However, you can configure an email domain to be appended to incoming usernames. For example, If you configure an email domain of example.com, and an incoming RADIUS Request has a User-Name of user, then the resulting email will be user@example.com.

LDAP mode

Instead of requiring email addresses as usernames, you can configure the RADIUS Service to operate in LDAP Mode. In LDAP Mode, users will be authenticated against an LDAP server. Then their email address will be looked up in LDAP and a Trusonaficaton will be issued. Additionally, you may provide an LDAP Group that users must be a member of to be authorized. The following diagram shows how LDAP Mode works:

Trusona RADIUS LDAP flow
Figure 1: LDAP mode authentication flow

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, MSCHAP and MSCHAPv2 are also supported. However, the appliance will be unable to verify the user’s password. The appliance will still lookup the user in LDAP to find their email address and check that they are a member of the configured LDAP Group. If you want to verify the provided password, you must do so outside of the RADIUS transaction. Figure 2 below shows how the LDAP communication is different when using MSCHAP or MSCHAPv2 when compared to Figure 1 above.

Trusona RADIUS LDAP flow
Figure 2: Authentication flow when using MSCHAP or MSCHAPv2

Managing the RADIUS service

You can manage the Trusona RADIUS Service with the command sudo trusona-service it has the following sub commands:

  • start - Starts the Trusona RADIUS Services
  • stop - Stops the Trusona RADIUS Services
  • restart - Stops and then starts the Trusona RADIUS Services
  • status - Reports the status of the Truonsa RADIUS Services

Network requirements

The appliance exposes 1812/udp and 1813/udp and those ports must be reachable by the downstream service that is issuing RADIUS requests. It also needs external access on port 443 so it can reach the Trusona Backend Services via HTTPS. If using LDAP Mode, then the configured LDAP port will also need to be open between the appliance and the configured LDAP host.

Using RADIUS to issue trusonafications

After completing setup, you can then issue Trusonafications for email addresses using the Appliance. Sending the email address as the User-Name attribute will create a trusonafication for that username. 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 $APPLIANCE_IP auth $RADIUS_SECRET

Note: 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.