opkssh (OpenPubkey SSH)
opkssh is a tool which enables ssh to be used with OpenID Connect allowing SSH access to be managed via identities like [email protected] instead of long-lived SSH keys.
It does not replace SSH, but instead generates SSH public keys containing PK Tokens and configures sshd to verify them. These PK Tokens contain standard OpenID Connect ID Tokens. This protocol builds on OpenPubkey which adds user public keys to OpenID Connect without breaking compatibility with existing OpenID Providers.
Currently opkssh is compatible with Google, Microsoft/Azure, GitLab, hello.dev, Authelia, Authentik, Keycloak, Zitadel, PocketID, AWS Cognito, and Kanidm OpenID Providers (OP). See below for the entire list. If you have a Gmail, Microsoft, or a GitLab account you can ssh with that account.
To ssh with opkssh you first need to download the opkssh binary and then run:
opkssh login
This opens a browser window where you can authenticate to your OpenID Provider. This will generate an SSH key in ~/.ssh/id_ecdsa which contains your OpenID Connect identity.
Then you can ssh under this identity to any ssh server which is configured to use opkssh to authenticate users using their OpenID Connect identities.
ssh [email protected]
For updates and announcements join the OpenPubkey mailing list.
To ssh with opkssh, Alice first needs to install opkssh using homebrew or manually downloading the binary.
To install with homebrew run:
brew tap openpubkey/opkssh
brew install opkssh
To install with winget run:
winget install openpubkey.opkssh
To install with Chocolatey run:
choco install opkssh -y
Use the opkssh nixpkg as normal, or test it via:
nix-shell -p opkssh
To install manually, download the opkssh binary and run it:
Download URL Linux (x86_64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-linux-amd64 Linux (ARM64/aarch64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-linux-arm64 macOS (x86_64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-osx-amd64 macOS (ARM64/aarch64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-osx-arm64 ⊞ Win (x86_64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-windows-amd64.exe ⊞ Win (ARM64) github.com/openpubkey/opkssh/releases/latest/download/opkssh-windows-arm64.exeTo install on Windows run:
curl https://github.com/openpubkey/opkssh/releases/latest/download/opkssh-windows-amd64.exe -o opkssh.exe
To install on macOS run:
curl -L https://github.com/openpubkey/opkssh/releases/latest/download/opkssh-osx-amd64 -o opkssh; chmod +x opkssh
To install on linux, run:
curl -L https://github.com/openpubkey/opkssh/releases/latest/download/opkssh-linux-amd64 -o opkssh; chmod +x opkssh
or for ARM
curl -L https://github.com/openpubkey/opkssh/releases/latest/download/opkssh-linux-arm64 -o opkssh; chmod +x opkssh
After downloading opkssh run:
opkssh login
This opens a browser window to select which OpenID Provider you want to authenticate against.
After successfully authenticating opkssh generates an SSH public key in ~/.ssh/id_ecdsa which contains your PK Token.
By default this ssh key expires after 24 hours and you must run opkssh login to generate a new ssh key.
Since your PK Token has been saved as an SSH key you can SSH as normal:
ssh [email protected]
This works because SSH sends the public key written by opkssh in ~/.ssh/id_ecdsa to the server and sshd running on the server will send the public key to the opkssh command to verify. This also works for other protocols that build on ssh like sftp or ssh tunnels.
sftp [email protected]
To remove opkssh-generated SSH keys and certificates:
opkssh logout
This removes the SSH key pair that was generated by opkssh login. To remove a specific key:
opkssh logout -i ~/.ssh/opkssh_server_group1
Tell opkssh to store the name the key-pair opkssh_server_group1
opkssh login -i opkssh_server_group1
Tell ssh to use the generated key pair.
ssh -o "IdentitiesOnly=yes" -i ~/.ssh/opkssh_server_group1 [email protected]
We recommend specifying -o "IdentitiesOnly=yes" as it tells ssh to only use the provided key. Otherwise ssh will cycle through other keys in ~/.ssh first and may not get to the specified ones. Servers are configured to only allow 6 attempts by default the config key is MaxAuthTries 6.
To configure a Linux server to use opkssh simply run (with root level privileges):
wget -qO- "https://raw.githubusercontent.com/openpubkey/opkssh/main/scripts/install-linux.sh" | sudo bash
This downloads the opkssh binary, installs it as /usr/local/bin/opkssh, and then configures ssh to use opkssh as an additional authentication mechanism.
To configure a Windows server to use opkssh, download and run the installer script in an elevated PowerShell terminal:
Invoke-WebRequest -Uri "https://github.com/openpubkey/opkssh/releases/latest/download/Install-OpksshServer.ps1" -OutFile Install-OpksshServer.ps1
.\Install-OpksshServer.ps1
This downloads the opkssh binary, configures sshd_config for AuthorizedKeysCommand, sets up the correct NTFS ACLs on all configuration files, and restarts sshd.
To uninstall:
Invoke-WebRequest -Uri "https://github.com/openpubkey/opkssh/releases/latest/download/Uninstall-OpksshServer.ps1" -OutFile Uninstall-OpksshServer.ps1
.\Uninstall-OpksshServer.ps1
To validate the installation:
Invoke-WebRequest -Uri "https://github.com/openpubkey/opkssh/releases/latest/download/Test-OpksshInstallation.ps1" -OutFile Test-OpksshInstallation.ps1
.\Test-OpksshInstallation.ps1
On Windows, the configuration files are located at %ProgramData%\opk\ (typically C:\ProgramData\opk\).
To allow a user, [email protected], to ssh to your server as root, run:
sudo opkssh add root [email protected] google
To allow a group, ssh-users, to ssh to your server as root, run:
sudo opkssh add root oidc:groups:ssh-users google
We can also enforce policy on custom claims.
For instance to require that root access is only granted to users whose ID Token has a claim https://acme.com/groups with the value ssh-users run:
sudo opkssh add root oidc:\"https://acme.com/groups\":ssh-users google
which will add that line to your OPKSSH policy file.
We use two features of SSH to make this work.
First we leverage the fact that SSH public keys can be SSH certificates and SSH Certificates support arbitrary extensions.
This allows us to smuggle your PK Token, which includes your ID Token, into the SSH authentication protocol via an extension field of the SSH certificate.
Second, we use the AuthorizedKeysCommand configuration option in sshd_config (see sshd_config manpage) so that the SSH server will send the SSH certificate to an installed program that knows how to verify PK Tokens.
All opkssh configuration files are space delimited and live on the server.
On Linux, configuration files are stored under /etc/opk/. On Windows, they are stored under %ProgramData%\opk\ (typically C:\ProgramData\opk\).
Below we discuss our basic policy system, to read how to configure complex policies rules see our documentation on our policy plugin system. Using the policy plugin system you can enforce any policy rule that can be computed on a Turing Machine.
/etc/opk/providers/etc/opk/providers contains a list of allowed OPs (OpenID Providers), a.k.a. IDPs.
This file functions as an access control list that enables admins to determine the OpenID Providers and Client IDs they wish to rely on.
12h - user's ssh public key expires after 12 hours,24h - user's ssh public key expires after 24 hours,48h - user's ssh public key expires after 48 hours,1week - user's ssh public key expires after 1 week,oidc - user's ssh public key expires when the ID Token expiresoidc_refreshed - user's ssh public key expires when their refreshed ID Token expires.By default we use 24h as it requires that the user authenticate to their OP once a day. Most OPs expire ID Tokens every one to two hours, so if oidc the user will have to sign multiple times a day. oidc_refreshed is supported but complex and not currently recommended unless you know what you are doing.
The default values for /etc/opk/providers are:
# Issuer Client-ID expiration-policy
https://accounts.google.com 206584157355-7cbe4s640tvm7naoludob4ut1emii7sf.apps.googleusercontent.com 24h
https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 096ce0a3-5e72-4da8-9c86-12924b294a01 24h
/etc/opk/providers requires the following permissions (by default we create all
暂无开放 Issues，或尚未同步最近议题。