doc/admin/host_config.rst

   1 Host configuration
   2 ==================
   3
   4 All hosts running Kerberos software, whether they are clients,
   5 application servers, or KDCs, can be configured using
   6 :ref:`krb5.conf(5)`.  Here we describe some of the behavior changes
   7 you might want to make.
   8
   9
  10 Default realm
  11 -------------
  12
  13 In the :ref:`libdefaults` section, the **default_realm** realm
  14 relation sets the default Kerberos realm.  For example::
  15
  16     [libdefaults]
  17         default_realm = ATHENA.MIT.EDU
  18
  19 The default realm affects Kerberos behavior in the following ways:
  20
  21 * When a principal name is parsed from text, the default realm is used
  22   if no ``@REALM`` component is specified.
  23
  24 * The default realm affects login authorization as described below.
  25
  26 * For programs which operate on a Kerberos database, the default realm
  27   is used to determine which database to operate on, unless the **-r**
  28   parameter is given to specify a realm.
  29
  30 * A server program may use the default realm when looking up its key
  31   in a :ref:`keytab file <keytab_file>`, if its realm is not
  32   determined by :ref:`domain_realm` configuration or by the server
  33   program itself.
  34
  35 * If :ref:`kinit(1)` is passed the **-n** flag, it requests anonymous
  36   tickets from the default realm.
  37
  38 In some situations, these uses of the default realm might conflict.
  39 For example, it might be desirable for principal name parsing to use
  40 one realm by default, but for login authorization to use a second
  41 realm.  In this situation, the first realm can be configured as the
  42 default realm, and **auth_to_local** relations can be used as
  43 described below to use the second realm for login authorization.
  44
  45
  46 .. _login_authorization:
  47
  48 Login authorization
  49 -------------------
  50
  51 If a host runs a Kerberos-enabled login service such as OpenSSH with
  52 GSSAPIAuthentication enabled, login authorization rules determine
  53 whether a Kerberos principal is allowed to access a local account.
  54
  55 By default, a Kerberos principal is allowed access to an account if
  56 its realm matches the default realm and its name matches the account
  57 name.  (For historical reasons, access is also granted by default if
  58 the name has two components and the second component matches the
  59 default realm; for instance, ``alice/ATHENA.MIT.EDU@ATHENA.MIT.EDU``
  60 is granted access to the ``alice`` account if ``ATHENA.MIT.EDU`` is
  61 the default realm.)
  62
  63 The simplest way to control local access is using :ref:`.k5login(5)`
  64 files.  To use these, place a ``.k5login`` file in the home directory
  65 of each account listing the principal names which should have login
  66 access to that account.  If it is not desirable to use ``.k5login``
  67 files located in account home directories, the **k5login_directory**
  68 relation in the :ref:`libdefaults` section can specify a directory
  69 containing one file per account uname.
  70
  71 By default, if a ``.k5login`` file is present, it controls
  72 authorization both positively and negatively--any principal name
  73 contained in the file is granted access and any other principal name
  74 is denied access, even if it would have had access if the ``.k5login``
  75 file didn't exist.  The **k5login_authoritative** relation in the
  76 :ref:`libdefaults` section can be set to false to make ``.k5login``
  77 files provide positive authorization only.
  78
  79 The **auth_to_local** relation in the :ref:`realms` section for the
  80 default realm can specify pattern-matching rules to control login
  81 authorization.  For example, the following configuration allows access
  82 to principals from a different realm than the default realm::
  83
  84     [realms]
  85         DEFAULT.REALM = {
  86             # Allow access to principals from OTHER.REALM.
  87             #
  88             # [1:$1@$0] matches single-component principal names and creates
  89             # a selection string containing the principal name and realm.
  90             #
  91             # (.*@OTHER\.REALM) matches against the selection string, so that
  92             # only principals in OTHER.REALM are matched.
  93             #
  94             # s/@OTHER\.REALM$// removes the realm name, leaving behind the
  95             # principal name as the account name.
  96             auth_to_local = RULE:[1:$1@$0](.*@OTHER\.REALM)s/@OTHER\.REALM$//
  97
  98             # Also allow principals from the default realm.  Omit this line
  99             # to only allow access to principals in OTHER.REALM.
 100             auth_to_local = DEFAULT
 101         }
 102
 103 The **auth_to_local_names** subsection of the :ref:`realms` section
 104 for the default realm can specify explicit mappings from principal
 105 names to local accounts.  The key used in this subsection is the
 106 principal name without realm, so it is only safe to use in a Kerberos
 107 environment with a single realm or a tightly controlled set of realms.
 108 An example use of **auth_to_local_names** might be::
 109
 110     [realms]
 111         ATHENA.MIT.EDU = {
 112             auth_to_local_names = {
 113                 # Careful, these match principals in any realm!
 114                 host/example.com = hostaccount
 115                 fred = localfred
 116             }
 117         }
 118
 119 Local authorization behavior can also be modified using plugin
 120 modules; see :ref:`hostrealm_plugin` for details.
 121
 122
 123 .. _plugin_config:
 124
 125 Plugin module configuration
 126 ---------------------------
 127
 128 Many aspects of Kerberos behavior, such as client preauthentication
 129 and KDC service location, can be modified through the use of plugin
 130 modules.  For most of these behaviors, you can use the :ref:`plugins`
 131 section of krb5.conf to register third-party modules, and to switch
 132 off registered or built-in modules.
 133
 134 A plugin module takes the form of a Unix shared object
 135 (``modname.so``) or Windows DLL (``modname.dll``).  If you have
 136 installed a third-party plugin module and want to register it, you do
 137 so using the **module** relation in the appropriate subsection of the
 138 [plugins] section.  The value for **module** must give the module name
 139 and the path to the module, separated by a colon.  The module name
 140 will often be the same as the shared object's name, but in unusual
 141 cases (such as a shared object which implements multiple modules for
 142 the same interface) it might not be.  For example, to register a
 143 client preauthentication module named ``mypreauth`` installed at
 144 ``/path/to/mypreauth.so``, you could write::
 145
 146     [plugins]
 147         clpreauth = {
 148             module = mypreauth:/path/to/mypreauth.so
 149         }
 150
 151 Many of the pluggable behaviors in MIT krb5 contain built-in modules
 152 which can be switched off.  You can disable a built-in module (or one
 153 you have registered) using the **disable** directive in the
 154 appropriate subsection of the [plugins] section.  For example, to
 155 disable the use of .k5identity files to select credential caches, you
 156 could write::
 157
 158     [plugins]
 159         ccselect = {
 160             disable = k5identity
 161         }
 162
 163 If you want to disable multiple modules, specify the **disable**
 164 directive multiple times, giving one module to disable each time.
 165
 166 Alternatively, you can explicitly specify which modules you want to be
 167 enabled for that behavior using the **enable_only** directive.  For
 168 example, to make :ref:`kadmind(8)` check password quality using only a
 169 module you have registered, and no other mechanism, you could write::
 170
 171     [plugins]
 172         pwqual = {
 173             module = mymodule:/path/to/mymodule.so
 174             enable_only = mymodule
 175         }
 176
 177 Again, if you want to specify multiple modules, specify the
 178 **enable_only** directive multiple times, giving one module to enable
 179 each time.
 180
 181 Some Kerberos interfaces use different mechanisms to register plugin
 182 modules.
 183
 184
 185 KDC location modules
 186 ~~~~~~~~~~~~~~~~~~~~
 187
 188 For historical reasons, modules to control how KDC servers are located
 189 are registered simply by placing the shared object or DLL into the
 190 "libkrb5" subdirectory of the krb5 plugin directory, which defaults to
 191 |libdir|\ ``/krb5/plugins``.  For example, Samba's winbind krb5
 192 locator plugin would be registered by placing its shared object in
 193 |libdir|\ ``/krb5/plugins/libkrb5/winbind_krb5_locator.so``.
 194
 195
 196 .. _gssapi_plugin_config:
 197
 198 GSSAPI mechanism modules
 199 ~~~~~~~~~~~~~~~~~~~~~~~~
 200
 201 GSSAPI mechanism modules are registered using the file
 202 |sysconfdir|\ ``/gss/mech`` or configuration files in the
 203 |sysconfdir|\ ``/gss/mech.d`` directory with a ``.conf``
 204 suffix.  Each line in these files has the form::
 205
 206     name  oid  pathname  [options]  <type>
 207
 208 Only the name, oid, and pathname are required.  *name* is the
 209 mechanism name, which may be used for debugging or logging purposes.
 210 *oid* is the object identifier of the GSSAPI mechanism to be
 211 registered.  *pathname* is a path to the module shared object or DLL.
 212 *options* (if present) are options provided to the plugin module,
 213 surrounded in square brackets.  *type* (if present) can be used to
 214 indicate a special type of module.  Currently the only special module
 215 type is "interposer", for a module designed to intercept calls to
 216 other mechanisms.
 217
 218 If the environment variable **GSS_MECH_CONFIG** is set, its value is
 219 used as the sole mechanism configuration filename.
 220
 221
 222 .. _profile_plugin_config:
 223
 224 Configuration profile modules
 225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 226
 227 A configuration profile module replaces the information source for
 228 :ref:`krb5.conf(5)` itself.  To use a profile module, begin krb5.conf
 229 with the line::
 230
 231     module PATHNAME:STRING
 232
 233 where *PATHNAME* is a path to the module shared object or DLL, and
 234 *STRING* is a string to provide to the module.  The module will then
 235 take over, and the rest of krb5.conf will be ignored.