Install the Okta RADIUS agent on Linux OS

This document describes the process of installing the Okta RADIUS Agent on Linux operating systems. For instructions for installing the RADIUS agent on Windows, please refer to Installing and Configuring the Okta RADIUS Server Agent for Windows.

For best practices, see Okta RADIUS Server Agent Deployment Best Practices.

This is an Early Access feature. To enable it, contact Okta Support.

The Okta RADIUS server agent delegates authentication to Okta using single-factor authentication (SFA) or multi-factor authentication (MFA).

A RADIUS client sends the RADIUS agent the credentials (username and password) of a user requesting access to the client. Authentication then depends on your org's MFA settings.

  • If MFA is not enabled and the user credentials are valid, the user is authenticated.
  • If MFA is enabled and the user credentials are valid, the user is prompted to select a second authentication factor. The user selects one (e.g., Google Authenticator or Okta Verify) and obtains a request for a validation code. If the code sent back to the client is correct, the user gains access.
Downloading the RADIUS Linux Agent:

This is an EA agent. Please contact Okta support to have the agent added to your org. Once added, navigate to Settings > Downloads and select the link next to the Okta RADIUS Server Agent (RPM).

RADIUS App Configuration

To enable RADIUS authentication with Okta, you must install the Okta RADIUS server agent and configure one or more RADIUS applications in the Okta admin console. Admin console RADIUS applications allow Okta to distinguish between different RADIUS-enabled apps and support them concurrently. In addition, Okta RADIUS applications support policy creation and assignment of the application to groups.
For more information on configuring the RADIUS App see RADIUS applications in Okta.

Supported Operating Systems

The Okta RADIUS agent has been tested on the following Linux versions:

  • Red Hat Enterprise Linux release 8.0
  • CentOS 7.6
  • Ubuntu 18.04.4

Requirements and Limitations

Before you Begin

Caution

Caution

When installing the RADIUS Agent you must be logged in to an account which has all three of Read-only Admin, Mobile Admin, and App admin roles, or Super admin role.
In addition, Okta recommends the use of dedicated service account to authorize RADIUS agents. A dedicated account ensures that the API token used by the RADIUS agent is not tied to the life-cycle of a specific user account which could be deactivated when the user is deactivated. In addition, service accounts used for RADIUS agents must be given appropriate admin permissions.

Please refer to the Administrators permission table (MFA section) for specific permissions required.

Known Limitations

Proxy configurations must be configured directly in the agent configuration file.

Installing the RADIUS LINUX Agent

Preparing the Environment

  1. Download the RPM installer as noted in the Before you Begin section.
  2. If using an Amazon Elastic Compute Cloud (commonly referred to as Amazon EC2) ensure you have all required keys and upload the RPM into the environment.

Validate the download

Check the Downloads page to see this agent's file size and SHA-512 hash. You can use the file size and hash to verify the integrity of the files.

  1. In the Admin Console, go to Settings > Downloads.
  2. Select the Download link next to the RADIUS installer (apt or deb).
  3. Use one of the following commands to generate the hash on your local machine. Note that you should replace setup with the file path to your downloaded agent.
    • Linuxsha512sum setup.rpm
    • MacOSshasum -a 512 setup.rpm
    • WindowsCertUtil -hashfile setup.exe SHA512
  4. Verify that the generated hash matches the hash on the Downloads page.

Installing the agent

Important Note

Important

The following commands must be run as root.

  1. Login to the computer which will run the agent and open a terminal window.
  2. Become root.

    $ su root
    password:<enter root password>
  3. Install the agent.
    1. Using rpm to install the agent run the command:
      rpm -Uvh OktaRadiusSetupRPM-{M.m.details}.rpm
      Where:
      • U - install or upgrade

      • v - execute in verbose mode.

      • h - Print hash marks, #, periodically while performing operation

      • M.m.details represents the most recent version of the agent RPM.
        For example: OktaRadiusSetupRPM-2.10.0.rpm

    2. Using debian apt to install the agent run the command: 
      apt install /${PATH_TO_INSTALLER_FILE}/OktaRadiusAgentSetup-{M.m.details}.deb
      Where:
      • M.m.details represents the most recent version of the agent DEB.
        For example: OktaRadiusAgentSetup-2.10.0.deb

  4. The installer will execute and prompt you to enter the base URL for your Okta organization.
    For example: https://mycompany.okta.com
  5. The agent will then prompt you to authenticate with your Okta tenant.
    Copy the URL from the agent install window into a web browser.
    The URL will resemble:
    https://{yourorg.okta.com}/oauth2/auth?code={code}

  6. In the web browser, you’ll be prompted to authenticate to Okta and authorize the agent.
    Click Allow Access.
    Info

    Note

    Okta recommends authorizing the agent using a dedicated service account with Super Admin privileges. An API token will be generated for the agent. To learn more about API tokens see API.
    Refer to Before you Begin for more information.

  7. Return to the Linux terminal window where you should see a message stating the agent was successfully registered.
  8. Configure a RADIUS app in Okta to configure the RADIUS agent port, shared secret, and advanced RADIUS settings .
    For more information about configuring the RADIUS App in your okta tenant please see RADIUS applications in Okta

Managing the Agent

The Okta Radius agent can be started, stopped or restarted easily. During the Radius Agent installation process. The installer creates a Linux service with either systemd or initd, depending on your current operating system, to manage the application,

Managing the Agent With systemd

To start the radius agent:

As root:

 # systemctl start ragent

To stop the radius agent:

