Connecting to a Linux SSH (Secure Shell) Directory

Introduction

LogonBox is able to connect to any Linux server via SSH to work directly with any Linux users or groups on that server, this article shows you how you can connect your Linux server to your cloud tenant enabling your users to manage their account from the cloud. 

The SSH Connector is a scripted user database connector designed for connecting to a Unix like host over the SSH protocol. Simple commands are then run in the SSH session to load identities and roles from the /etc/passwd, /etc/shadow and /etc/group files. This connector requires either a root account, or an account with sudo privileges in order to be able to set and change passwords.

Password validations for authenticating users is performed either by an SSH authentication for that user, an SU command with password, or by matching hashes on the passwd files.

Pre-written scripts are available for most common Unix/Linux distros to simplify the configuration, but a custom script option is also available to allow complete control over user management.

Prerequisite 

In order for your LogonBox server to locate your SSH server the directory needs to be visible to the server, whether the directory is located on the same network as your server (if you have hosted your own LogonBox server) or through a secure node agent connection if your LogonBox service is hosted in the cloud- as documented in the article titled Installing a secure node agent.

Step 1 - Create Directory

Navigate to User Directory and select Configure User Database located at the top of the User table. 

From the form that opens up from the Realm Type dropdown, select SSH (Secure Shell).

Step 2 - Configuring your server Settings

With the correct realm type selected, the next step requires the settings to be configured.

There are 2 links at the top to switch between standard and advanced settings. Step 2 here concerns all of the Standard settings.

Step 2a - Details

The first tab, Details, is where the details for the server you are connecting to is held. You will need to provide the following information:

• Hostname: The hostname or IP address of the SSH server you are connecting to.
• Port: The port on which the SSH server is running (Default is 22)
• OS: The operating system you are connecting to. Selecting any other option than Custom automatically selects the appropriate scripts that are needed for full user management.
  • The options available in the dropdown are:
    • Gentoo
    • Custom
    • Cisco ASA
    • Arch Linux
    • CentOS
    • Debian
    • Fedora
    • Generic Linux
    • OpenSUSE
    • Red Hat
    • Solaris
    • Solaris (with NIS and Kerberos)
    • Solaris (with NIS)
    • Ubuntu

• Username: The username of the service account that will be used to manage this server. This username needs to be either root or a user with sudo privileges.

Step 2b - Authentication

The second tab, Authentication, contains items relating to how the service account will authenticate to the server as well as how user authentications are handled.

The options available here are:

• Password: The password for the service account (if password authentication is in use for that account)
• Private Key: If key authentication is used for the service account, paste the service account’s private key here.
• Private Key Passphrase: The password for the above private key.
• User Authentication: There are 3 choices here
  • SSH Password Authentication
  • SU Command
  • Unix Passwd files

For SSH Password Authentication, the Hypersocket server performs an SSH connection to the server as the user who is logging on to test the credentials. For SU Command, the service account attempts to do su <username> with the user’s password. For Unix Password files, /etc/shadow and /etc/passwd are checked to determine the password hashing algorithm. A hash of the user’s password is then generated and compared with the one stored in these files.

Step 2c - Advanced

The third tab is Advanced, which contains extra settings for the service account and passwords. The available options here are:

• Sudo Prompt: If using a non-root account, the sudo command will be used in order to have the correct permissions for editing users. This setting tells the LogonBox server what text is prompted by the server when sudo is called, so that LogonBox knows when to enter the service account password.
• Sudo Command: The command to run when executing sudo. By default this is set to sudo –k to enforce the service account credentials every time it is used.
• Read Only: Enable this option if you do not wish to edit users or change passwords.
• Delete Home Directory: When a user is deleted, should LogonBox also delete that user’s home directory on the target server?
• Password Pattern: When SSH Password authentication is selected on the Details tab, this setting contains a regular expression to check for the password prompt.
• New Password Pattern: When SSH Password authentication is selected on the Details tab, this setting contains a regular expression to check for the change password prompt.

Step 2d - Script

If Custom was selected in the OS setting in the Details tab, then the following tab will be Script. This is where you would create functions for all of the required functionality. An example script is included with several objects that allow the LogonBox server to interact with the SSH server. These can be altered as required to fit your requirements.

Here are some of the functions which the LogonBox Server will call in order to work with the SSH server as a Tenant Realm. The minimum functions that need to be implemented are allIdentities and getIdentityByName but the more functions provided the better as this will give greater functionality and performance:

• allIdentities: Returns a list of all users on the server
• getIdentityByName: get an identity given the username.
• getRoleByName: get a role given its name.
• allRoles: Returns a list of all roles or groups.
• updateIdentity: Updates a user’s details.
• createIdentity: Creates a new user.
• deleteIdentity: Deletes a user.
• deleteRole: Deletes a role or group.
• setPassword: Sets a user’s password.

Step 2e - Principal Filter

The last tab is Principal Filter, which allows you to restrict which user objects are cached by the server. Individual Users and/or Groups can be defined to exclude them.

Type in the user or group you wish to exclude then press enter or click the plus icon to add it to the list.

Step 3 - Advanced Settings

The configuration items below are not neccesary to get your SSH Server connected and synching with your server, however they may be useful for those that wish to add a little more control.

To access these settings click the Advanced Settings link above the tabs.

Step 3a - Reconcile

The only tab here, Reconcile, contains settings relating to how the users are cached in LogonBox. LogonBox connects to the remote user database periodically to update its list of cached users and then performs an update (reconcile) of this cache by either adding new users, deleting users that no longer exist or updating existing users.

The reconcile settings are:

• Rebuild Cache: On next reconcile, delete the cache and import all user objects from scratch. This takes more time than a normal reconcile. Defaults to OFF.
• Purge Duplicates: On rare occasions an out of date cache can cause duplicate users to be created in the cache. If that happens, this option can force removal of these duplicate users and rebuilds the cache. Defaults to OFF.
• Cache Passwords: LogonBox will generate a one-way hash of the users’ passwords the next time they log on and cache this. Subsequent authentication attempts do not need to contact the directory for authentication until the LogonBox server is restarted. Defaults to ON.
• Reconcile at Login: Performs a reconcile of the user’s account at login. This can ensure that the latest information for that user (such as group membership and AD attributes) are perfectly up to date each login. Generally this is not needed as user accounts do not change very often. Defaults to OFF.

Click Update to save the new settings and start the reconcile of your SSH Server.

Step 3 - Connection and reconcile

When you click update, you should be prompted with a prompt to trust this host.

If you trust the connection, click Yes, after which the connection will be made.

Your Linux users should now appear in LogonBox:

Conclusion

This article has detailed the core settings needed for your server to begin reconciling with your Linux server via SSH. Your tenant should now successfully begin synchronizing, enabling your users to be able to fully manage their accounts in the cloud.