Ditch SSH Keys: Securely Access Servers with OpenID Connect Using opkssh

Tired of managing long-lived SSH keys and the security risks they pose? opkssh (OpenPubkey SSH) offers a modern solution: leveraging OpenID Connect (OIDC) for secure, streamlined SSH access management. Imagine authenticating to your servers with your familiar [email protected] identity, eliminating the hassle of key management.

What is opkssh?

opkssh doesn't replace traditional SSH, but enhances it by generating short-lived SSH public keys containing PK Tokens (built on the OpenPubkey protocol). These tokens encapsulate standard OIDC ID Tokens, letting you authenticate using existing identities. This approach simplifies access management and strengthens security.

Key Benefits of Using OIDC for SSH

• Enhanced Security: Short-lived credentials reduce the window of opportunity for key compromise.
• Simplified Management: Centrally manage access through your existing OIDC provider (like Google, Microsoft/Azure, or GitLab).
• Improved Auditability: Easily track user access based on their OIDC identity.

Getting Started with opkssh: A Quick Guide

Ready to experience the future of SSH? Here's how to get started:

1. Installation

Choose the installation method that suits your operating system:

• Homebrew (macOS): Open your terminal and run:

  brew tap openpubkey/opkssh
  brew install opkssh
  

  Copy

• Manual Installation (Windows, Linux, macOS): Download the appropriate binary for your operating system:

  • Linux
  • macOS
  • Windows

Follow these steps to install manually after downloading:

*   **macOS/Linux:** `curl -L [DOWNLOAD_URL] -o opkssh; chmod +x opkssh`
*   **Windows:** `curl [DOWNLOAD_URL] -o opkssh.exe`

2. Authentication

Authenticate using your OpenID Connect identity. Run the following command in your terminal:

• macOS/Linux: opkssh login
• Windows: .\opkssh.exe login

This will open a browser window, prompting you to select your OIDC provider and authenticate.

3. SSH Access

Once authenticated, opkssh generates an SSH key (containing your PK Token) in ~/.ssh/id_ecdsas. Now you can SSH to your server as usual:

ssh [email protected]

sshd is configured to verify the PK Token.

Server-Side Configuration: Enabling opkssh Authentication

To enable opkssh authentication on your server, follow these steps:

Automatic Installation (Linux)

Run the following command with root privileges:

wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash

This script automates the installation and configuration of opkssh, including:

• Downloading the opkssh binary.
• Installing it as /usr/local/bin/opkssh.
• Configuring SSH to use opkssh for authentication.

Granting User Access

To allow a user ([email protected]) to SSH to your server as root, run:

sudo opkssh add root [email protected] google

How opkssh Works: A Deeper Dive

opkssh cleverly utilizes SSH features to integrate OIDC authentication:

1. SSH Certificates with Extensions: OIDC ID Tokens are embedded into the SSH authentication protocol through a SSH certificate extension field.
2. AuthorizedKeysCommand: The SSH server uses the AuthorizedKeysCommand option in sshd_config (sshd_config manpage) to forward the SSH certificate to opkssh for verification.

Configuration Files: Fine-Tuning Access Control

opkssh uses space-delimited configuration files on the server for granular access control.

1. /etc/opk/providers: Allowed OIDC Providers

This file lists the authorized OPs (OpenID Providers) and enforces which providers and Client IDs are trusted.

• Column 1: Issuer URI of the OP (e.g., https://accounts.google.com).
• Column 2: Client-ID.
• Column 3: Expiration policy defining how long the generated SSH key is valid:
  • 24h, 48h, 1week: Sets a fixed expiration time after which the user must re-authenticate.
  • oidc: SSH key expires when the OIDC ID Token expires.
  • oidc-refreshed: SSH key expires when the refreshed ID Token expires (advanced scenario).

Example Configuration (/etc/opk/providers):

# Issuer Client-ID expiration-policy
https://accounts.google.com YOUR_GOOGLE_CLIENT_ID 24h
https://login.microsoftonline.com/YOUR_AZURE_TENANT_ID/v2.0 YOUR_AZURE_CLIENT_ID 24h

The proper file permissions are

sudo chown root:opksshuser /etc/opk/providers
sudo chmod 640 /etc/opk/providers

2. /etc/opk/auth_id: Global Authorized Identities

This file maps OIDC identities to Linux user accounts (principals).

• Column 1: The principal (Linux username).
• Column 2: Email address or Subject ID (sub claim from the ID Token).
• Column 3: Issuer URI (or shorthand: google, azure).

Example Configuration (/etc/opk/auth_id):

# email/sub principal issuer
alice [email protected] google
root [email protected] google
dev [email protected] azure

You can add rules using the add command sudo opkssh add {USER} {EMAIL} {ISSUER}

The proper file permissions are

sudo chown root:opksshuser /etc/opk/auth_id
sudo chmod 640 /etc/opk/auth_id

3. ~/.opk/auth_id: User-Specific Authorized Identities

A local version of /etc/opk/auth_id that resides in the user's home directory (/home/{USER}/.opk/auth_id). Users can manage their own authorized identities without requiring root privileges, only applies to the user where the file resides.

Example Configuration (/home/alice/.opk/auth_id):

# email/sub principal issuer
alice [email protected] google

The proper file permissions are

chown {USER}:{USER} /home/{USER}/.opk/auth_id
chmod 600 /home/{USER}/.opk/auth_id

Important Note about AuthorizedKeysCommandUser

AuthorizedKeysCommandUser specifies a less privileged user for the SSH AuthorizedKeysCommandUser. It creates a user and group automatically

sudo groupadd --system opksshuser
sudo useradd -r -M -s /sbin/nologin -g opksshuser opksshuser

It also specifies the following lines to /etc/ssh/sshd_config

AuthorizedKeysCommand /usr/local/bin/opkssh verify %u %k %t
AuthorizedKeysCommandUser opksshuser

Platform Support

Client

Server

Embrace the Future of SSH with Single Sign-On

opkssh offers a powerful and secure alternative to traditional SSH key management. By leveraging OpenID Connect, it streamlines access control, enhances security, and simplifies administration. Start using opkssh today and experience a more modern and secure way to access your servers, and say goodbye to the complexities of SSH keys with OpenPubkey SSH. Remember to implement these opkssh strategies to bolster your secure shell access.