As root:

# systemctl stop ragent

To restart the radius agent:

As root:

# systemctl restart ragent

To check radius agent status:

As root:

root@localhost # systemctl status ragent

Managing the Radius Agent With initd

To start the radius agent:
As root:

# /etc/init.d/ragent start 

To stop the radius agent:
As root:

# /etc/init.d/ragent stop 

To restart the radius agent:
As root:

# /etc/init.d/ragent restart

Additional Property Configurations

You can override RADIUS Agent default properties as required.

Important Note

Important

Changes to the RADIUS Agent config.properties are only loaded on agent restart.
Always restart your agent after changing config.properties.

  1. Open a terminal window and navigate to /opt/okta/ragent/user/config/radius.
  2. Using a text editor open config.properties .
  3. Modify any of the properties shown below, as required.
  4. When done, save the file.
  5. Any changes are effective after restarting the Okta RADIUS Agent service as described in Managing the Agent.
Property Description Default
ragent.num_max_http_connection The maximum number of HTTP connections in the connection pool. 20
ragent.num_request_threads The number of authentication worker threads available for processing requests. 15
ragent.total.request.timeout.millisecond

The maximum time the RADIUS agent is allowed to process a UDP packet after it has arrived from the RADIUS client.

 

For the Okta Verify with Push factor the actual value is interpreted by the RADIUS agent as one half (1/2) of the configured value.
For example: 60000 =60 seconds, divided in half =30 seconds.

For all other factors the value is used as specified.


60000
ragent.request.timeout.millisecond The maximum time the RADIUS agent is allowed to process a UDP packet after it has arrived from the RADIUS client.

If specified, ragent.total.request.timeout.millisecond is ignored.
If not specified, default is to use ragent.total.request.timeout.millisecond.

Available since version 2.9.4.
N/A defaults to value specified by ragent.total.request.timeout.millisecond

When using the RADIUS agent with a VPN such as Cisco ASA VPN the following timeout values should be configured on both RADIUS Agent and VPN settings:

RADIUS agent v2.9.3 and earlier with out Okta Verify Push. ragent.total.request.timeout.millisecond = VPN retry count * (VPN timeout + VPN wait between retries) - VPN wait between retries

 

RADIUS agent v2.9.3 with Okta Verify Push. ragent.total.request.timeout.millisecond = 2 * (VPN retry count * (VPN timeout + VPN wait between retries) - VPN wait between retries)

 

RADIUS agent v 2.9.4 and later. ragent.request.timeout.millisecond = VPN retry count * (VPN timeout + VPN wait between retries) - VPN wait between retries

Note:

  • VPN retry count should be between 3-5.
  • VPN request timeout should be 15-60s, (60-120s when using Okta Verify Push).

For example, where:

  • VPN retry = 5x
  • VPN request timeout = 60s
  • VPN wait between retry = 5s

Then, VPN authentication timeout = 5 * (60 + 5) + 5 = 320s, or 320000ms
RADIUS agent v2.9.3 and earlier with Okta Verify Push: ragent.total.request.timeout.millisecond = 320000.

RADIUS agent v 2.9.4 and later: ragent.request.timeout.millisecond =320000.


ragent.okta.request.max.timeout.millisecond

The socket timeout to set on the Okta API request. This property only applies if configured; otherwise, it is computed dynamically based on the total request timeout setting.

Dynamic, based on remaining TTL for request
ragent.request.timeout.response.mode

The timeout response mode. Possible values include:

  • SEND_REJECT_ALWAYS - agent sends a reject message to the client after any timeout..
  • SEND_REJECT_ON_POLL_MFA- agent sends a reject message to the client if a timeout occurs during the MFA polling loop only (i.e. while the agent is polling Okta to determine if the user has correctly responded to an MFA challenge such as a push notification). If a timeout occurs at any other time, no response will be sent to the client.
  • NO_RESPONSE - no response will be sent to the client when the agent times out.
SEND_REJECT_ON_POLL_MFA
ragent.mfa.timeout.seconds Time, in seconds, that the agent will wait for the client to respond to an MFA challenge such as factor selection. 60

Accessing and Managing Log Files

Log files for the radius agent can be found in /opt/okta/ragent/logs
To gather all logs together use a command similar to:

$ tar -zcvf logs.tar.gz /opt/okta/ragent/logs

Logging level can be set by modifying the log4j.properties file

Depending on where you installed the Okta RADIUS Agent, data logs can be accessed from

  • Windows: C:\Program Files (x86)\Okta\Okta RADIUS Agent\current\logs
  • Linux: /opt/okta/ragent/logs

To increase the logging level:

  1. Open the log4j.properties file from the installation folder
    Windows: C:\Program Files (x86)\Okta\Okta RADIUS Agent\current\user\config\radius\.
    Linux: /opt/okta/ragent/user/config/radius.
  2. Change all three instances of info to debug. Which, when updated, should resemble:
    • log4j.logger.app=debug, app
    • log4j.logger.access=debug, access
    • log4j.rootLogger=debug, app, stdout

Uninstalling the agent

The Okta RADIUS agent for Linux, installed using RPM, can be uninstalled as follows:
As root:

root@localhost # rpm -e ragent

The Okta RADIUS agent for Linux, installed using APT (.deb installer for Debian versions of Linux), can be uninstalled as follows:
As root:

root@localhost # apt remove ragent

General RADIUS Agent Documentation

For more information, refer to Getting started with Okta RADIUS Integrations and RADIUS Server Agent Best Practices.