Acceptto RADIUS Agent System Requirements and Deployment Guide

Introduction

RADIUS is an open standard for performing user authentication on behalf of network access devices. It was originally developed in the 1990’s to enable a central source of access control for internet service providers providing dial-up access using terminal servers. Today, it is most commonly used to authenticate users connecting to a network via VPN servers or enterprise Wi-Fi access points.

RADIUS defines a lightweight datagram-based protocol for RADIUS clients (the network access devices such as VPN servers) to communicate with a RADIUS server. The server receives access requests from clients containing a user’s username and credentials, makes a decision to grant or reject access, and returns the result to the client. Many methods of authentication may be supported, from simple password checks to complex challenge-response algorithms requiring multiple steps.

The Acceptto RADIUS Agent provides a RADIUS server solution for authenticating your users in two steps:

1. First, primary authentication is performed using an LDAP server such as Active Directory. The agent verifies that the user is present, enabled, and has supplied a correct password.

2. If the directory authentication is successful, the agent performs secondary authentication via Acceptto's eGuardian cloud services. In this step, policies are enforced, risk assessment is performed, and the user may be challenged with an MFA request to provide stronger proof of identity.

Requirements

Server requirements

The agent itself runs within a Docker container, providing a degree of isolation between it and the Linux host environment on which it is installed. Any virtualization platform that is capable of hosting Linux servers should be suitable, including on-premises solutions such as VMware ESXi and Microsoft Hyper-V, and cloud environments such as Amazon EC2 and Microsoft Azure.

Number of instances

Two or more instances are recommended to be provisioned to increase availability. The RADIUS Agent is a stateless service so there is no limitation for horizontal scaling, although the system can work with only one instance of the agent if high availability is not a hard requirement.

However, due to the nature of RADIUS, arranging for load balancing and/or failover can sometimes present unique challenges. See the Using multiple RADIUS Agents section, below, for details.

Operating system

The Acceptto RADIUS Agent can be installed on any Linux system with a sufficiently recent version of Docker and Docker Compose installed. However, the following Linux distributions are supported by Acceptto:

• Red Hat Enterprise Linux 7+
• Ubuntu Server LTS 18.04+

We recommend using the latest releases (Red Hat Enterprise Linux 8 or Ubuntu Server LTS 20.04).

Docker

The RADIUS Agent package includes an install-docker.sh script which may be used to install a suitable version of Docker on Red Hat and Ubuntu systems. However, if you choose to install Docker manually, know that we require Docker 19.3.0 or higher, and Docker Compose 1.26 or higher.

Hardware

The minimum hardware requirements for deploying the RADIUS Agent are:

• 2 CPU cores
• 2 GB RAM
• 16 GB SSD storage

If the host is also being used for other services, the resources should be increased accordingly. In particular, if the same host is running both the Acceptto RADIUS Agent and the Acceptto LDAP Agent, 4 GB RAM is recommended.

Network requirements

Inbound access

The RADIUS Agent does not need to be reachable from the Internet or Acceptto. It does need to be reachable from any RADIUS clients on UDP ports 1812 and 1813:

Service	Protocol	Ports	Source host
RADIUS authentication	UDP	1812	RADIUS clients
RADIUS accounting	UDP	1813	RADIUS clients

Outbound access (external)

Service	Protocol	Ports	Host
Acceptto's eGuardian cloud services	TCP	443	mfa.acceptto.com
Linux host updates	TCP	80, 443	This varies depending on the host operating system in use. For Red Hat Enterprise Linux, see this document. For Ubuntu Linux, us.archive.ubuntu.com and security.ubuntu.com must be reachable.
Docker updates	TCP	80, 443	download.docker.com
Docker Compose download	TCP	80, 443	github.com

Outbound access (internal)

Service	Protocol	Ports	Service
LDAPS	TCP	636	Secure LDAP service
LDAP	TCP	389	Non-secure LDAP service, if used. (Not recommended)
DNS	TCP	53	DNS server

Additionally, if MS-CHAP authentication is in use, the agent must also be able to contact a domain controller on the following ports: UDP 88, TCP 88, TCP 135, UDP 137, TCP 445, TCP 1024-65535.

User directory (AD) requirements

The Acceptto RADIUS Agent communicates with the user directory using the LDAP protocol. Before deployment, a user account must be provisioned which allows read-only access to the directory.

The following information needs to be prepared before the installation:

