Trusona for SSH (Linux PAM)

This guide details the steps required to configure a passwordless experience with SSH & Trusona

By Nikolas Mangu-Thitu
Updated Mar 18, 2021

Getting Started

This guide assumes a new install and was written for Ubuntu 20.04, code name Focal Fossa.

Some steps may not be required on an existing and configured installation.

Other flavors of linux will be similar, but package names, paths, and directories may differ.

Required Prerequisites

You should verify ownership of a domain through the Trusona Developer’s site or have an agreement with Trusona allowing you to send Trusonafications to any email address.

Trusona C SDK

On Debian Ubuntu 20.04, you may complete installation using the following series of commands:

DOWNLOAD_URL=https://github.com/trusona/trusona-server-sdk-c/releases/download/1.0.0/trusona-server-sdk_1.0.0-1_amd64.deb
curl -sL $DOWNLOAD_URL -o trusona-server-sdk.deb
sudo apt-get update
sudo apt-get install ./trusona-server-sdk.deb

This will install the Trusona Server SDK, including all required dependencies.

SDK Token and Secret

To use the Trusona C SDK, you’ll need an SDK token and secret.

1. Navigate to https://dashboard.trusona.com
2. Login using Trusona
3. Click “SDK Credentials” in the sidebar navigation
4. Click the “Create Server Credentials” button
5. Save your token and secret in a safe and secure place

Configuration

Trusona settings

Create a trusona directory in /usr/local/etc:

sudo mkdir -p /usr/local/etc/trusona

Create a file settings.json in the /usr/local/etc/trusona directory:

sudo touch /usr/local/etc/trusona/settings.json

Edit the file to add the following Trusona settings:

{
  "access_token": "<your token here>",
  "mac_key": "<your secret here>",
  "resource": "<your hostname>",
  "api_host": "https://api.trusona.net",
  "desired_level": 2,
  "expires_in_x_seconds": 90,
  "action": "login"
}

Setting name	Description
access_token	The Trusona API token you got from https://dashboard.trusona.com
mac_key	The Trusona API secret you got from https://dashboard.trusona.com
api_host	Trusona’s API host
desired_level	2 – For Trusona Essential, 3 – For Trusona Executive
expires_in_x_seconds	Trusonafication expiration time in seconds
action	The action displayed to the user when authenticating
resource	The resource displayed to the user when authenticating

Trusona PAM configuration

If you installed using the .deb package, the configuration at /etc/pam.d/trusona is automatically generated for you.

Create a new PAM configuration file in /etc/pam.d:

sudo touch /etc/pam.d/trusona

Edit the file to include the following:

session required /usr/local/lib/pam_trusona.so settings=/usr/local/etc/trusona/settings.json prompt=yes presence=yes tilted=no

To enable Trusona for SSH, edit /etc/pam.d/sshd to include a reference to Trusona.

Here is an abbreviated example of /etc/pam.d/sshd with @include trusona directive:

# ...snip...

# Create a new session keyring.
session    optional     pam_keyinit.so force revoke

# Standard Un*x session setup and teardown.
@include common-session

@include trusona

# Print the message of the day upon successful login.
# This includes a dynamically generated part from /run/motd.dynamic
# and a static (admin-editable) part from /etc/motd.
session    optional     pam_motd.so  motd=/run/motd.dynamic
session    optional     pam_motd.so noupdate

# ...snip...

User Configuration

Follow these steps to configure both Trusona and SSH for a passwordless experience.

Trusona User Configuration

Each user connecting to the system with SSH needs to define their Trusona username in their home directory. In the following example, we will configure your user.

Create a file named .trusona in your home directory:

touch ~/.trusona

In this file, specify the email address you used to register in the Trusona App.

echo "user@example.com" > ~/.trusona

Restrict access to the file:

chmod 600 ~/.trusona

SSH Key Configuration

From the host you shall be connecting from, run the following the command and accept the prompted defaults:

ssh-keygen -t ed25519

If asked to overwrite an existing id_ed25519 file, respond with no

Next, execute the following command to display your public key in the file named id_ed25519.pub:

cat ~/.ssh/id_ed25519.pub

On the host where Trusona is installed, run:

touch ~/.ssh/authorized_keys

Copy and insert the previously displayed contents of the public key file as a single line into the file located at .ssh/authorized_keys

Some additional notes on user configuration:

• This file must be a regular file - not a symbolic link - and should have octal permissions of 10400 or 10600.
• The file must be owned by the owner of $HOME.
• At runtime, getuid() must equal geteuid() as a precaution against any setuid(uid_t) vulnerabilities.
• Additionally, the contents of this file should be less than 128 bytes; otherwise, bytes beyond that count will be ignored.
• Finally, if this file is found, and its contents read, concatenation of the value specified by the domain setting will not be done.

Testing the configuration

To test the configuration, attempt to send yourself a Trusonafication:

trusona --user user@example.com

Where user@example.com is the email address you used to register in the Trusona App.

If the test fails, check the following:

1. Formatting, permissions and accessibility of /usr/local/etc/trusona/settings.json
2. Validity of your API token and secret
3. Your email address is correct
4. You are allowed to send Trusonafications to any email address
5. File type, permissions and accessibility of ~/.trusona
6. Typos in /usr/local/etc/trusona/settings.json

Enabling Trusona for SSH

Before completing the following steps, ensure that you have an existing SSH connection (or physical access) to the server where Trusona is being enable. This is critical in the event you need to revert any changes

Restart the SSH service:

sudo service sshd restart

---