Guide

Krypton akr FIDO2 SSH Agent (beta)

Suggest Edits

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 (10.15+) or Linux (64 Bit) (Debian, RHEL, and CentOS 6/7/8/9)
    • 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

The latest version of the akr FIDO2 SSH Agent is 1.1.2
If you are running a version earlier than 1.1.2, you need to update to the latest version.

  • 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 Debian distribution, follow these steps:

    1. To configure your private ​Akamai MFA​ akr package repository for the APT Package Manager, run these commands:
      curl -SsL https://akamai.github.io/akr-pkg/ubuntu/KEY.gpg | sudo apt-key add -
      sudo curl -SsL -o /etc/apt/sources.list.d/akr.list https://akamai.github.io/akr-pkg/ubuntu/akr.list

    b. To install the akr package, run sudo apt update.

    c. To update the akr package, run sudo apt install akr.

  • For CentOS/RHEL 6/7/8 distributions, follow these steps:

    1. Edit the file /etc/yum.repos.d/akr.repo, for example run sudo vim /etc/yum.repos.d/akr.repo.

    2. Add these lines to your file:

    [akr]
name=akr repository
baseurl=https://akamai.github.io/akr-pkg/rpm/
gpgcheck=0
enabled=1

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

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

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

  • For CentOS/RHEL 9 distributions, follow these steps:

    1. Edit the file /etc/yum.repos.d/akr.repo, for example run sudo vim /etc/yum.repos.d/akr.repo.

    2. Add these lines to your file:

    [akr]
name=akr repository
baseurl=https://akamai.github.io/akr-pkg/rpm-9/
gpgcheck=0
enabled=1

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

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

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

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

Updated almost 2 years ago