Trusona for SSH (Linux PAM)

This guide details the steps required to configure Trusona as a passwordless authentication method for SSH.

1. 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.

1.1. 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.

1.2. 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.

1.3. 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

2. Configuration

2.1. 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

2.2. 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...

2.3. 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

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.

2.4. 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

3. 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

Integrations

Desktop
IAM and SSO
PAM
Productivity
RADIUS
Remote access
VPN

Guides

Get started guides
Implementation guides
Users guides

SDKs

Mobile SDKs
Server SDKs
Web SDKs

APIs

Authentication Service
ID Proofing Service

TOTP

Business
E-commerce
Finance
Productivity
Social
Gaming
Other