Document client keytab usage

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

1 files changed, 37 insertions, 0 deletions

diff --git a/doc/admin/appl_servers.rst b/doc/admin/appl_servers.rst
index fee49f0..5232db9 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
 ----------