From 9eacae526e0330ca1684eacae8eeffd2e5d04516 Mon Sep 17 00:00:00 2001
From: Seth Vargo <seth@sethvargo.com>
Date: Mon, 21 Aug 2017 17:22:54 -0400
Subject: [PATCH] Addd more SSH CA troubleshooting (#3201)

* Add notes about pty and other permit-* extensions

* Update troubleshooting

* Add an example of JSON for sign

* Fix a bug about what keys to push up
---
 .../ssh/signed-ssh-certificates.html.md       | 149 +++++++++++++++++-
 1 file changed, 147 insertions(+), 2 deletions(-)

diff --git a/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md b/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md
index 759f3a34b2..f5b0e4d966 100644
--- a/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md
+++ b/website/source/docs/secrets/ssh/signed-ssh-certificates.html.md
@@ -146,6 +146,21 @@ the contents begin with `ssh-rsa ...`.
     The result will include the serial and the signed key. This signed key is
     another public key.
 
+    To customize the signing options, use a JSON payload:
+
+    ```text
+    $ vault write ssh-client-signer/sign/my-role -<<"EOH"
+    {
+      "public_key": "ssh-rsa AAA...",
+      "valid_principals": "my-user",
+      "key_id": "custom-prefix",
+      "extension": {
+        "permit-pty": ""
+      }
+    }
+    EOH
+    ```
+
 1. Save the resulting signed, public key to disk. Limit permissions as needed.
 
     ```text
@@ -164,10 +179,12 @@ key.
     $ ssh-keygen -Lf ~/.ssh/signed-cert.pub
     ```
 
-1. SSH into the host machine using the signed key.
+1. SSH into the host machine using the signed key. You must supply both the
+signed public key from Vault **and** the corresponding private key as
+authentication to the SSH call.
 
     ```text
-    $ ssh -i signed-cert.pub username@10.0.23.5
+    $ ssh -i signed-cert.pub -i ~/.ssh/id_rsa username@10.0.23.5
     ```
 
 ## Host Key Signing
@@ -317,6 +334,134 @@ $ tail -f /var/log/auth.log | grep --line-buffered "sshd"
 If you are unable to make a connection to the host, the SSH server logs may
 provide guidance and insights.
 
+### Name is not a listed principal
+
+If the `auth.log` displays the following messages:
+
+```text
+# /var/log/auth.log
+key_cert_check_authority: invalid certificate
+Certificate invalid: name is not a listed principal
+```
+
+The certificate does not permit the username as a listed principal for
+authenticating to the system. This is most likely due to an OpenSSH bug (see
+[known issues](#known-issues) for more information). This bug does not respect
+the `allowed_users` option value of "\*". Here are ways to work around this
+issue:
+
+1. Set `default_user` in the role. If you are always authenticating as the same
+user, set the `default_user` in the role to the username you are SSHing into the
+target machine:
+
+    ```text
+    $ vault write ssh/roles/my-role -<<"EOH"
+    {
+      "default_user": "YOUR_USER",
+      // ...
+    }
+    EOH
+    ```
+
+1. Set `valid_principals` during signing. In situations where multiple users may
+be authenticating to SSH via Vault, set the list of valid principles during key
+signing to include the current username:
+
+    ```text
+    $ vault write ssh-client-signer/sign/my-role -<<"EOH"
+    {
+      "valid_principals": "my-user"
+      // ...
+    }
+    EOH
+    ```
+
+
+### No Prompt After Login
+
+If you do not see a prompt after authenticating to the host machine, the signed
+certificate may not have the `permit-pty` extension. There are two ways to add
+this extension to the signed certificate.
+
+- As part of the role creation
+
+    ```text
+    $ vault write ssh-client-signer/roles/my-role -<<"EOH"
+    {
+      "default_extensions": [
+        {
+          "permit-pty": ""
+        }
+      ]
+      // ...
+    }
+    EOH
+    ```
+
+- As part of the signing operation itself:
+
+    ```text
+    $ vault write ssh-client-signer/sign/my-role -<<"EOH"
+    {
+      "extension": {
+        "permit-pty": ""
+      }
+      // ...
+    }
+    EOH
+    ```
+
+### No Port Forwarding
+
+If port forwarding from the guest to the host is not working, the signed
+certificate may not have the `permit-port-forwarding` extension. Add the
+extension as part of the role creation or signing process to enable port
+forwarding. See [no prompt after login](#no-prompt-after-login) for examples.
+
+```json
+{
+  "default_extensions": [
+    {
+      "permit-port-forwarding": ""
+    }
+  ]
+}
+```
+
+### No X11 Forwarding
+
+If X11 forwarding from the guest to the host is not working, the signed
+certificate may not have the `permit-X11-forwarding` extension. Add the
+extension as part of the role creation or signing process to enable X11
+forwarding. See [no prompt after login](#no-prompt-after-login) for examples.
+
+```json
+{
+  "default_extensions": [
+    {
+      "permit-X11-forwarding": ""
+    }
+  ]
+}
+```
+
+### No Agent Forwarding
+
+If agent forwarding from the guest to the host is not working, the signed
+certificate may not have the `permit-agent-forwarding` extension. Add the
+extension as part of the role creation or signing process to enable agent
+forwarding. See [no prompt after login](#no-prompt-after-login) for examples.
+
+```json
+{
+  "default_extensions": [
+    {
+      "permit-agent-forwarding": ""
+    }
+  ]
+}
+```
+
 ### Known Issues
 
 - On SELinux-enforcing systems, you may need to adjust related types so that the