{"id":13645317,"url":"https://github.com/hashicorp/vault-ssh-helper","last_synced_at":"2025-10-04T22:37:05.777Z","repository":{"id":2003271,"uuid":"38991056","full_name":"hashicorp/vault-ssh-helper","owner":"hashicorp","description":"Vault SSH Agent is used to enable one time keys and passwords","archived":false,"fork":false,"pushed_at":"2024-08-02T16:59:55.000Z","size":4032,"stargazers_count":426,"open_issues_count":18,"forks_count":56,"subscribers_count":293,"default_branch":"main","last_synced_at":"2025-03-28T14:08:13.636Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hashicorp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-13T04:22:16.000Z","updated_at":"2025-03-08T16:02:17.000Z","dependencies_parsed_at":"2024-01-14T09:30:46.580Z","dependency_job_id":"aeef6aca-5328-4874-acbb-c6181cc43193","html_url":"https://github.com/hashicorp/vault-ssh-helper","commit_stats":{"total_commits":154,"total_committers":28,"mean_commits":5.5,"dds":0.5064935064935066,"last_synced_commit":"8bcbbc7be7b6fce963085082f6532a54b5290787"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fvault-ssh-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fvault-ssh-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fvault-ssh-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fvault-ssh-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hashicorp","download_url":"https://codeload.github.com/hashicorp/vault-ssh-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198463,"owners_count":20900080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T01:02:33.440Z","updated_at":"2025-10-04T22:37:00.734Z","avatar_url":"https://github.com/hashicorp.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"vault-ssh-helper[![Build Status](https://travis-ci.org/hashicorp/vault-ssh-helper.svg)](https://travis-ci.org/hashicorp/vault-ssh-helper)\n===============\n\n**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, _please responsibly disclose_ by contacting us at [security@hashicorp.com](mailto:security@hashicorp.com).\n\n----\n\n`vault-ssh-helper` is a counterpart to [HashiCorp\nVault's](https://github.com/hashicorp/vault) SSH backend. It allows a machine\nto consume One-Time-Passwords (OTP) created by Vault servers by allowing them\nto be used as client authentication credentials at SSH connection time.\n\nAll of the remote hosts that belong to the SSH backend's OTP-type roles will\nneed this helper installed. In addition, each host must have its SSH\nconfiguration changed to enable keyboard-interactive authentication and\nredirect its client authentication responsibility to `vault-ssh-helper`.\n\nVault-authenticated users contact the Vault server and retrieve an OTP issued\nfor a specific username and IP address. While establishing an SSH connection to\nthe host, the `vault-ssh-helper` binary reads the OTP from the password prompt\nand sends it to the Vault server for verification. Client authentication is\nsuccessful (and the SSH connection allowed) only if the Vault server verifies\nthe OTP. True to its name, once the OTP has been used a single time for\nauthentication, it is removed from Vault and cannot be used again.\n\n`vault-ssh-helper` is not a PAM module, but it does the job of one.\n`vault-ssh-helper`'s binary is run as an external command using `pam_exec.so`\nwith access to the entered password (in this case, the issued OTP). Successful\nexecution and exit of this command is a PAM 'requisite' for authentication to\nbe successful. If the OTP is not validated, the binary exits with a non-zero\nstatus and authentication fails.\n\nPAM modules are generally shared object files; rather than writing and\nmaintaining a PAM module in C, `vault-ssh-helper` is written in Go and invoked\nas an external binary. This allows `vault-ssh-helper` to be contained within\none code base with known, testable behavior. It also allows other\nauthentication systems that are not PAM-based to invoke `vault-ssh-helper` and\ntake advantage of its capabilities.\n\n## Usage\n-----\n`vault-ssh-helper [options]`\n\n### Options\n| Option        | Description                                                                                                                 |\n|---------------|-----------------------------------------------------------------------------------------------------------------------------|\n| `verify-only` | Verifies that `vault-ssh-helper` is installed correctly and is able to communicate with Vault.                              |\n| `config`      | The path to the configuration file. Configuration options are detailed below.                                               |\n| `dev`         | `vault-ssh-helper` communicates with Vault with TLS disabled. This is NOT recommended for production use. Use with caution. |\n| `log-level`   | Level of logs to output. Defaults to `info`. Supported values are `off`, `trace`, `debug`, `info`, `warn`, and `error`.     |\n\n## Download vault-ssh-helper\n\nDownload the latest version of `vault-ssh-helper` at [releases.hashicorp.com](https://releases.hashicorp.com/vault-ssh-helper).\n\n## Build and Install\n-----\n\nYou'll first need Go installed on your machine (version 1.8+ is required).\n\nInstall `Go` on your machine and set `GOPATH` accordingly. Clone this\nrepository into $GOPATH/src/github.com/hashicorp/vault-ssh-helper. Install all\nof the dependent binaries like `godep`, `gox`, `vet`, etc. by bootstrapping the\nenvironment:\n\n```shell\n$ make updatedeps\n```\n\nBuild and install `vault-ssh-helper`:\n\n```shell\n$ make\n$ make install\n```\n\nFollow the instructions below to modify your SSH server configuration, PAM\nconfiguration and `vault-ssh-helper` configuration. Check if `vault-ssh-helper`\nis installed and configured correctly and also is able to communicate with\nVault server properly. Before verifying `vault-ssh-helper`, make sure that the\nVault server is up and running and it has mounted the SSH backend.  Also, make\nsure that the mount path of the SSH backend is properly updated in\n`vault-ssh-helper`'s config file:\n\n```shell\n$ vault-ssh-helper -verify-only -config=\u003cpath-to-config-file\u003e\nUsing SSH Mount point: ssh\nvault-ssh-helper verification successful!\n```\n\nIf you intend to contribute to this project, compile a development version of\n`vault-ssh-helper` using `make dev`. This will put the binary in the `bin` and\n`$GOPATH/bin` folders.\n\n```shell\n$ make dev\n```\n\nIf you're developing a specific package, you can run tests for just that\npackage by specifying the `TEST` variable. For example below, only `helper`\npackage tests will be run.\n\n```sh\n$ make test TEST=./helper\n...\n```\n\nIf you intend to cross compile the binary, run `make bin`.\n\n`vault-ssh-helper` Configuration\n-------------------\n**[Note]: This configuration is applicable for Ubuntu 14.04. SSH/PAM\nconfigurations differ with each platform and distribution.**\n\n`vault-ssh-helper`'s configuration is written in [HashiCorp Configuration\nLanguage (HCL)](https://github.com/hashicorp/hcl).  By proxy, this means that\n`vault-ssh-helper`'s configuration is JSON-compatible. For more information,\nplease see the [HCL Specification](https://github.com/hashicorp/hcl).\n\n### Properties\n|Property           |Description|\n|-------------------|-----------|\n|`vault_addr`       |[Required] Address of the Vault server.\n|`ssh_mount_point`  |[Required] Mount point of SSH backend in Vault server.\n|`namespace`        |Namespace of the SSH mount. (Vault Enterprise only)\n|`ca_cert`          |Path of a PEM-encoded CA certificate file used to verify the Vault server's TLS certificate. `-dev` mode ignores this value.\n|`ca_path`          |Path to directory of PEM-encoded CA certificate files used to verify the Vault server's TLS certiciate. `-dev` mode ignores this value.\n|`tls_skip_verify`  |Skip TLS certificate verification. Use with caution.\n|`allowed_roles`    |List of comma-separated Vault SSH roles. The OTP verification response from the server will contain the name of the role against which the OTP was issued. Specify which roles are allowed to login using this configuration. Set this to `*` to allow any role to perform a login.\n|`allowed_cidr_list`|List of comma-separated CIDR blocks. If the IP used by the user to connect to the host is different than the address(es) of the host's network interface(s) (for instance, if the address is NAT-ed), then `vault-ssh-helper` cannot authenticate the IP. In these cases, the IP returned by Vault will be matched with the CIDR blocks in this list. If it matches, the authentication succeeds. (Use with caution)\n\nSample `config.hcl`:\n\n```hcl\nvault_addr = \"https://vault.example.com:8200\"\nssh_mount_point = \"ssh\"\nnamespace = \"my_namespace\"\nca_cert = \"/etc/vault-ssh-helper.d/vault.crt\"\ntls_skip_verify = false\nallowed_roles = \"*\"\n```\n\nPAM Configuration\n--------------------------------\nModify the `/etc/pam.d/sshd` file as follows; each option will be explained\nbelow.\n\n```\n#@include common-auth\nauth requisite pam_exec.so quiet expose_authtok log=/tmp/vaultssh.log /usr/local/bin/vault-ssh-helper -config=/etc/vault-ssh-helper.d/config.hcl\nauth optional pam_unix.so not_set_pass use_first_pass nodelay\n```\n\nFirst, the previous authentication mechanism `common-auth`, which is the\nstandard Linux authentication module, is commented out, in favor of using our\ncustom configuration.\n\nNext the authentication configuration for `vault-ssh-helper` is set.\n\n|Keyword           |Description |\n|------------------|------------|\n|`auth`            |PAM type that the configuration applies to.\n|`requisite`       |If the external command fails, the authentication should fail.\n|`pam_exec.so`     |PAM module that runs an external command (`vault-ssh-helper`).\n|`quiet`           |Suppress the exit status of `vault-ssh-helper` from being displayed.\n|`expose_authtok`  |Binary can read the password from stdin.\n|`log`             |Path to `vault-ssh-helper`'s log file.\n|`vault-ssh-helper`|Absolute path to `vault-ssh-helper`'s binary.\n|`config`          |The path to `vault-ssh-helper`'s config file.\n\nThe third line works around a bug between some versions of `pam_exec.so` and\n`vault-ssh-helper` that causes a successful authentication from\n`vault-ssh-helper` to fail due to some resources not being properly released.\nBecause it is marked as optional, it is essentially a no-op that ensures that\nPAM cleans up successfully, avoiding the bug.\n\n|Option           |Description |\n|-----------------|------------|\n|`auth`           |PAM type that the configuration applies to.\n|`optional`       |If the module fails, authentication does not fail (but if the OTP was invalid, we will have already failed previously).\n|`pam_unix.so`    |Linux's standard authentication module.\n|`not_set_pass`   |Module should not be allowed to set or modify passwords.\n|`use_first_pass` |Do not display password prompt again. Use the password from the previous module.\n|`nodelay`        |Avoids the induced delay after entering a wrong password.\n\nSSHD Configuration\n--------------------------------\nModify the `/etc/ssh/sshd_config` file. Note that for many distributions these\nare the default options; you may not need to set them explicitly but should\nverify their values if not.\n\n```\nChallengeResponseAuthentication yes\nUsePAM yes\nPasswordAuthentication no\n```\n\n|Option                               |Description |\n|-------------------------------------|------------|\n|`ChallengeResponseAuthentication yes`|[Required] Enable challenge response (keyboard-interactive) authentication.\n|`UsePAM yes`                         |[Required] Enable PAM authentication modules.\n|`PasswordAuthentication no`          |Disable password authentication.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fvault-ssh-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhashicorp%2Fvault-ssh-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fvault-ssh-helper/lists"}