Name	Required	Description
URL	Yes	The LDAP URL to use when performing LDAP queries. The URL must begin with ldap:// or ldaps:// and may include an optional port number to override the defaults of port 389 for ldap and 636 for ldaps. Examples include ldaps://ldap.company.com/ and ldaps://ad1.example.org:5000/.
Bind User	Yes	The user used when binding to the LDAP server. This may be a DN such as CN=John Doe,CN=Users,DC=company,DC=com or, in the case of Active Directory, a name in user@domain format such as johndoe@company.com. A new account with read-only access to the directory should be provisioned for the agent and used for binding.
Bind password	Yes	The password of the user used to bind to the LDAP server.
Base DN	Yes	The Base DN used when performing LDAP queries. All relevant users and groups must be descendants of this DN. Example: DC=company,DC=com.
TLS Trusted CAs	No	A list of certificates in PEM format representing trusted certificate authorities (CAs) to be used when verifying the LDAP server's certificate. These could include an enterprise CA used to issue certificates to LDAP servers, or even the certificate of the LDAP server itself. Warning: If this option is used, the operating system's default list of trusted CAs will not be used. Default: Use the operating system's list of trusted CAs.

MS-CHAP requirements (optional)

If MS-CHAP authentication is desired, the agent must be able to reach an Active Directory domain controller to join the domain. A separate computer account will be needed for each agent instance. By default, Active Directory allows any user to automatically create up to 10 computer accounts, so manual creation of computer accounts is seldom required.

However, if your site's policy does not allow users to automatically create computer accounts, you may need to manually create a computer account for each agent instance, and associate it with the agent's user account so the account is allowed to join the computer to the domain:

Pre-installation checklist

Please use this checklist to prepare for the installation:

• The required servers or virtual machines should be provisioned.
• The required firewall rules are in place.
• An LDAP read-only account has been provisioned for the agent.
• The LDAPS service is reachable from the RADIUS Agent hosts within the network.

Once all requirements are in place, the Acceptto team will provide the installation package and configuration file needed to complete the RADIUS Agent deployment.

Package contents

The Acceptto RADIUS Agent is distributed as an archive named radius-agent-X.Y.Z.tar.xz (where X.Y.Z is the version of this release) containing the following assets:

1. docker-compose.yml - The Docker Compose configuration describing how to launch the RADIUS Agent.

2. install-docker.sh - A helper script to install Docker on Linux hosts.

3. install.sh - The RADIUS Agent installation script.

4. radius-agent-image.tar - The RADIUS Agent Docker image.

5. manifest.json - Metadata describing this release of the RADIUS Agent. This is provided for informational purposes only, and is not actively used by the agent or the installation scripts.

Installing the RADIUS Agent

To install the Acceptto RADIUS Agent, first upload the provided radius-agent-X.Y.Z.tar.xz archive to the server. (Where X.Y.Z, here and elsewhere in the installation instructions, is the version of this release.) On the server, find the archive and extract it using the following command:

tar -xvJ -f radius-agent-X.Y.Z.tar.xz

Note that the extraction will create a radius-agent-X.Y.Z directory containing the installation assets. Change to this directory:

cd radius-agent-X.Y.Z

If this server does not have Docker and Docker Compose installed, they can be installed using the provided helper script:

sudo ./install-docker.sh

(Note the use of sudo, as this step requires root access.)

If this is a new installation, Acceptto will provide a radius-agent-config.env configuration file template pre-configured with any credentials needed to pair your agent with eGuardian. You should edit this file using an editor of your choice (vi, vim, nano, or whatever editor may be available in your Linux system):

vi radius-agent-config.env

This configuration file supplies settings in the form of environment variables. See the RADIUS Agent Configuration section below for full details on configuring the RADIUS Agent.

Finally, to install the agent, run the install.sh script from a user account with sufficient privileges to manage Docker:

sudo ./install.sh

Note that sudo is used in the above example to run the script as root, which should always have Docker privileges.

The installation process needs a destination directory where it can store agent assets such as the configuration file. It will suggest a default path, but you can provide an alternate location if desired.

Upgrading the RADIUS Agent

Upgrading to a newer version of the RADIUS Agent works mostly the same as performing a fresh installation: extract the provided archive and run its install.sh script. Note the following minor differences:

1. If a RADIUS Agent is currently present on the system, its installation directory will be suggested as the destination for installing the new agent.

2. If the destination directory has an existing configuration file, it will be preserved instead of overwritten.

3. Any currently running agent will be stopped before starting the new agent.

RADIUS Agent configuration

The Acceptto RADIUS Agent is configured using environment variables supplied in the radius-agent-config.env file. The following configuration items are required for the agent to start:

