DOCSEARCHbyAlgolia
Submit Docs

opkssh (OpenPubkey SSH)

repository·main·Indexed 24 days ago

https://github.com/openpubkey/opkssh

A tool for SSH access management using OpenID Connect (OIDC) identities instead of long-lived SSH keys. It generates SSH public keys containing PK Tokens (OIDC ID Tokens), allowing authentication via providers like Gmail or Microsoft. Includes client tools for macOS, Windows, and Linux, as well as server-side configuration for sshd via AuthorizedKeysCommand.

Tokens
27.9K
Snippets
78
Records
140
Agent score
84%

What's inside opkssh

  1. Use the opkssh CLI

    main

    The opkssh command-line tool enables SSH authentication using OpenID Connect (OIDC) identities. It allows users to generate SSH key pairs tied to their OIDC identity, manage authentication policies, and verify OpenPubkey SSH certificates for use with sshd's AuthorizedKeysCommand.

    opkssh [flags]

  2. How policy plugins work in opkssh

    main

    Policy plugins allow you to extend the default opkssh policy with custom logic. They function similarly to OpenSSH's AuthorizedKeysCommand.

    Key Concepts:

    • Validation Flow: Policy plugins do not bypass provider checks. The ID Token is first validated against the providers in /etc/opk/providers before the plugin is called.
    • Additive Logic (OR): Policy evaluation is additive. Access is granted if any policy returns allow. The logic follows: IF (any policy plugin returns allow) OR (standard auth_id policy returns allow) THEN allow ELSE deny.
    • Success Criteria: To grant access, your plugin command must output the string allow and exit with code 0. To deny, it should output deny and exit with a non-zero code.
    • Configuration: Create YAML configuration files in /etc/opk/policy.d/ to specify the command to be executed.
    name: Example plugin config
