Enterprise Connect

Windows RADIUS proxy

Enterprise Connect brings the capability for a remote authentication dial-up service (RADIUS) proxy to be installed on a Windows machine via the RADIUS protocol.

The RADIUS proxy changes the local RADIUS call to a secured REST API call, allowing local RADIUS clients to connect to ForgeRock for authentication. In turn, the capability to use MFA is provided, allowing tools, such as a virtual private network (VPN), to be enhanced.

Install Windows RADIUS proxy

Install and configure the Windows RADIUS proxy on a Windows machine(s).
Configure Linux SSH to use Windows RADIUS proxy for MFA

Post installation of the Windows RADIUS proxy on a Windows machine(s), explore the use case of setting up MFA on SSH login with Linux machines.

The ForgeRock integration supports the following authentication methods via PAP (password authentication protocol):

  • Push notifications (this is the preferred and recommended method) via the ForgeRock Authenticator application.

  • Time-based one-time passcodes (TOTP/OATH) via the ForgeRock Authenticator application.

  • Simple username and password credentials.

The subsections serve as the basis for installing the RADIUS proxy on a Windows machine.

Prerequisites

Before beginning the installation you must:

  • Have administrative privileges on the target Windows machine.

  • Obtain the Windows Workstation Authentication installation file from Backstage.

    You must have a Backstage account and be logged in to view the download.

  • Create a service account user for the Windows RADIUS proxy to run as. The minimum account privileges this user needs are:

    • Enable Log on as a service. For more information, refer to Microsoft’s documentation.

    • Write permission to C:\windows\system32 to have access to create the logs folder.

    • Write permission to C:\Windows\System32\logs folder.

  • Pre-configure journeys and services, as described in Create authentication journey(s).

  • Ensure all usernames (profiles/accounts) match from Windows (or the authoritative source) > ForgeRock and vice versa.

    • Set up a connector from ForgeRock to the datastore (for example, AD) and sync the data.

  • For push and Offline OTP (TOTP/OATH)authenticator methods, users pre-register in the appropriate journeys.

    It is crucial for users to pre-register; otherwise, these MFA methods will not work through the RADIUS proxy.

    Your RADIUS client must support the exchange of the TOTPs from ForgeRock journey > RADIUS proxy > RADIUS client and vice versa for the Offline OTP method to work. This includes handling challenge-response flows. If your client cannot handle the calls, use the push method instead.

  • Users install the ForgeRock Authenticator application to their smartphone via the Apple store or Google Play store.

  • For high availability/disaster recovery, it is recommended to deploy the necessary amount of Windows Workstation Authentication behind load balancers. Additionally, only one instance per machine is allowed.

Supported environments

Windows Workstation Authentication can only be installed on the following operating systems:

  • Windows 10

  • Windows 11

  • Windows Server 2016

  • Windows Server 2019

  • Windows Server 2022

Windows 8.1 and Windows Server 2012 are not supported.

Install Windows RADIUS proxy

Installing the RADIUS proxy is an intuitive process that utilizes an Installation Wizard to assist you. You must complete the prerequisites before following the below steps.

Install the ForgeRock RADIUS proxy on Windows

  1. Right-click on the ForgeRock Radius Agent.exe file and select Run as administrator.

    install radius proxy run as admin

    The installation wizard opens.

    The file name of the RADIUS proxy is subject to change from the download. If you do not run the executable as an administrator, the installation will fail.

  2. On the Welcome screen, click Next.

    install radius proxy welcome screen

  3. On the Custom Setup screen, click Next.

    install radius proxy custom setup next screen

  4. On the Destination Folder screen, click Next.

    install radius proxy dest folder next screen

  5. On the Logon Information screen, enter the service account user credentials for the service account using the ForgeRock RADIUS service. Make sure the syntax for the username is Domain\Username. For more information on the privileges required for this account, refer to prerequisites.

    install radius proxy user creds screen

    If the machine is not a part of a domain, then the domain for the service account user is the machine name.

  6. On the Agent Parameters page, configure the required settings:

    • Enter the relevant URL. For example, http://<tenant-env-fqdn>/openam.

    • Enter the relevant Realm. For example, /alpha.

      Ensure to prefix the realm with /.

      If the account does not have sufficient privileges or if the credentials are incorrect, an error screen might be presented during the final stages of the installation.

      install radius proxy service account error

    • Enter the Journey field for the selected authentication method:

      • Push (for example, push-radius)

        For an example of a push journey (used with the ForgeRock Authenticator application), refer to Example of a push journey.

      • TOTP (for example, otp-radius)

        For an example of a TOTP/OATH journey (used with the ForgeRock Authenticator application), refer to Example of a TOTP/OATH journey.

        Your RADIUS client must be able to support the exchange of the TOTPs from ForgeRock journey > RADIUS proxy > RADIUS client and conversely for the TOTP (OATH) method to work.

      • Simple (for example, simple-radius)

        Example of simple journey in Identity Cloud
        install radius proxy identity cloud simple journey
        Figure 1. Simple authentication journey in Identity Cloud
        Example of simple journey in Access Management
        install radius proxy am simple journey
        Figure 2. Simple authentication journey in Access Management
