Guide
  1. For administrators
  2. Manage integrations

Krypton akr FIDO2 SSH Agent (beta)

The akr command-line utility consists of the Akamai MFA​ Krypton SSH Agent which works exclusively with the Akamai MFA​ FIDO2 authenticator to provide you with strong, cryptographic authentication for your SSH flows. The Akamai Krypton SSH Agent provides a strong authentication factor capability for SSH logins. Use of this authentication factor is independent of other Akamai MFA capabilities such as enrollment, user provisioning, and reporting - it is a completely independent authentication factor.

To get your akr FIDO2 SSH Agent up and running, you must download and install the Akamai MFA​ app on your smartphone. To turn your mobile device into a push-based SSH FIDO2 authenticator, you must pair the app with the locally running SSH agent.
Upon completed registration, you receive signature requests on your mobile device each time you attempt using SSH.

📘

This section refers to a feature that is in beta. It shall not be construed as providing any representation or guarantee as to the matters discussed, as such features may have bugs or other issues. Akamai assumes no obligation to update or correct any matters discussed in this section.

Before you begin

To enable the akr utility, you have to:

  • Run the following systems on your desktop machine:
    • macOS (11+, Apple Silicon) or Linux (x86_64/amd64 or aarch64/arm64): Ubuntu 22.04/24.04/26.04, RHEL/Rocky Linux 8/9/10, or CentOS Stream 9/10
    • OpenSSH Client and Server 8.2+
  • On your mobile device, download and install the Akamai MFA​ mobile app. To download the app, go to the App Store for iPhones or Google Play Store for Androids.
  • OpenSSH on macOS 13.0+ (Ventura) doesn’t support security keys. To use akr on Ventura, you need to enable security keys support by installing Homebrew’s OpenSSH and overriding the system’s default OpenSSH in your PATH. Run the following commands in the terminal to do so:
brew install openssh
export PATH=$(brew --prefix openssh)/bin:$PATH

Get Started

To set up your SSH FIDO2 keys, follow these steps:

  1. On your desktop machine, launch the terminal.

  2. Start the akr SSH agent and set up your ssh config file:

    • On macOS, run the following commands:
    akr setup
export SSH_AUTH_SOCK=<path_to_user_home>/.akr/akr-ssh-agent.sock
    📘

    To get the above path on macOS, you can run the following command: ls -lrt ~/.akr

    • On Linux, or if your ssh config file is not in /etc/ssh/ssh_config location, you may need to specify the file path. In this case, run this command: akr setup --ssh-config-path <file path>.
📘

Running akr setup updates your ssh config file and installs the akr SSH Agent as a background service on your system. To check the akr configurations, run this command:
akr setup --print-only.

The SSH config additions looks as follows:
#Begin MFA SSH Config
Host *
IdentityAgent /Users/<username>/ .akr/akr-ssh-agent.sock

#End MFA SSH Config

This enables your native system SSH to communicate to the akr ssh agent process over a Unix socket.

  1. Run akr pair.
    The QR code displays.

  2. Scan the QR code using the Akamai MFA​ app on your mobile device.
    A success message displays confirming that your mobile device was successfully paired with the SSH agent.

  3. To generate your first SSH FIDO2 key pair, run akr generate --name mykey, where you have to replace mykey with your key credential name.
    You receive a push notification on your mobile device.

  4. In the Register Device push notification, tap Allow to confirm.
    This generates your SSH FIDO2 key pair that will be stored on your trusted mobile device.

  5. Add your public key to the server or github.com.

  6. To verify whether your Akamai MFA​ FIDO2 key works, run the ssh command and connect to a FIDO2 supported server.

📘

If you have more desktop devices running akr SSH agent that you want to pair with your trusted mobile device, for each computer install the akr utility and follow the above steps.

  1. To unpair your mobile device, run akr unpair.

Install or update your akr FIDO2 SSH Agent

For the latest akr FIDO2 SSH Agent release, see the akr releases page on GitHub. If you are running an older version, update to the latest one.

  • To build from source code:

    1. Install Rust.
    2. Run cargo build.

  • To install with Homebrew on macOS:

    As running OpenSSH 8.2+ is required to use the akr FIDO2 SSH agent, you have to first check your OpenSSH version and upgrade if necessary.

    1. To check your SSH version run # ssh -V.
    2. If your SSH version is 8.1 or lower, install OpenSSH by running # brew install openssh.
    3. Reload the shell by running # exec $SHELL -l.
    4. Check the OpenSSH version by running # ssh -V.
    5. To install akr FIDO2 SSH agent, run brew install akamai/mfa/akr.

    Check Homebrew for system requirements and read the installation guide.

  • For Ubuntu distributions (22.04, 24.04, 26.04), follow these steps. Replace <VERSION> with 22, 24, or 26 to match your release:

    1. To configure the Akamai MFA​ akr package repository for the APT Package Manager, run these commands:
    sudo install -m 0755 -d /etc/apt/keyrings
curl -SsL https://akamai.github.io/akr-pkg/akr-keyring.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/akr.gpg
echo "deb [signed-by=/etc/apt/keyrings/akr.gpg] https://akamai.github.io/akr-pkg/ubuntu/<VERSION> ./" \
  | sudo tee /etc/apt/sources.list.d/akr.list

    1. To install the akr package, run sudo apt update && sudo apt install akr.

    2. To update the akr package later, run sudo apt update && sudo apt install --only-upgrade akr.

  • For RHEL / Rocky Linux distributions (8, 9, 10), follow these steps. Replace <VERSION> with 8, 9, or 10 to match your release:

    1. Create the file /etc/yum.repos.d/akr.repo with the following contents:
    [akr]
name=akr repository
baseurl=https://akamai.github.io/akr-pkg/rhel/<VERSION>/
gpgcheck=1
gpgkey=https://akamai.github.io/akr-pkg/akr-keyring.gpg
enabled=1

    1. To install the akr package, run sudo yum -y install akr.

    2. To update the akr package, run sudo yum -y update akr.

    3. Install pinentry-gtk. Run sudo yum -y install pinentry-gtk.

  • For CentOS Stream distributions (9, 10), follow these steps. Replace <VERSION> with 9 or 10 to match your release:

    1. Create the file /etc/yum.repos.d/akr.repo with the following contents:
    [akr]
name=akr repository
baseurl=https://akamai.github.io/akr-pkg/centos/<VERSION>/
gpgcheck=1
gpgkey=https://akamai.github.io/akr-pkg/akr-keyring.gpg
enabled=1

    1. To install the akr package, run sudo yum -y install akr.

    2. To update the akr package, run sudo yum -y update akr.

    3. Install pinentry-gtk. Run sudo yum -y install pinentry-gtk.

To learn more about the akr installation steps, see akr readme on GitHub.