> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # PAM RADIUS This procedure describes how to integrate a PAM RADIUS and Identity as a Service. Although this document specifically covers the PAM RADIUS, the information provided applies to RHEL 8 and RHEL 9. The aim of this integration is to provide strong, second-factor authentication for your PAM RADIUS solution using Identity as a Service. The PAM RADIUS supports the Identity as a Service authentication methods and authentication protocols listed in the table below. The capabilities may depend on the Identity as a Service configuration, or the set up of other third party authentication resources (Active Directory, for example). ## Supported authentication methods | Authentication method | Notes | Supported protocols | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------- | | Password | Password authentication is first-factor authentication with Identity as a Service password feature. | PAP | | RADIUS | RADIUS authentication is first-factor authentication with a RADIUS server. | PAP | | External | External authentication is first-factor authentication with a RADIUS server. | PAP | | Grid | Two-step authentication only | PAP | | Token | Identity as a Service supports response-only tokens. One-step or two-step authentication (including push authentication). | PAP | | Temporary Access Code | Token authentication must be configured. | PAP | | OTP (One Time Password) by SMS or Token | Two-step authentication only | PAP | note The PAM supports only PAP authentication methods with RADIUS. ## Prerequisites Complete the following steps before integrating your authentication system with Identity as a Service: 1. Install and configure your first-factor authentication resource using the documentation provided by the vendor. The first-factor authentication resource can be a RADIUS server or an external authentication resource (a Local DB, LDAP-compliant directory or Windows domain controller through Kerberos). 2. Install and configure the RADIUS appliance using the documentation provided by the vendor. The device must be able to route traffic before integrating with Identity as a Service. 3. Install and configure Identity as a Service and an Identity as a Service gateway (containing a RADIUS proxy agent). Take note of the shared secrets, IP addresses, and ports you use. You need this information to configure the RADIUS appliance and first-factor authentication resource. See [Create and configure a Gateway instance](/docs/gateways/create-and-configure-a-gateway.md). 4. If you want to configure your RADIUS appliance and first-factor authentication resource to recognize Identity as a Service user groups, you must define the Identity as a Service user groups first. Complete the following to integrate PAM RADIUS with IDaaS. ### Step 1: Prepare PAM RADIUS for installation Complete the following to prepare PAM RADIUS installation: 1. On each server that requires protection with second-factor authentication, install the PAM RADIUS software. See [Extra Packages for Enterprise Linux (EPEL)](https://docs.fedoraproject.org/en-US/epel/). 2. Log in or substitute the user to the root user. The PAM RADIUS Plug-in requires root privileges. 3. Run the following commands for your operating system: - RHEL 9: - `sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms` - `sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm` - RHEL 8: - `sudo subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms` - `sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm` ### Step 2: Install PAM RADIUS Perform the following on each server that requires protection with second-factor authentication: 1. Log in or substitute the user for the root user. 2. Install `pam_radius` as follows: - `sudo yum install pam_radius` 3. The RADIUS server configuration file is created at `/etc/pam_radius.conf`. 4. If `pam_radius` is already present, run the command: - `sudo dnf update pam_radius` 5. To communicate with Entrust Identity Enterprise RADIUS proxy server, complete the following: - Enter the hostname or IP address (with port number) for an Entrust Identity Enterprise server (for example, `10.10.10.10:1812`). - If lines specifying other servers exist, comment them as needed. 6. Add an Entrust Identity as a Service Gateway server to the configuration to communicate with Entrust Identity as a Service Gateway: - Run `sudo vi /etc/pam_radius.conf`. - Enter the IP address or hostname and the port number (for example, `123.145.10.10:1812`). - Enter the hostname or IP address (with port number) for an Identity as a Service Gateway (for example, `10.10.10.10:1812`). - Enter the shared secret. This should be the same shared secret you created for the Identity as a Service Enterprise Gateway. See [Create and configure a Gateway](/docs/gateways/create-and-configure-a-gateway.md) for more information. - Enter the timeout value (in seconds) for the Identity as a Service Gateway. If the authenticator uses push authentication, use a longer timeout (for example, 30 seconds or greater). If not, use a shorter timeout (for example, 10 seconds). - Add the following lines to the configuration file with your Identity as a Service Gateway IP and port: - `# IP/FQDN [:port] shared_secret timeout(s)` - `gateway.domain.com:1812 secret 60` - Save the changes by typing `wq` + Enter. ### Step 3: Duplicate a PAM RADIUS configuration (if required) After the PAM RADIUS Plug-in is installed and configured on one system, you can duplicate the files for other servers from the first installation. These updated files can be deployed to any systems sharing the same version of the operating system. 1. Deploy the `pam_radius` package to the required system. 2. From the first installation server, create a backup of the RADIUS server configuration file from _Step 2: Install the PAM Plug-in_ and copy the package to a common location so other servers can pick this file. 3. Create a backup of `pam_radius.conf`. 4. Copy the `pam_radius.conf` file from the common location to `/etc` and set access rights: - `sudo chmod 600 /etc/pam_radius.conf` ### Step 4: Configure PAM applications to use IDaaS Choose the procedure for the applicable operating system. #### Configure Red Hat Enterprise Linux 8 servers After the PAM RADIUS Plug-in has been successfully installed and configured, modify the `/etc/pam.d/sshd` file. 1. Create a backup of `/etc/pam.d/sshd`. 2. Review the default `/etc/pam.d/sshd` contents and adjust as required. For example: ``` #%PAM-1.0 auth substack password-auth auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth # pam_selinux.so close should be the first session rule session required pam_selinux.so close session required pam_loginuid.so # pam_selinux.so open should only be followed by sessions to be executed in the user context session required pam_selinux.so open env_params session required pam_namespace.so session optional pam_keyinit.so force revoke session optional pam_motd.so session include password-auth session include postlogin ``` 3. Update the file to include `pam_radius_auth.so` after `auth substack password-auth`. For example: ``` #%PAM-1.0 auth substack password-auth auth required pam_radius_auth.so auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth # pam_selinux.so close should be the first session rule session required pam_selinux.so close session required pam_loginuid.so # pam_selinux.so open should only be followed by sessions to be executed in the user context session required pam_selinux.so open env_params session required pam_namespace.so session optional pam_keyinit.so force revoke session optional pam_motd.so session include password-auth session include postlogin ``` 4. For one-step authentication, comment the line `auth substack password-auth`. 5. Configure the SSH daemon to be aware of challenge-response authentication: - Open `/etc/ssh/sshd_config`. - Set `ChallengeResponseAuthentication` to `yes`. - Set `UsePAM` to `yes`. 6. Restart the sshd service: - `sudo systemctl restart sshd` note Do not log out from the session used to configure the SSH PAM configuration. If you need to reverse the PAM changes, you can still do so from that terminal. It is very easy to lock up a system with a bad configuration. #### Configure Red Hat Enterprise Linux 9 servers After the PAM RADIUS Plug-in has been successfully installed and configured, modify the `/etc/pam.d/sshd` file. 1. Create a backup of `/etc/pam.d/sshd`. 2. Review the default `/etc/pam.d/sshd` contents and adjust as required. For example: ```text #%PAM-1.0 auth substack password-auth auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth # pam_selinux.so close should be the first session rule session required pam_selinux.so close session required pam_loginuid.so # pam_selinux.so open should only be followed by sessions to be executed in the user context session required pam_selinux.so open env_params session required pam_namespace.so session optional pam_keyinit.so force revoke session optional pam_motd.so session include password-auth session include postlogin ``` 3. Update the file to include `pam_radius_auth.so` after `auth substack password-auth`. For example: ```text #%PAM-1.0 auth substack password-auth auth required pam_radius_auth.so auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth # pam_selinux.so close should be the first session rule session required pam_selinux.so close session required pam_loginuid.so # pam_selinux.so open should only be followed by sessions to be executed in the user context session required pam_selinux.so open env_params session required pam_namespace.so session optional pam_keyinit.so force revoke session optional pam_motd.so session include password-auth session include postlogin ``` 4. For one-step authentication, comment the line `auth substack password-auth`. 5. Configure the SSH daemon to be aware of challenge-response authentication: - Open `/etc/ssh/sshd_config`. - Set `ChallengeResponseAuthentication` to `yes`. - Set `UsePAM` to `yes`. 6. Restart the sshd service: - `sudo systemctl restart sshd` note Do not log out from the session used to configure the SSH PAM configuration. If you need to reverse the PAM changes, you can still do so from that terminal. It is very easy to lock up a system with a bad configuration. ### Step 5: Add PAM RADIUS to Identity as a Service note Entrust recommends that when multiple RADIUS applications are configured that each RADIUS application is given a unique shared secret. Integrate a RADIUS client as follows: 1. Click Menu icon **>** **Security > Applications**. The **Applications** page appears. 2. Click **Add**. The **Select an Application Template** page appears. 3. Do one of the following: - Select **RADIUS and VPN Integrations** from the search drop-down list and scroll to find the application you want to add to IDaaS. - In the **Search bar**, enter a search option to filter for the application you want to add to IDaaS. 4. Click **PAM Plug-in**. The **Add PAM Plug-in** page appears. 5. Optional: Edit the **Application Name**. 6. Optional: Enter a **Description** for your application. 7. Optional: Add a custom application logo as follows: - Click Circle Plus icon next to **Application Logo**. The **Upload Logo** dialog box appears. - Click Arrow Up From Line icon to select an image file to upload. - Browse to select your file and click **Open**. The **Upload Logo** dialog box displays your selected image. - If required, resize your image. - Click **OK**. 8. Click **Next**. The **Setup** page appears. 9. Click **Add** next to **Hosts** to add the host name of the VPN server. The RADIUS agent receives the request on this host. The RADIUS Agent on the Gateway determines the RADIUS application the request is for based on the host name and port. 10. Enter the host name in the **Host** dialog box and then click **OK**. Repeat this step to add more host names. 11. In the **Port** field, enter the port on which the RADIUS agent accepts messages. tip Do not enter `8443` as the port number for this application. Port `8443` is used by the Entrust Identity Enterprise agent in your Gateway. attention The RADIUS agent uses the host name that sent a request and the port number that it received the request from to determine which RADIUS application made the request. Because of that: - Two RADIUS applications with the same port value cannot share any host names. - Two RADIUS applications that have one or more matching host names must have different port values. 12. In the **Shared Secret** field, enter the shared secret that is used by your VPN server. This is the RADIUS secret shared between your VPN server and the RADIUS server. The shared secret value must match a shared secret in your RADIUS client. 13. From the **Select RADIUS Agent** drop-down list, select the name of the Gateway containing the **RADIUS agent** to which this application will be assigned. 14. Optional: From the **Select RADIUS Attribute for IP Address** drop-down list, select the RADIUS attribute that corresponds to your IP location. 15. In the **Challenge Response Queue Max Time** field, set the number of seconds that the RADIUS agent waits for a response to first-factor authentication. The default value is 180 seconds. 16. In the **Challenge Response Queue Max Size** field, set the maximum number of second-factor challenge requests allowed in the queue of your RADIUS application. The default value is 1000 requests. The maximum value is 10,000. 17. In the **Request Cache Timeout** field, set the number of seconds to cache requests. The default value is 10 seconds. 18. From the **Character Set** drop-down list, select the character set used to decode and encode string values (including the user ID and password values) in RADIUS messages. The options are ISO-8859-1. 19. Optional: Select **Log RADIUS messages** to enable RADIUS message logging. When enabled, messages for the RADIUS agent are logged to the same log file as the gateway logs. 20. Optional: Enable the **Authentication Settings**. - Select **Enable Push Authentication Fallback** if you want authentication to fallback to another authenticator in the event of a failure. If required, set the **Push Authentication Fallback Timeout** to the number of minutes before the push authentication times out. - Select **When authenticating the user will be asked to select their second-factor authenticator**. When selected, after the user responds to the first-factor challenge, they are prompted to select their second-factor authenticator. The list of available second-factor authenticators is set by the resource rule. - The following is a list of supported strings matched to the authentication types: - Grid: `grid` - Knowledge-based Authentication: `kba` - One-time password: `email`, `sms`, `voice` - Smart Credential Push: `scpush` - Temporary Access Code: `tac` - Token: `token` - Token push: `push` - Select **Indicate if requests must include the message-authenticator attribute for incoming messages** to include the message-authenticator attribute for incoming messages. - Select **Indicate if requests must include the message-authenticator attribute for outgoing messages** to include the message-authenticator attribute for outgoing messages. - **Note:** Steps 20c and 20d fix the BlastRADIUS vulnerability. - Select **Remove domain from user ID for incoming requests** to remove the `domain` value from the user ID during authentication when the user ID provided by the RADIUS client is in the format `domain\username` and the user ID in IDaaS is in the format `username`. - Select **Indicate if Active Directory password authentication requests are handled by the same Gateway Instance that initiated the request** to require that Active Directory password authentication and change requests that are initiated as part of the RADIUS authentication are handled by any Gateway Instance in the same Gateway cluster that initiated it. If disabled, the request is handled by any Gateway Instance. - Select **Enable one-step multi-factor authentication**. When enabled, the user enters their user ID and then their password and token response in the password field. If you select this option, second factor authenticators available in the resource rule are limited to token and temporary access code. - Enter the **One-step multi-factor authentication security token length**. This is the length of the token or temporary access code response if you enable one-step multi-factor authentication. 21. Optional: **Add Response Attributes**. Response attributes are returned to the RADIUS application after successful authentication. Use this setting to configure RADIUS attributes to return information such as the user's group information to the VPN server. When adding response attributes, you optionally add group filters. For example: example Users in IDaaS may belong to one of the following groups CANADA, US, UK, FRANCE. The VPN server wants the FilterID attribute returned from the IDaaS RADIUS agent to be the value NA or EUROPE, depending on whether the user is in NA (Canada, US) or Europe (UK, France). To do this, use a RADIUS attribute filter for the FilterID attribute with a Groups value with the following filters: - match CANADA, replace NA - match US, replace NA - match UK, replace EUROPE - match FRANCE, replace EUROPE Set the **Response Attributes** as follows: 1. Click Circle Plus icon **Add**. The **Add a Response Attribute** dialog box appears. 2. Select the **RADIUS Attribute ID** from the drop-down list. The option you select depends on your VPN vendor. 3. Select the **Value Type** from the drop-down list. 4. To return a static value specific in the RADIUS attribute definition, select **Static** and enter a **Value** in the field and then click **Add.** 5. To return the user's group membership, select **Group** and then optionally do the following: - Click **Add** to add filters. - Enter the **Match** and the **Replace** attribute filters. - Click **Add** to add more attribute filters. - If you add multiple filters, you can drag and drop them in order of preference. - Select **Stop after matching filter** if you only want one filter to return one value. Using the example above, if you want NA to have preference over Europe, make sure to list Canada and US in the list of filters. - For Multiple Values Per Attribute, enter the **Value Separator** and then click **Add.** note If a user belongs to more than one group, you can either add a separate attribute to your RADIUS response for each group or you can combine all of the groups into a single attribute. For example, if the user belongs to G1,G2,G3 then you would: - return a RADIUS response with three attributes - return a RADIUS response with one attribute and a value like "G1,G2,G3" where the comma is defined in the Value Separator setting or a value like "G1 G2 G3" where the Value Separator is defined as a space. attention The default group separator is a space. If you have group names that are separated by a space, use another separator, such as a comma. 6. Repeat these steps to add more response attributes. 22. Optional: Configure the **EAP Settings** to set up the application to use the EAP RADIUS authentication protocol. - Select **EAP Enabled** to allow the RADIUS application to accept EAP messages. - When enabled, authentication messages with EAP content are treated as EAP requests. The application can accept only EAP authentication requests. - When disabled, incoming authentication requests are processed by the RADIUS application as a standard RADIUS authentication request (even if the request includes EAP content). In this case, the application can accept only standard RADIUS authentication requests. - Select the **EAP Protocol** from the drop-down list. The options are PEAPv1 with GTC. - This setting defines the type of EAP authentication protocol that is performed on EAP requests received by the RADIUS application. Consult the configuration requirements of your VPN server to determine which EAP protocol to select. - Select **Return MPPE Keys** to include the MPPE (Microsoft Point-to-Point Encryption) recv and mppe send keys in the Access-Accept message returned during a successful EAP authentication. The setting is enabled by default. - Select **Use PEAPv1 label when calculating MPPE Keys** to use the PEAPv1 label when calculating the mmpe recv and mppe send keys. - Leave the **Minimum TLS Version**, **Maximum TLS Version** and **Allow Weak Ciphers** at the default settings unless you have an older VPN and need to configure these settings to allow older versions of TLS or weaker ciphers to interoperate with older VPN servers that do not support the latest versions. 23. Configure the **Deprecated Settings** if your RADIUS application is connected to a Gateway version older than 3.0. These values are only required for backwards compatibility. 24. Select **No first-factor** as the **Authentication Type**. This setting defines the level of authentication required to access a RADIUS application that relies on a gateway RADIUS agent configured before release 3.1. note MSCHAPv2 authentication is not supported when **No first-factor** authentication is configured for the RADIUS application. 25. Click **Submit**. ### Step 6: Add a resource rule See [Create resource rules](/docs/authentication-and-security/create-and-manage-resource-rules.md). ### Step 7: Test the integration #### Test PAM RADIUS Plug-in for one-step authentication 1. Test the configuration by launching an SSH session from another server. Assuming the SSHD services are configured to use PAM RADIUS Plug-ins, the following example shows the beginning of an SSH login to the newly configured server. 2. Launch an SSHD session to the configured server. 3. The first prompt PAM RADIUS displays is **Password**. note If your authentication method is Response-Only Token, advise your users that the first Password prompt implies the Token response. 4. For one-step authentication for Mobile Smart Credential, in the SSH session after the user enters the username, press **Enter** at the password prompt. A Mobile Smart Credential Challenge appears on the mobile device. 5. For One-Time Password as one-step authentication, advise the users that the first **Password** prompt implies the OTP response. The user needs to enter a valid OTP at the **Password** prompt. 6. The user is logged in and shown the bash prompt. #### Test PAM RADIUS Plug-in for two-step authentication 1. Test the configuration by launching an SSH session from another server. Assuming the SSHD services are configured to use PAM Plug-ins, the following example shows the beginning of an SSH login to the newly configured server. 2. Launch an SSHD session to the configured server. 3. Enter the username and password. Identity as a Service presents a second-factor authentication challenge. 4. Answer a valid challenge. 5. The user is logged in and shown the bash prompt. ### Step 8: Other optional tasks Consult the following for uninstall procedures and parameters to customize the installation. #### Uninstall PAM RADIUS 1. Go to `/etc/pam.d/` and restore a backup of `sshd`. 2. Restore the backup file that you created in _Step 4: Configure PAM applications to use IDaaS_. 3. Remove the `pam_radius` package as follows: - `sudo yum remove pam_radius` - or `sudo yum erase pam_radius` 4. After the uninstall, restart the sshd service: - `sudo systemctl restart sshd` #### PAM RADIUS parameters The PAM RADIUS Plug-in has a few parameters that can be used to customize the installation. See [USAGE documentation](https://github.com/FreeRADIUS/pam_radius/blob/master/USAGE) for more information.