From: Greg Hudson <ghudson@mit.edu>
Date: Mon, 16 Mar 2020 22:14:30 +0000 (-0400)
Subject: Document client keytab usage
X-Git-Tag: krb5-1.19-beta1~104
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F1050%2Fhead;p=thirdparty%2Fkrb5.git

Document client keytab usage

ticket: 8886 (new)
tags: pullup
target_version: 1.18-next
---

diff --git a/doc/admin/appl_servers.rst b/doc/admin/appl_servers.rst
index fee49f027a..5232db9af0 100644
--- a/doc/admin/appl_servers.rst
+++ b/doc/admin/appl_servers.rst
@@ -60,6 +60,43 @@ To remove a principal from an existing keytab, use the kadmin
    :end-before: _ktremove_end:
 
 
+Using a keytab to acquire client credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While keytabs are ordinarily used to accept credentials from clients,
+they can also be used to acquire initial credentials, allowing one
+service to authenticate to another.
+
+To manually obtain credentials using a keytab, use the :ref:`kinit(1)`
+**-k** option, together with the **-t** option if the keytab is not in
+the default location.
+
+Beginning with release 1.11, GSSAPI applications can be configured to
+automatically obtain initial credentials from a keytab as needed.  The
+recommended configuration is as follows:
+
+#. Create a keytab containing a single entry for the desired client
+   identity.
+
+#. Place the keytab in a location readable by the service, and set the
+   **KRB5_CLIENT_KTNAME** environment variable to its filename.
+   Alternatively, use the **default_client_keytab_name** profile
+   variable in :ref:`libdefaults`, or use the default location of
+   |ckeytab|.
+
+#. Set **KRB5CCNAME** to a filename writable by the service, which
+   will not be used for any other purpose.  Do not manually obtain
+   credentials at this location.  (Another credential cache type
+   besides **FILE** can be used if desired, as long the cache will not
+   conflict with another use.  A **MEMORY** cache can be used if the
+   service runs as a long-lived process.  See :ref:`ccache_definition`
+   for details.)
+
+#. Start the service.  When it authenticates using GSSAPI, it will
+   automatically obtain credentials from the client keytab into the
+   specified credential cache, and refresh them before they expire.
+
+
 Clock Skew
 ----------