Skip to main content

Linux SSH MFA

Overview

1Kosmos BlockID Login for Linux integrates with PAM (Pluggable Authentication Module) to enable SSH login on Linux systems. It offers both standalone authentication and 2FA/MFA options, supporting various methods like PUSH Notification, TOTP, OTP via Email, OTP via SMS, and Password.

Supported Authentication methods

Any combination of the following online authentication methods is supported when using BlockID PAM:

  • PUSH Notification
  • TOTP from BlockID app
  • OTP via Email
  • OTP via SMS
  • BlockID Password

For example, admin can enable push notification and SMS OTP as authentication methods and provide user with the flexibility to choose any of the enabled methods during login or enforce all the enabled authentication methods as MFA.

Prerequisites

  • BlockID PAM installer
  • Root access to Linux host
  • SSHD service running
  • Network connectivity to 1Kosmos cloud
  • BlockID Mobile Application installed and linked to your account
note

The BlockID Linux PAM can only be used to authenticate accounts in user directories connected to your 1Kosmos tenant.


Installation and Configuration

Supported OS

  • RHEL 6, 7, 8, and 9.

Installation

To install the BlockID Linux PAM on your Linux host, please follow these steps:

  • Install Prerequisite Packages

The BlockID Linux PAM requires the installation of some prerequisite packages. Packages can be installed using the command:

sudo yum install -y tar libuuid vim-common libcurl
  • Download and extract the BlockID Linux PAM package

Navigate to the folder containing the PAM package and install it:

sudo ./blockId.<version>.<timestamp>.sh

Configuration

caution

It is advisable to keep an additional root shell accessible before modifying your PAM files or sshd configuration to avoid unintentionally locking yourself out. Furthermore, it is crucial to verify the functionality of your PAM configuration locally before testing it with SSH logins. Please take backup of the respective files that are to be modified as mentioned below.

License file Configuration

note

Only a user with root privileges can update the configuration file.

To configure the login mechanism in the BlockID Linux PAM, you need to modify the BlockID configuration file on your system. The location of this file is /opt/BlockId/data/license_config.

A sample license_config file looks like this:

  • Using a text editor such as vi, update the COMMUNITY and TENANT_DNS in this file with your tenant details (dummy details provided below):
TENANT_DNS=yourtenant.1kosmos.net
COMMUNITY=yourcommunity

SSH and PAM file configurations

password-auth (/etc/pam.d/password-auth)

When updating the /etc/pam.d/password-auth file, it's crucial to ensure that the authentication rules are properly configured to accommodate BlockID 2FA. Here's what needs to be done:

  • There should not be any auth rule with control flag as ** sufficient or [...success=done...] **, as it will bypass any other PAM (BlockID) after itself.

  • For any auth rule having control flag as sufficient needs to be changed to ** [success=X default=ignore] **, where X is the number of auth rules, below current auth rule, in the same file.

  • For any auth rule having [...success=done...] needs to be changed to [success=X default=ignore], where X is the number of auth rules, below current auth rule, in the same file. This will not create technical change in password-auth and simultaneously allow blockid 2FA to work.

    For example, if a rule exists as below:
    auth sufficient pam_sss.so forward_pass

    And there are 3 more auth rules below it, then the changed rule will be:
    auth [success=3 default=ignore] pam_sss.so forward_pass

  • Ensure that the last authentication rule, pam_deny.so has the control flag set to requisite.

    So, if the rule looks like this:
    auth required pam_deny.so

    The rule should be changed to:
    auth requisite pam_deny.so

    A sample of password-auth file before modification:

    A sample of password-auth file after modifications:

sshd (/etc/pam.d/sshd)

When modifying /etc/pam.d/sshd follow these steps:

  • Add the pam_blockId.so auth rule after your primary authentication (which is password-auth by default) and set its control flag as requisite.
  • It is necessary to make changes to the control flag of other pam rules preceding pam_blockId.so, to ensure that any of these rules do not have either sufficient or success=done as the control flag.
  • If there is any another PAM file entry with control flag as substack, preceding the pam_blockId.so:
    • Ensure its control flag is include,
    • Verify it doesn't contain auth rules marked as sufficient or success=done (see the changes required for /etc/pam.d/password-auth).

A sample of sshd file before modification:

A sample of sshd file after modification:

sshd_config (/etc/ssh/sshd_config)

The following flags and their values need to be added in the /etc/ssh/sshd_config file:

FlagsValueDescription
ChallengeResponseAuthenticationyesSpecifies whether to allow keyboard-interactive authentication.
KbdInteractiveAuthenticationyesDeprecated alias for ChallengeResponseAuthentication.
UsePAMyesEnables the Pluggable Authentication Module interface.
MaxAuthTries1Defines the maximum allowable number of authentication attempts per connection.
PubkeyAuthenticationnoSpecifies whether public key authentication is permitted, with the default setting being yes. 1Kosmos advises disabling this feature since it allows users to bypass the authentication process when using public key authentication.