Environment variable	Description
ARA_EGUARDIAN_UID	The eGuardian UID which uniquely identifies the RADIUS Agent as an application in your organization.
ARA_EGUARDIAN_SECRET	The eGuardian secret used to protect access.
ARA_LDAP_URLS	A list of LDAP URLs to use when performing LDAP queries. The URLs must begin with ldap:// or ldaps:// and may include an optional port number to override the defaults of port 389 for ldap and 636 for ldaps. Examples include ldaps://ldap.company.com/ and ldaps://ad1.example.org:5000/. If provided via environment variable, multiple URLs may be separated by commas. Only the first URL is currently used. A future release may use additional LDAP URLs to round-robin outgoing connections or provide failover when one is not responding.
ARA_LDAP_BIND_USER	The user used when binding to the LDAP server. This may be a DN such as CN=John Doe,CN=Users,DC=company,DC=com or, in the case of Active Directory, a name in user@domain format such as johndoe@company.com. A new account with read-only access to the directory should be provisioned for the agent and used for binding.
ARA_LDAP_BIND_PASS	The password of the user used to bind to the LDAP server.
ARA_LDAP_BASE_DN	The Base DN used when performing LDAP queries. All relevant users and groups must be descendants of this DN. Example: DC=company,DC=com.
ARA_CLIENTS	RADIUS clients are configured in this setting. This should be a single string with client configurations separated by commas. Each client configuration contains the following fields separated by semi-colons: 1. The name of the client (this can be anything as long as it is unique), 2. the IP address range (in CIDR notation) used to identify this client, and 3. the RADIUS secret used for this client. An example client configuration with two clients might look like this: vpn1;192.168.101.0/24;h3d723hf9js3,vpn2;192.168.102.33/32,jd93nsfd92dh

If MS-CHAP authentication is needed, the following configuration items are required:

Environment variable	Description
ARA_MSCHAP_ENABLED	This must be set to true to enable MS-CHAP authentication. Default: false
ARA_MSCHAP_AD_USERNAME	The username of the Active Directory account used to join this RADIUS Agent to the domain. This is usually the same as the LDAP bind user, above.
ARA_MSCHAP_AD_PASSWORD	The password of the Active Directory account used to join this RADIUS Agent to the domain. This is usually the same as the LDAP bind password, above.
ARA_MSCHAP_AD_SERVER	The hostname of an Active Directory domain controller to join. For many sites, this may be the same as the hostname used in the LDAP URL.
ARA_MSCHAP_REALM	The Kerberos realm of the domain to join. This is the same as the domain's name. For example, "company.local".
ARA_MSCHAP_NETBIOS_DOMAIN	The NetBIOS (pre-Win2k) name of the domain to join. For example, "COMPANY".
ARA_MSCHAP_COMPUTER_NAME	The name of the computer account provisioned for this RADIUS Agent. If the user account provided above is authorized to automatically provision computer accounts, this will happen when the RADIUS Agent starts.

If EAP authentication is needed, the following configuration items are required:

Environment variable	Description
ARA_EAP_ENABLED	This must be set to true to enable EAP authentication. (Note: Only EAP-PEAP-MSCHAPv2 is supported at this time.) Default: false
ARA_EAP_CERTIFICATE	The certificate in PEM format to be used for the EAP-PEAP authentication.
ARA_EAP_PRIVATE_KEY	The private key in PEM format to be used for the EAP-PEAP authentication.

The following configuration items are optional, and may be used to further guide the behavior of the agent:

