Okta RADIUS Server Agent (RPM) the Okta RADIUS agent on Linux OS

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

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

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.

Installing the agent

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.
   
   

   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.

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

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.

1. Using a text editor open /opt/okta/ragent/user/config/radius/config.properties .
   
2. Make any required changes.
   
3. When complete save changes.
4. 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,

 # systemctl start ragent

# systemctl stop ragent

# systemctl restart ragent

root@localhost # systemctl status ragent

Managing the Radius Agent With initd

# /etc/init.d/ragent start 

# /etc/init.d/ragent stop 

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

1. Using a text editor open /opt/okta/ragent/user/config/radius/config.properties .
   
2. Make any required changes.
   
3. When complete save changes.
4. 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: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.

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

Uninstalling the agent

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

root@localhost # rpm -e ragent

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.