Also, make a change in the file located at /etc/ssh/sshd_config.d/50-redhat.conf. If this file exists, find the line that says ChallengeResponseAuthentication no and comment it out by adding a # at the beginning of the line, like this: # ChallengeResponseAuthentication no.

Configuration if SELinux is Enabled

Additional permissions are required if your Linux host has SELinux Enabled.

  • Verify selinux is enabled
sestatus
  • Next, create a semodule and install it to allow the permissions for BlockID PAM module to work by completing the following step:

  • set selinux to Permissive

setenforce 0
  • Install the policycoreutils package (required to create and install a selinux module)
sudo yum -y install policycoreutils-python
  • If the above command gives package not found error, use the following command:
sudo yum -y install policycoreutils-python-utils
  • Open a new terminal window and connect to the same host using ssh. This connection is needed in order to create a log file we can audit in the next step.
ssh <username>@ip>
  • Once this is done, there are audit logs generated for sshd, highlighting the permissions required by the BlockID 2FA. Create a semodule from this.
sudo ausearch -c 'sshd' --raw | audit2allow -M BlockIDPAM
  • You should see a file/semodule named BlockIDPAM.te and BlockIDPAM.pp created. Install this module with the following command:
sudo semodule -i BlockIDPAM.pp
  • Set selinux to Enforcing
setenforce 1

Uninstallation

important

The administrator must reverse any configuration changes made manually during the installation process before uninstalling the BlockID.

To uninstall BlockID PAM, run the following command:

sudo /opt/BlockId/bin/BlockIDUninstall.sh

Using SSH Login for Linux

Once BlockID PAM has been installed on your Linux host, users can use SSH Login by connecting with SSH. Please see below for examples.

SSH Login via Push Notification

  • On your client machine, connect to your Linux host using SSH.

  • When prompted, provide the password for first factor authentication.

  • You will see a menu of enable authentication methods for BlockID 2FA. Select option for PUSH.

  • You will receive a push notification to the mobile device linked to your account. Approve the request by clicking the notification.

  • After authenticating the request using your enrolled biometrics, you will be logged in to your Linux host.

SSH Login via OTP as authentication method with only BlockID mechanism

  • On your client machine, connect to your Linux host using SSH. You will be prompted to enter OTP.

  • Open the BlockID mobile application on your mobile device and take note of the displayed six-digit Workstation OTP (swipe left if you cannot see it).

  • Enter the same six-digit Workstation OTP from your app and press ENTER. If the OTP matches, you will be logged in to your Linux host.

SSH Login via Password, OTP, and Push Notification with only BlockID mechanism

  • On your client machine, connect to your Linux host using SSH.

  • You will be prompted to enter a six-digit OTP.

  • Open the BlockID mobile application on your mobile device and take note of the displayed six-digit Workstation OTP (swipe left if you cannot see it).

  • Enter the same six-digit Workstation OTP from your app and press ENTER.

  • You will receive a push notification to the mobile device linked to your account on successful OTP validation.

  • Approve the request by clicking the notification.

  • On successful authentication of push notification using your enrolled biometrics, enter your BlockID user password on the prompt and press ENTER.

  • After successful authentication, you will be logged in to your Linux host.


Managing Adaptive Auth Journey for Linux PAM

1Kosmos now offers the capability of providing possession on the user’s configured device during onboarding. You can now configure a new Adaptive Auth Journey for Linux PAM using the Linux PAM menu under Applications > Linux PAM on the AdminX interface to provide second or multi-factor authentication when logging into your Linux servers.

When you are configuring the journey, you can associate conditions and actions with username or groups. By default, the new adaptive auth journey is applicable for all users. However, you can add a condition in case the journey must be made applicable for a specific set of users or AD usergroups. The following actions can be configured as follows:

  • Deny access: User is denied access by the Linux PAM.
  • Grant access: User is granted access without prompting for any factors.
  • MFA Required: User is granted access after they have authenticated with at least one of the allowed factors.

Creating Authentication Journey for Linux PAM

The community administrator can use the Adaptive Auth Journeys tab in the Linux PAM menu under Applications > Linux PAM on the AdminX interface.

