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
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
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
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 theCOMMUNITY
andTENANT_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:
Flags | Value | Description |
---|---|---|
ChallengeResponseAuthentication | yes | Specifies whether to allow keyboard-interactive authentication. |
KbdInteractiveAuthentication | yes | Deprecated alias for ChallengeResponseAuthentication . |
UsePAM | yes | Enables the Pluggable Authentication Module interface. |
MaxAuthTries | 1 | Defines the maximum allowable number of authentication attempts per connection. |
PubkeyAuthentication | no | Specifies 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
andBlockIDPAM.pp
created. Install this module with the following command:
sudo semodule -i BlockIDPAM.pp
- Set selinux to Enforcing
setenforce 1
Uninstallation
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:
-
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.
-
In the Journey Name field, enter a descriptive name for the journey and click the slider to enable or disable the journey.
-
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:
Category Condition Action Groups - Is one of
- Is not one of
- contains
- Does not containClick 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 with1. 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.
-
Select the appropriate action applicable for the journey. The following values are available to select:
- Grant access
- Deny access
- MFA Required
-
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 Access | Linux 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 Access | Linux 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 Required | Linux 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:
- Navigate to the Linux PAM page under Applications > Linux PAM menu of the AdminX interface.
- 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
orsetenforce Permissive
-
Enable SELinux for the active session:
setenforce 1
orsetenforce Enforcing