You can only configure one journey and one authenticator method. The journey entered will correspond to the authenticator method selected in subsequent steps.
radius proxy agent parameters screen

  1. Review the default values in the Radius Server section of the Agent Parameters screen, and if necessary, change them.

    1. The IP Address field can consist of two values; the default value127.0.0.1 (localhost) and 0.0.0.0.

      Change the IP Address to 0.0.0.0 to allow the Windows RADIUS proxy to listen on all interfaces.

    2. The default Port is 1812 (via UDP). Change if necessary.

    3. Input a value into the Secret field that is strong and complex. Take note of the secret, as it might be needed when configuring your RADIUS client to the RADIUS proxy. The Secret value appears to be pre-populated, but it is not.

      Ensure that the RADIUS client you are configuring with the Windows RADIUS proxy allows the characters in the Secret field. For instance, some RADIUS clients can not process special characters.

  2. Review the settings in the Authenticator section of the Agent Parameters screen and verify they match the authenticator type and method you configured. If necessary, you can correct the Authenticator configuration by selecting the correct settings from the drop-down lists.

  3. To begin the installation, click Install.

    install radius proxy install screen

    A status bar is displayed during the installation process.

  4. To exit the installation wizard, click Finish.

Once you have completed the installation of the RADIUS proxy, proceed to the post-installation steps.

Post-installation steps

Following installation, it is recommended to perform the following checks to verify that your environment has been set up as expected.

Check Windows Services

Make sure that the ForgeRock Radius Proxy service is installed and running via Windows Services:

  1. Press Windows + R on your keyboard.

  2. Type services.msc.

  3. Hit Enter to open the service.

  4. Search for the service under the name column. The service name is ForgeRock Radius Proxy.

Verify installation of folders and files

Verify that all the folders and files are installed under C:\Program Files{forgerock_name}\Radius Agent.

The configuration settings are stored in appSettings.Production.json. If you modify the configuration settings directly from this file, you must restart the RADIUS service (via Windows Services). The service name is ForgeRock Radius Proxy.

Verify functionality with RADIUS client

Once the Windows RADIUS proxy has been configured and installed on a Windows machine, it is important to test the setup.

Before beginning the verification process, make sure the following prerequisites are met:

  • The Windows RADIUS proxy is installed.

  • On a separate Windows machine, a test RADIUS client is installed. For example, NTRadPing.

    • Ensure the appropriate network connectivity is allowed between the two Windows machines. The default port is 1812 unless changed in the installation of the Windows RADIUS proxy.

  • Have a test account with a username and password.

Validate service is listening

To validate the service is listening, use a tool such as netstat on the Windows machine running the Windows RADIUS proxy:

netstat -ano | find "1812"

Test with RADIUS client

To test with the RADIUS client, you must have the following information from the Windows RADIUS proxy installation:

  • Windows RADIUS proxy server and port.

  • RADIUS Secret.

  • Test account with username and password to use with the RADIUS client. Ensure the user account exists in the ForgeRock environment.

For this example, NTRadPing is used as a test RADIUS client; however, any other RADIUS client will work.

Test Windows RADIUS proxy with RADIUS client
Display an example
verify radius proxy functionality

  1. Open desired RADIUS client, in this case, NTRadPing.

  2. Enter the Windows RADIUS proxy specific items. This includes the server, port, secret, and username and password for the test account.

  3. Click Send to initiate communication from the RADIUS client to the Windows RADIUS proxy.

  4. If the MFA method push was selected, for example, approve the login attempt from the ForgeRock Authenticator application.

    For push, users must pre-register as described in Prerequisites and Create push journey.

  5. Await a response from the Windows RADIUS proxy (server) that states Access-Accept.

Change Windows RADIUS proxy secret

Due to security reasons or change management, it can become necessary to change the secret you configured for the Windows RADIUS proxy (during the time of installation).

The installation path includes an executable to assist with the updating of the secret:

  1. Via Command Prompt, go to C:\Program Files{forgerock_name}\Radius Agent on your Windows machine.

  2. Run the ConfigTool.exe file with the appropriate parameters:

    ConfigTool.exe set-secret --secret enterNewSecretHere

  3. A message such as `appsettings.Production.json` Updated Successfully! should appear.

  4. The Windows RADIUS proxy secret has now been updated.

Ensure to update the Windows RADIUS proxy on dependent applications utilizing the service.

Additional reference

The subsequent sections explore additional features of Windows RADIUS proxy:

Configure Linux SSH to use Windows RADIUS proxy for MFA

With the Windows RADIUS proxy installed and configured on a Windows machine, you are ready to add MFA to an SSH login on Linux.

This use case is explored in this section.

The subsequent sections and examples utilize the Red Hat Enterprise Linux (RHEL) distribution. The commands can vary slightly. For example, RHEL uses yum to install packages while the Debian Linux distribution uses apt.

The following subsections assume you are logged into the Linux terminal as the root user or equivalent.

Prerequisites

Before setting up the SSH login on a Linux machine to use MFA via the Windows RADIUS proxy, you must:

  • Install the Windows RADIUS proxy.

  • Validate and test the Windows RADIUS proxy.

  • Establish network connectivity between the Linux machine(s) and the Windows machine(s).

  • Confirm all usernames (profiles/accounts) match from the Linux machine(s)> ForgeRock and vice versa.

    • Set up a connector from ForgeRock to the datastore and sync the data.

    • The ForgeRock journey validates the credentials when you configure MFA on an SSH login for Linux.

  • Confirm users pre-register in the appropriate journey if required. For example, for the push MFA method, users download the ForgeRock Authenticator application. For more information, refer to Windows RADIUS proxy prerequisites.

Ensure you properly patch, lock down, and harden the Linux machine(s) you expose to the Windows RADIUS proxy.

Install required packages

Packages are required to install relevant RADIUS configurations.

  1. Install the EPEL release by running the following command:

    sudo yum install epel-release

  2. Install the PAM RADIUS client by running the following command:

    sudo yum install pam_radius.x86_64

  3. Using an RPM command, verify that the installations were successful.

If any of the install commands return as not found by the package manager, locate the appropriate package name via an internet search as these are subject to change slightly depending on your Linux distribution.

Configure PAM RADIUS

After you install the required packages (which installs the PAM RADIUS), you must configure the PAM RADIUS module.

  1. Edit the /etc/pam_radius.conf file (using vim or an equivalent text editor).

  2. In the file, remove all entries below the 127.0.0.1 entry, under the table # server[:port] shared_secret timeout (s).

  3. Add an entry using the syntax <WindowsRADIUSProxyIPAddress>:<portOfProxy> <Windows RADIUS Secret> <timeoutInSeconds>.

    Linux PAM RADIUS configuration
    Figure 3. Linux PAM RADIUS configuration

Configure SSH Daemon

After the PAM RADIUS configurations are complete, the sshd configuration must be updated to utilize the RADIUS settings on SSH login.

  1. Edit the /etc/pam.d/sshd file (using vim or an equivalent text editor).

  2. Add the following line to the top of the file:

    auth required /usr/lib64/security/pam_radius_auth.so

    This line instructs Linux that for authentication, use the PAM RADIUS configurations. It requires the authentication service to enforce users to log in via the Windows RADIUS proxy. For more information on this, refer to RHEL’s documentation.

  3. Save changes and exit the file.

  4. Restart the sshd service:

    sudo systemctl restart sshd.service

Verify these changes with a test user and machine before applying them to your environments. Ensure the selected MFA method (defined in Install Windows RADIUS proxy) works with the test user.

Failure to confirm this successfully may result in users being locked out of the Linux machine(s).

Verify and test functionality

With the Windows RADIUS proxy installed and tested, the required packages installed on the Linux machine(s), and relevant configuration changes to PAM RADIUS and the SSH Daemon, you are ready to verify and test SSH login with a user.

Ensure the user you test in your Linux environment matches what is in your ForgeRock environment.

Add a Linux user

To add a user on a Linux machine:

  1. Create the user:

    adduser <username>

  2. Modify the password of the newly created user:

    passwd <username>

    You will be prompted to enter and re-enter the password of the user.

Create the user in your ForgeRock environment with the same username and password for testing. In a production scenario, syncing should be set up.

Perform SSH login

After you create a test user in the Linux environment with an equivalent account in the ForgeRock environment, you are ready to perform an SSH login test. The below steps assume the push MFA method was configured in the Windows RADIUS proxy setup.

  1. Initiate an SSH connection to the target Linux machine.

  2. Enter the username and password as prompted. A push notification should appear on your phone.

  3. Tap Approve on the ForgeRock Authenticator application.

  4. Verify that you have successfully logged into the Linux terminal with a valid session.

Uninstall Windows RADIUS proxy

The RADIUS proxy can be uninstalled at any time via the Control Panel of your Windows machine.

Uninstall the Windows RADIUS proxy

  1. Press Windows + R on your keyboard.

  2. Type control panel.

  3. Hit Enter to open the control panel.

  4. Navigate to Programs > Programs and Features.

  5. Select ForgeRock Radius Proxy.

  6. Click Uninstall.

Log files with Windows RADIUS proxy

With the Windows RADIUS proxy set up and configured, logs are generated automatically. They can be found under C:\Windows\System32\logs. The file format is sdo_radius_service-date. For example, sdo_radius_service-20220830.txt.