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 v20 LTS. 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 will differ.

1.1. Trusona C SDK

Download or clone the Trusona C SDK from GitHub.

1.2. SDK Token and Secret

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

  1. Navigate to
  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. Dependencies

The following dependencies are required to build the Trusona C SDK:

On Ubuntu, they can be installed with:

sudo apt install build-essential uuid-dev libcurl4-openssl-dev lib-jansson-dev libssl-dev libpam0g-dev

3. Build the SDK

  1. Clone or download the Trusona C SDK
  2. Make and install the project

sudo make && sudo make install

4. Configuration

4.1. Trusona settings

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

sudo mkdir /usr/local/etc/trusona

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

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>",
  "api_host": "",
  "desired_level": 2,
  "expires_in_x_seconds": 99,
  "action": "login",
  "resource": "Ubuntu"
Setting name Description
access_token The Trusona API token you got from
mac_key The Trusona API secret you got from
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

4.2. Trusona PAM configuration

Move the generated and files from /usr/local/lib to /usr/local:

sudo mv /usr/local/lib/ /usr/lib
sudo mv /usr/local/lib/ /usr/lib

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

sudo touch /etc/pam.d/sshd/trusona

Edit the file to include the following:

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

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

An abbreviated example of /etc/pam.d/ssh with @include trusona directive:

# ...snip...

# Create a new session keyring.
session    optional 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  motd=/run/motd.dynamic
session    optional noupdate

# ...snip...

4.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 "" > ~/.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.

4.4. Testing the configuration

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

sudo trusona --user

Where is the email address you used to register in the Trusona App.

If the test fails, check the following:

  1. Permissions of /usr/local/etc/trusona/settings.json
  2. Validity of your API token and secret
  3. Your email address is correct
  4. Permissions and access of ~/.trusona
  5. Typos in /usr/local/etc/trusona/settings.json

5. 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 ssh restart


Remote access


Get started guides
Implementation guides
Users guides


Mobile SDKs
Server SDKs
Web SDKs


Authentication Service
ID Proofing Service