To create a new adaptive auth journey, follow these steps:

  1. Navigate to the Adaptive Auth Journeys section through the Linux PAM menu and click Add new adaptive auth journey. The Create New Adaptive Auth Journey page is displayed.

  2. In the Journey Name field, enter a descriptive name for the journey and click the slider to enable or disable the journey.

  3. In the Conditions section, click Add a condition to define a condition to whom this auth journey is applicable. You can apply this journey specific to a user or a usergroup.

    The following table provides information on various conditions that can be set while configuring an adaptive auth journey:

    CategoryConditionAction
    Groups- Is one of
    - Is not one of
    - contains
    - Does not contain
    Click the + icon to open the Add Groups window. Specify a group name and click Save.
    Username- Is one of
    - Is not one of
    - contains
    - Does not contain
    - Starts with
    - Does not start with
    - Ends with
    - Does not end with
    1. Click the + icon to open the Add Users window.
    2. In the username field, enter the name of the user for whom the policy must be applied.
    Note: Click +Add another to add one or more users for whom all this policy must be applied.
  4. Select the appropriate action applicable for the journey. The following values are available to select:

    • Grant access
    • Deny access
    • MFA Required
  5. Click Save. The recently created journey is displayed on the Linux PAM list page.

Managing Actions on Linux PAM

The following table provides information on the actions that can be performed while configuring the adaptive authentication journey for Linux PAM.

When you select ...If conditions are matched...
Deny AccessLinux CP denies access to users and alerts them by displaying an error message on Linux PAM “Login failed due to max number of authentication attempts".
Grant AccessLinux CP grants access to users associated with service accounts and does not display any additional MFAs.
It is recommended to use this option only if the BlockID Linux PAM is used alongside LDAP PAM as this option will allow service accounts to locally authenticate with LDAP without any need of MFA.
Note: If the grant access option is used exclusively with the 1Kosmos Linux PAM, then Linux accounts meeting this condition will authenticate with just the username, posing a significant security threat.
MFA RequiredLinux PAM allows you to select the appropriate multi-factors to be displayed while performing the authentication. The following options are available to select:
- Just Password : Select this option to display only the password field for the user during authentication. Post validation of the password, the user will be granted access to their system.
- Push notification : Select this option to approve the push notification received in your mobile to complete the authentication.
- BlockID App Codes : Select this option to enter the six-digit code generated by the BlockID app.
- Any OTP : Select this option to enter the code received through the 1Kosmos authenticator such as mobile totp, email otp, sms otp, and phone otp.
- SMS OTP : Select this option to authenticate into the system by entering the code received through SMS.
Note : This option is available only if the mobile number is registered for the user.
- Email OTP : Select this option to enter the OTP received through email to complete the authentication.
Note: This option is available only if the email id is registered for the user.
- Voice OTP : Select this option to enter the code received through the voice call.
Note: This option is available only if the phone/landline number is registered for the user.
- Password & Push notification : Select this option to first enter the password. Post its validation, approve the push notification received in your mobile to access the system.
- Password & BlockID App Codes : Select this option to first enter the password. Post its validation, enter the code received through the BlockID app.
- Password & any OTP : Select this option to first enter the password. Post its validation, enter the code received through the 1Kosmos authenticator such as mobile totp, email otp, sms otp, and phone otp.
- Password & SMS OTP : Select this option to first enter the password. Post its validation, enter the OTP received through SMS to complete the authentication. If the phone number is not configured for the user, then Linux PAM will not display the SMS OTP option to the user.
- Password & Email OTP : Select this option to first enter the password. Post its validation, enter the OTP received through the email to complete the authentication.
Note: If the email address is not configured for the user, then Linux PAM will not display this option to the user.
- Password & Voice OTP : Select this option to first enter the password. Post its validation, enter the OTP received through the voice call to complete the authentication.

Deleting Authentication Journey

The community administrator can delete an authentication journey from the Adaptive Auth Journeys section of the Linux PAM list page.

To delete an authentication journey, follow these steps:

  1. Navigate to the Linux PAM page under Applications > Linux PAM menu of the AdminX interface.
  2. Click the delete icon inline with the rule that you want to delete. The AdminX interface displays a message on the successful deletion of the authentication journey.

Troubleshooting SSH Login for Linux

Troubleshooting Logs

Users facing any issues logging in with BlockID PAM can troubleshoot the problem by checking their system logs.

  • First, check the BlockID PAM logs created in /var/log/blockId/blockId.log and look for error messages.

  • If the issue can't be solved from the BlockID logs above, check the system SSHD logs using the following command:

journalctl -t sshd -r
  • If needed, read selinux audit logs for any SELinux issues
ausearch -m avc -ts recent

Useful Commands

  • To verify if the sshd service is running, use the command: systemctl status sshd

  • Stop the sshd service: systemctl stop sshd

  • Start the sshd service: systemctl start sshd

  • Restart the sshd service: systemctl restart sshd

  • Check SELinux status: sestatus

  • Disable SELinux for the active session: setenforce 0 or setenforce Permissive

  • Enable SELinux for the active session: setenforce 1 or setenforce Enforcing