Arculix RADIUS Agent deployment guide
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 WiFi 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 Arculix RADIUS Agent provides a RADIUS server solution for authenticating your users in two steps:
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.
If the directory authentication is successful, the agent performs secondary authentication via Arculix 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 Arculix 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 for Arculix:
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 Arculix RADIUS Agent and the Arculix LDAP Agent, 4 GB RAM is recommended.
Network requirements
Inbound access
The RADIUS Agent does not need to be reachable from the Internet or Arculix. 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 |
|---|---|---|---|
Arculix 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 Arculix RADIUSAgent 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 Examples include |
Bind User | Yes | The user used when binding to the LDAP server. This may be a DN such as A new account with read-only access to the directory should be provisioned for the agent and used for binding. NoteThe Arculix integration will no longer function if this user account is disabled, its password is changed, or its privileges are lowered or revoked. |
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: |
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. WarningIf 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
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 SecureAuth team will provide the installation package and configuration file needed to complete the RADIUS Agent deployment.
Add RADIUS application in Arculix
Add an application in Arculix for RADIUS.
Log in to Arculix with administrative privileges and go to Applications.
Click Create New Application.
In the New Application form, on the General tab, set the following configurations:
Name
Set the name of the application. This is the name to display for push notifications, in the Admin panel, Application portal, and audit logs.
For example, RADIUS.
Type
Set to RADIUS.
Out of Band Methods
Select the allowed methods end users can choose to approve MFA requests.
For example, Arculix Mobile app (push notifications), SMS, or Security Key.
Message for MFA Requests
Optional. Type a message displayed to end users when sending an MFA request via push notification, SMS, or email.
Select the Advanced tab and copy the UID and Secret.
You will need these values during installation of the RADIUS Agent to connect with Arculix.
Save your changes.
Package contents
The Arculix 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:
docker-compose.yml- The Docker Compose configuration describing how to launch the RADIUS Agent.install-docker.sh- A helper script to install Docker on Linux hosts.install.sh- The RADIUS Agent installation script.radius-agent-image.tar- The RADIUS Agent Docker image.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 Arculix 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, SecureAuth will provide a radius-agent-config.env configuration file template pre-configured with any credentials needed to pair your agent with Arculix. 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:
If a RADIUS Agent is currently present on the system, its installation directory will be suggested as the destination for installing the new agent.
If the destination directory has an existing configuration file, it will be preserved instead of overwritten.
Any currently running agent will be stopped before starting the new agent.
RADIUS Agent configuration
The Arculix 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 |
|---|---|
| The Arculix UID which uniquely identifies the RADIUS Agent as an application in your organization. |
| The Arculix secret used to protect access. |
| A list of LDAP URLs to use when performing LDAP queries. The URLs must begin with Examples include 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. |
| The user used when binding to the LDAP server. This may be a DN such as A new account with read-only access to the directory should be provisioned for the agent and used for binding. |
| The password of the user used to bind to the LDAP server. |
| The Base DN used when performing LDAP queries. All relevant users and groups must be descendants of this DN. Example: |
| 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:
|
If MS-CHAP authentication is needed, the following configuration items are required:
Environment variable | Description |
|---|---|
| This must be set to Default: |
| 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. |
| 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. |
| 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. |
| The Kerberos realm of the domain to join. This is the same as the domain's name. For example, "company.local". |
| The NetBIOS (pre-Win2k) name of the domain to join. For example, "COMPANY". |
| 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 |
|---|---|
| This must be set to NoteOnly EAP-PEAP-MSCHAPv2 is supported at this time. Default: |
| The certificate in PEM format to be used for the EAP-PEAP authentication. |
| 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 |
|---|---|
| Specify the level of logging desired. Must be one of Default: |
| The message to show users when prompted to MFA. Default: "Connect to your RADIUS VPN?" |
| The MFA timeout, in seconds. Default: 60 seconds |
| If this is set to Default: |
| The URL used to connect to Arculix via Websocket for real-time notification of MFA results. This is an experimental feature, and is normally ignored because If |
| The LDAP filter used to find users based on the provided username. Use Default: |
| The LDAP user attribute to be used for the user's email address. Default: |
| 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: |
| 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. WarningIf 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. |
| 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. |
| The RADIUS attributes in this list are considered acceptable to transmit to Arculix for the purposes of providing authentication context to the risk engine. Default: |
| When logging information about a RADIUS request or response, the RADIUS attributes in this list are considered safe to include without redacting. Default: |
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:
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.
RADIUS is a UDP-based protocol, thus any load balancer in use needs to support UDP.
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.
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.
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 authentication services through Arculix, 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 the Arculix 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:
 |