Environment variable	Description
ARA_LOG_LEVEL	Specify the level of logging desired. Must be one of panic, fatal, error, warn, info, debug, or trace. Default: info
ARA_EGUARDIAN_MFA_MESSAGE	The message to show users when prompted to MFA. Default: "Connect to your RADIUS VPN?"
ARA_EGUARDIAN_MFA_TIMEOUT	The MFA timeout, in seconds. Default: 60 seconds
ARA_EGUARDIAN_DISABLE_WEBSOCKET	If this is set to false, the agent will enable the experimental use of Websocket for real-time notification of MFA results. Default: true
ARA_EGUARDIAN_WEBSOCKET_URL	The URL used to connect to eGuardian via Websocket for real-time notification of MFA results. This is an experimental feature, and is normally ignored because EGuardianDisableWebsocket defaults to true. If EGuardianDisableWebsocket is false, this setting is required.
ARA_LDAP_USER_FILTER	The LDAP filter used to find users based on the provided username. Use %s to represent the username value. Default: (sAMAccountName=%s)
ARA_LDAP_USER_MAIL_ATTRIBUTE	The LDAP user attribute to be used for the user's email address. Default: mail
ARA_LDAP_TLS_DISABLE_VERIFICATION	Disable verification of the server certificate provided by the LDAP server. Warning: Use of this option leaves the agent vulnerable to machine-in-the-middle attacks, and is only provided for development and debugging purposes. Default: false
ARA_LDAP_TLS_TRUSTED_CAS	A list of certificates in PEM format representing trusted certificate authorities (CAs) to be used when verifying the LDAP server's certificate. These could include an enterprise CA used to issue certificates to LDAP servers, or even the certificate of the LDAP server itself. Warning: If this option is used, the operating system's default list of trusted CAs will not be used. Default: Use the operating system's list of trusted CAs.
ARA_LDAP_TLS_SERVER_NAMES	If the hostname in an LDAP URL does not exactly match the hostname embedded in the certificate presented by the LDAP server, verification will fail. This option may be used to specify the hostname we expect to find in the LDAP server's certificate. If used, one such hostname should be provided for each configured LDAP URL, and in exactly the same order. Default: Use the hostname as provided in the URL.
ARA_CONTEXT_ATTRIBUTES	The RADIUS attributes in this list are considered acceptable to transmit to eGuardian for the purposes of providing authentication context to the risk engine. Default: User-Name, NAS-IP-Address, NAS-Port, Service-Type, Framed-Protocol, Framed-IP-Address, Framed-IP-Netmask, Framed-MTU, Framed-Compression, Called-Station-Id, Calling-Station-Id, NAS-Identifier, Proxy-State, Acct-Session-Id, Egress-VLANID, Ingress-Filters, Egress-VLAN-Name, NAS-Port-Type, Port-Limit, Tunnel-Type, Tunnel-Medium-Type, Tunnel-Client-Endpoint, Tunnel-Server-Endpoint, Connect-Info, Tunnel-Private-Group-ID, Tunnel-Preference, NAS-Port-Id, Framed-Pool, CUI, Tunnel-Client-Auth-ID, Tunnel-Server-Auth-ID, NAS-IPv6-Address, Framed-Interface-Id, Framed-IPv6-Prefix, Delegated-IPv6-Prefix, EAP-Peer-Id, EAP-Server-Id, Mobility-Domain-Id, Network-Id-Name, WLAN-HESSID, WLAN-Venue-Info, WLAN-Venue-Language, WLAN-Venue-Name, WLAN-Pairwise-Cipher, WLAN-Group-Cipher, WLAN-AKM-Suite, WLAN-Group-Mgmt-Cipher, WLAN-RF-Band, EAP-Type, PaloAlto-Client-Source-IP
ARA_LOG_ATTRIBUTES	When logging information about a RADIUS request or response, the RADIUS attributes in this list are considered safe to include without redacting. Default: User-Name Client-Email-Address LDAP-UserDN NAS-IP-Address, NAS-Port, Event-Timestamp, Hint, Service-Type, Framed-MTU, Calling-Station-Id, Called-Station-Id, NAS-Port-Type, Connect-Info, EAP-Type, FreeRADIUS-Proxied-To

Using multiple RADIUS Agents

Multiple RADIUS Agent instances may be provisioned to provide high availability of the RADIUS service. However, there are some important considerations when deploying agents in this manner:

1. Some RADIUS clients allow multiple RADIUS servers to be configured, and support failover if one becomes unresponsive. If your RADIUS clients support this feature, it may be the simplest approach since it avoids the need for a load balancer. However, note that the RADIUS server selection strategy in this scenario is completely up to the client. Some clients may use a single RADIUS server until it becomes unavailable, and only then switch to a different server. This would provide an availability assurance, but not be sufficient for balancing load.

2. RADIUS is a UDP-based protocol, thus any load balancer in use needs to support UDP.

3. When using the RADIUS Agent for conventional (non-EAP) PAP and MS-CHAP authentications, its operation is stateless and any balancing strategy (e.g. round-robin) will work fine. However, when using EAP, a single transaction involves multiple incoming datagrams, all of which need to be directed to the same RADIUS Agent node. A naive load balancer may consider each datagram individually, and route each to a different node. A RADIUS-aware load balancer should be able to route incoming datagrams properly.

4. Use of a source IP hash balancing strategy would be sufficient to satisfy EAP, but would likely be ineffective at balancing load since most incoming RADIUS datagrams would be sourced from a small number of RADIUS clients.

5. It's possible that some load balancers may change the source IP address of the datagram as it transits, which can be problematic for matching clients to their configurations.

How it works

The RADIUS service is flexible enough to support many different integration scenarios. The following examples are provided to show how the service may be used in a typical environment where an Active Directory server provides the primary source of information about users.

A network might have an existing VPN server which is provisioned to authenticate user login attempts using Active Directory:

To integrate Acceptto’s authentication services, a customer may install the RADIUS Agent and configure the VPN server to use it for authentication:

When the agent receives the access request, it will perform authentication with Active Directory as normal. If this is successful, the agent will take the additional step of authenticating the user with Acceptto's eGuardian cloud service, which will perform risk analysis and any multi-factor authentication required by the policy. For example, the user may be prompted to approve the access attempt on their mobile phone.

In the above diagram, the nature of the credential material is left deliberately vague -- it could be a password, or it could be any other sort of data required by the authentication method in use. For example, if MS-CHAP authentication is in use, extra steps will be present to accommodate the challenge and response, a specific Microsoft protocol will be used to authenticate with Active Directory, and the VPN server will receive MPPE keys if necessary for its encryption. In this scenario, the actual password never leaves the user’s PC: