Skip to main content

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:

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

Note

The 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: 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:

ad_radius_computer.png

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 SecureAuth team will provide the installation package and configuration file needed to complete the RADIUS Agent deployment.

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

ARA_EGUARDIAN_UID

The Arculix UID which uniquely identifies the RADIUS Agent as an application in your organization.

ARA_EGUARDIAN_SECRET

The Arculix 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 Arculix 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 Arculix 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:

  • 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:

seq_old_vpn.png

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

seq_agent.png

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:

seq_agent_mschap.png