Documentation: Also consider the use of kerberos authentication over SSH

Most documentation assumed the use of SSH public key authentication. This
change removes that assumption and adds some hints on client configuration
with OpenSSH and kerberos.

Change-Id: I4d5654a088a68afd740d3e4e91eaf15d0bbf58b1

Documentation/cmd-apropos.txt

@@ -15,7 +15,7 @@ Queries the documentation index and returns results with the title and URL
 from the matched documents.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-ls-groups.txt

@@ -23,7 +23,7 @@ If the caller is a member of the privileged 'Administrators' group,
 all groups are listed.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-ls-members.txt

@@ -16,7 +16,7 @@ group is visible to the user. The users' id, username, full name and email are
 shown tab-separated.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts. Output is either an error

Documentation/cmd-ls-projects.txt

@@ -25,7 +25,7 @@ If the caller is a member of the privileged 'Administrators'
 group, all projects are listed.
 
 == ACCESS
-Any user who has configured an SSH key, or by an user over HTTP.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-query.txt

@@ -108,7 +108,7 @@ limit:<n>::
 	will be used to cut the result set.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-receive-pack.txt

@@ -37,7 +37,7 @@ to 'git push', which will relay them automatically.
 	Deprecated, use `refs/for/branch%cc=address` instead.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == EXAMPLES
 

Documentation/cmd-review.txt

@@ -150,7 +150,7 @@ branch.
   invocations of the SSH command are required.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-set-members.txt

@@ -49,7 +49,7 @@ The `set-members` command is processing the options in the following
 order: `--remove`, `--exclude`, `--add`, `--include`
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-set-reviewers.txt

@@ -47,7 +47,7 @@ API.
 	Display site-specific usage information
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/cmd-version.txt

@@ -26,7 +26,7 @@ describe` documentation for details on how `<tagname>` is chosen and how
 `<n>` is computed.
 
 == ACCESS
-Any user who has configured an SSH key.
+Any user who has SSH access to Gerrit.
 
 == SCRIPTING
 This command is intended to be used in scripts.

Documentation/error-permission-denied.txt

@@ -3,15 +3,20 @@
 With this error message an SSH command to Gerrit is rejected if the
 SSH authentication is not successful.
 
-The link:http://en.wikipedia.org/wiki/Secure_Shell[SSH] protocol uses link:http://en.wikipedia.org/wiki/Public-key_cryptography[Public-key Cryptography] for authentication.
+The link:http://en.wikipedia.org/wiki/Secure_Shell[SSH] protocol can use
-This means for a successful SSH authentication you need your private
+link:http://en.wikipedia.org/wiki/Public-key_cryptography[Public-key Cryptography]
-SSH key and the corresponding public SSH key must be known to Gerrit.
+for authentication.
+In general configurations, Gerrit will authenticate you by the public keys
+known to you. Optionally, it can be configured by the administrator to allow
+for link:config-gerrit.html#sshd.kerberosKeytab[kerberos] authentication
+instead.
 
-If you are facing this problem, do the following:
+In any case, verify that you are using the correct username for the SSH command
+and that it is typed correctly (case sensitive). You can look up your username
+in the Gerrit Web UI under 'Settings' -> 'Profile'.
+
+If you are facing this problem and using an SSH keypair, do the following:
 
-. Verify that you are using the correct username for the SSH command
-  and that it is typed correctly (case sensitive). You can look up
-  your username in the Gerrit Web UI under 'Settings' -> 'Profile'.
 . Verify that you have uploaded your public SSH key for your Gerrit
   account. To do this go in the Gerrit Web UI to 'Settings' ->
   'SSH Public Keys' and check that your public SSH key is there. If
@@ -21,6 +26,19 @@ If you are facing this problem, do the following:
   described below. From the trace you should see which private SSH
   key is used.
 
+Debugging kerberos issues can be quite hard given the complexity of the
+protocol. In case you are using kerberos authentication, do the following:
+
+. Verify that you have acquired a valid initial ticket. On a Linux machine, you
+  can acquire one using the `kinit` command. List all your tickets using the
+  `klist` command. It should list all principals for which you have acquired a
+  ticket and include a principal name corresponding to your Gerrit server, for
+  example `HOST/gerrit.mydomain.tld@MYDOMAIN.TLD`.
+  Note that tickets can expire and require you to re-run `kinit` periodically.
+. Verify that your SSH client is using kerberos authentication. For OpenSSH
+  clients this can be controlled using the `GSSAPIAuthentication` setting.
+  For more information see
+  link:user-upload.html#configure_ssh_kerberos[SSH kerberos configuration].
 
 == Test SSH authentication
 

Documentation/intro-user.txt

@@ -56,8 +56,8 @@ For git operations Gerrit supports the link:user-upload.html#ssh[SSH]
 and the link:user-upload.html#http[HTTP/HTTPS] protocols.
 
 [NOTE]
-To use SSH you must link:user-upload.html#configure_ssh[generate an SSH
+To use SSH you may need to link:user-upload.html#ssh[configure your SSH public
-key pair and upload the public SSH key to Gerrit].
+key in your `Settings`].
 
 [[code-review]]
 == Code Review Workflow

Documentation/user-upload.txt

@@ -9,8 +9,8 @@ Gerrit supports three methods of uploading changes:
 All three methods rely on authentication, which must first be configured
 by the uploading user.
 
-Gerrit supports two methods of authenticating the uploading user.  SSH
+Gerrit supports two protocols for uploading changes; SSH and HTTP/HTTPS. These
-public key, and HTTP/HTTPS.
+may not all be available for you, depending on the server configuration.
 
 [[http]]
 == HTTP/HTTPS
@@ -41,13 +41,15 @@ not configured, the password can be obtained by clicking on `Generate Password`.
 [[ssh]]
 == SSH
 
-Each user uploading changes to Gerrit must configure one or more SSH
+To upload changes over SSH, Gerrit supports two forms of authentication: a
-public keys.  The per-user SSH key list can be accessed over the web
+user's public key or kerberos.
-within Gerrit by `Settings`, and then accessing the `SSH Public Keys`
-tab.
 
-[[configure_ssh]]
+Unless your Gerrit instance is configured to support
-=== Configuration
+link:config-gerrit.html#sshd.kerberosKeytab[kerberos] in your domain, only
+public key authentication can be used.
+
+[[configure_ssh_public_keys]]
+=== Public keys
 
 To register a new SSH key for use with Gerrit, paste the contents of
 your `id_rsa.pub` or `id_dsa.pub` file into the text box and click
@@ -79,10 +81,29 @@ key's passphrase.  Consult `man ssh-agent`, or your SSH client's
 documentation, for more details on configuration of the agent
 process and how to add the private key.
 
+[[configure_ssh_kerberos]]
+=== Kerberos
+
+A kerberos-enabled server configuration allows for zero configuration in an
+existing single-sign-on environment.
+
+Your SSH client should be configured to enable kerberos authentication. For
+OpenSSH clients, this is controlled by the option `GSSAPIAuthentication` which
+should be set to `yes`.
+
+Some Linux distributions have packaged OpenSSH to enable this by default (e.g.
+Debian, Ubuntu). If this is not the case for your distribution, enable it for
+Gerrit with this entry in your local SSH configuration:
+
+----
+Host gerrit.mydomain.tld
+    GSSAPIAuthentication yes
+----
+
 [[test_ssh]]
 === Testing Connections
 
-To verify your SSH key is working correctly, try using an SSH client
+To verify your SSH authentication is working correctly, try using an SSH client
 to connect to Gerrit's SSHD port.  By default Gerrit runs on
 port 29418, using the same hostname as the web server: