Trusona for SSH (Linux PAM)

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

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:

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
  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": "",
  "desired_level": 2,
  "expires_in_x_seconds": 90,
  "action": "login"
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

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

3. User Configuration

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

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

Restrict access to the file:

chmod 600 ~/.trusona

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

cat ~/.ssh/

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.

3.3. Testing the configuration

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

trusona --user

Where 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

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


Remote access


Get started guides
Implementation guides
Users guides


Mobile SDKs
Server SDKs
Web SDKs


Authentication Service
ID Proofing Service
Mobile Auth for Browsers Service