Okta RADIUS Server Agent (RPM) 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.
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 or DEB).
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
- You must be able to sign in as root, or be able to execute root level commands using commands such as sudo.
- During installation you are prompted to enter your Okta URL, for example https://mycompany.okta.com, and you'll be required to authenticate as an admin.
Have your Okta tenant URL and admin credentials available and ready for use. - You must have previously downloaded the Radius agent RPM or Debian installers.
Refer to the Downloading the RADIUS Linux Agent section for more details. - For more information about Okta RADIUS Agent Deployment, see Getting started with Okta RADIUS Integrations and Okta RADIUS Server Agent Deployment Best Practices. For general information about Okta’s RADIUS Integrations, please see Okta RADIUS Integrations.

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.
Topics
- Installing the RADIUS LINUX Agent
- Configuring Proxies
- Managing the Agent
- Additional Property Configurations
- Accessing and Managing Log Files
- Uninstalling the agent
Installing the RADIUS LINUX Agent
Preparing the Environment
- Download the RPM installer as noted in the Before you Begin section.
- 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.
- In the Admin Console, go to Settings > Downloads.
- Select the Download link next to the RADIUS installer (rpm or deb).
- 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.
- Linux: sha512sum setup.rpm
- MacOS: shasum -a 512 setup.rpm
- Windows: CertUtil -hashfile setup.exe SHA512
- Verify that the generated hash matches the hash on the Downloads page.
Installing the agent

Important
The following commands must be run as root.
- Login to the computer which will run the agent and open a terminal window.
-
Become root.
$ su root
password:<enter root password> - Install the agent.
- 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
- 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
- Using rpm to install the agent run the command:
- The installer will execute and prompt you to enter the base URL for your Okta organization.
For example: https://mycompany.okta.com - 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} - In the web browser, you’ll be prompted to authenticate to Okta and authorize the agent.
Click Allow Access.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 token management.
Refer to Before you Begin for more information. - Return to the Linux terminal window where you should see a message stating the agent was successfully registered.
- 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
Configuring Proxies
If required the RADIUS agent can be configured to use a proxy.
To configure RADIUS agent proxy settings:

Important
Changes to the RADIUS Agent config.properties are only loaded on agent restart.
Always restart your agent after changing config.properties.
- Using a text editor open /opt/okta/ragent/user/config/radius/config.properties .
- Make any required changes.
- When complete save changes.
- Any changes are effective after restarting the Okta RADIUS Agent service as described in Managing the Agent.
Property | Description | Default |
---|---|---|
ragent.proxy.enabled | Indicates that the RADIUS agent should use a proxy. Must be set to true. Example: ragent.proxy.enabled = true. |
Default: Not present must be added to config.properties. |
ragent.proxy.address | The IP address and port( if required) of the proxy. If ragent.proxy.enabled is set to true this property must exist. Example: ragent.proxy.address = 127.0.0.1:8888 |
Default: Not present must be added to config.properties. |
ragent.ssl.pinning | If the proxy terminates the SSL connection, then SSL pinning must be disabled. Example: ragent.ssl.pinning = false |
Default: true. |
ragent.proxy.user ragent.proxy.password |
Proxy credentials, if required. Encrypted on agent restart. ragent.proxy.user = admin ragent.proxy.password = password |
Default: Not present must be added to config.properties. |
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
Changes to the RADIUS Agent config.properties are only loaded on agent restart.
Always restart your agent after changing config.properties.
- Using a text editor open /opt/okta/ragent/user/config/radius/config.properties .
- Make any required changes.
- When complete save changes.
- 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 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 ![]()
Important
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.
The following properties apply to proxy configuration only.
Property Description Default ragent.proxy.enabled Indicates that the RADIUS agent should use a proxy. Must be set to true.
Example: ragent.proxy.enabled = true.Default: Not present must be added to config.properties. ragent.proxy.address The IP address and port( if required) of the proxy. If ragent.proxy.enabled is set to true this property must exist.
Example: ragent.proxy.address = 127.0.0.1:8888Default: Not present must be added to config.properties.
ragent.ssl.pinning If the proxy terminates the SSL connection, then SSL pinning must be disabled.
Example:
ragent.ssl.pinning = falseDefault: true. ragent.proxy.user
ragent.proxy.passwordProxy credentials, if required.
Encrypted on agent restart.
ragent.proxy.user = admin
ragent.proxy.password = passwordDefault: Not present must be added to config.properties.
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:
- 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. - 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.