command: /etc/opk/plugin-cmd.sh

  3. Compare `opkssh audit` and `opkssh permissions`

    main

    While both commands check the system policy file (/etc/opk/auth_id on Linux, %ProgramData%\opk\auth_id on Windows), they serve different purposes:

    • opkssh audit: Validates the content of policy files. It ensures issuers are valid and entries match provider definitions. It is read-only and enumerates all user ~/.opk/auth_id files.
    • opkssh permissions: Validates and fixes filesystem permissions and ACLs. It focuses on file modes and ownership. It does not check the contents of user policy files. Use opkssh permissions fix to repair detected issues.

  4. How SSH via GitHub Actions works with opkssh

    main

    opkssh enables passwordless SSH from GitHub Actions workflows by leveraging GitHub's OpenID Connect (OIDC) tokens. Instead of managing static SSH keys, the workflow uses an OIDC token to prove its identity.

    When opkssh login github is executed within a GitHub Actions environment, it automatically detects the ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variables to fetch a token from https://token.actions.githubusercontent.com. The SSH server then verifies the resulting certificate against a local policy that defines which repositories and references (branches, tags, or pull requests) are authorized.

  5. Set up SSH AuthorizedKeysCommand for opkssh

    main

    To integrate opkssh with the SSH daemon, you must configure the AuthorizedKeysCommand in /etc/ssh/sshd_config. This allows the SSH daemon to call opkssh to verify keys.

    opkssh uses a low-privilege system user named opksshuser to execute the verification command.

    1. Create the system user (if not already done by install script):

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

    2. Update /etc/ssh/sshd_config: Add the following lines:

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

  6. Use `opkssh verify` as an AuthorizedKeysCommand

    main

    The opkssh verify command is designed to be used by sshd via the AuthorizedKeysCommand directive. It extracts a PK token from a base64-encoded SSH certificate and verifies it against configured policies.

    Verification Logic

    1. Token Integrity: Ensures the PK token is properly formed, signed, and issued by a specified OpenID Provider (OP).
    2. Provider Validation: Confirms the token's issuer (iss) and client ID (aud) are listed in the allowed provider file located at /etc/opk/providers and that the token is not expired.
    3. Identity Mapping: Validates the identity (email or sub) in the PK token against user policy files located at /etc/opk/auth_id or ~/.opk/auth_id to ensure the identity is authorized to assume the requested principal (username).

    Integration with sshd

    To integrate opkssh with sshd, add the following lines to /etc/ssh/sshd_config:

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

    Where the placeholders are defined by sshd as:

    • %%u: Target username (requested principal).
    • %%k: Base64-encoded SSH public key (SSH certificate) provided for authentication.
    • %%t: Public key type (e.g., ecdsa-sha2-nistp256-cert-v01@openssh.com).
    opkssh verify root <base64-encoded-cert> ecdsa-sha2-nistp256-cert-v01@openssh.com

  7. Authenticate and generate SSH keys with `opkssh login`

    main

    Use the opkssh login command to authenticate with an OpenID Provider and generate a temporary SSH key pair.

    Workflow:

    1. The command generates a key pair.
    2. It opens a browser for OpenID authentication.
    3. Upon success, it creates an SSH public key (defaulting to ~/.ssh/id_ecdsa) containing your PK token.
    4. By default, this key expires after 24 hours, requiring a re-login.

    Arguments:

    • alias: The provider alias to use. If omitted, the OPKSSH_DEFAULT environment variable is used. Aliases are defined in the OPKSSH_PROVIDERS environment variable using the format: <alias>,<issuer>,<client_id>,<client_secret>,<scopes>.
    opkssh login [alias] [flags]

  8. Configure and set up policy plugins

    main

    To implement a custom policy, follow these steps:

    1. Create a configuration file in /etc/opk/policy.d/*.yml. This file must define a name and a command.
    2. Create the plugin command script (e.g., /etc/opk/plugin-cmd.sh) that reads environment variables and outputs allow or deny.
    3. Set strict permissions to ensure only root can modify policies:

    For the config file (/etc/opk/policy.d/example-plugin.yml):

    • Ownership: root:opksshuser
    • Permissions: 640

    For the command script (/etc/opk/plugin-cmd.sh):

    • Ownership: root:opksshuser
    • Permissions: 755 or 555
    # Config file permissions
chmod 640 /etc/opk/policy.d/example-plugin.yml
chown root:opksshuser /etc/opk/policy.d/example-plugin.yml

# Command script permissions
chmod 755 /etc/opk/plugin-cmd.sh
chown root:opksshuser /etc/opk/plugin-cmd.sh

  9. Remove opkssh-generated keys with opkssh logout

    main

    Use the opkssh logout command to remove SSH keys and certificates that were generated by opkssh.

    By default, the command searches standard SSH locations (~/.ssh/) and the opkssh identity directory (~/.ssh/opkssh/) to identify and remove opkssh-generated material.

    To remove a specific key pair instead of performing a global cleanup, use the -i or --private-key-file flag followed by the path to the private key.

  10. Configure Cognito App Client for OPKSSH

    main

    After creating your App Client, you must modify its settings to support OPKSSH redirect URIs and required OIDC scopes:

    1. Edit Login Info

    In your User Pool, go to "App clients" > [Your App Name] > "Login pages" > "Edit".

    Under "Allowed callback URLs", add the following three URLs:

    http://localhost:3000/login-callback
http://localhost:10001/login-callback
http://localhost:11110/login-callback

    Under "OpenID Connect Scopes", you MUST remove Phone and add Profile. The required scopes for OPKSSH are openid, profile, and email.

    Click "Save Changes".

    2. Add a Managed Login page

    If your app does not have a managed login style (indicated by a - in the "Managed login style" section):

    1. Go to "Managed login" in the left-hand sidebar.
    2. Under "Styles", click "Create a new style".
    3. Select your app and click "Create".

  12. Register an Azure (Entra ID) App for OPKSSH

    main

    To use Azure/Entra ID with OPKSSH, you must register an application in the Azure Portal.

    1. Sign into the Azure Portal and navigate to Entra ID.
    2. Select App Registrations and click Add.
    3. Enter openpubkey as the app name.
    4. Configure the first Redirect URI: http://localhost:3000/login-callback. Ensure you select public client for the redirect URI type.
    5. Note the Client ID and Tenant ID (Directory ID).
    6. Add the remaining two Redirect URIs: http://localhost:10001/login-callback and http://localhost:11110/login-callback. Do not include a trailing slash /.
    7. Under Advanced Settings, set Allow Public Client Flows to Yes. This is required for OPKSSH to function.
    8. Save your changes.
    Redirect URIs to add:
http://localhost:3000/login-callback
http://localhost:10001/login-callback
http://localhost:11110/login-callback