xref: /freebsd/crypto/krb5/doc/admin/host_config.rst (revision b670c9bafc0e31c7609969bf374b2e80bdc00211)
1Host configuration
2==================
3
4All hosts running Kerberos software, whether they are clients,
5application servers, or KDCs, can be configured using
6:ref:`krb5.conf(5)`.  Here we describe some of the behavior changes
7you might want to make.
8
9
10Default realm
11-------------
12
13In the :ref:`libdefaults` section, the **default_realm** realm
14relation sets the default Kerberos realm.  For example::
15
16    [libdefaults]
17        default_realm = ATHENA.MIT.EDU
18
19The 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
38In some situations, these uses of the default realm might conflict.
39For example, it might be desirable for principal name parsing to use
40one realm by default, but for login authorization to use a second
41realm.  In this situation, the first realm can be configured as the
42default realm, and **auth_to_local** relations can be used as
43described below to use the second realm for login authorization.
44
45
46.. _login_authorization:
47
48Login authorization
49-------------------
50
51If a host runs a Kerberos-enabled login service such as OpenSSH with
52GSSAPIAuthentication enabled, login authorization rules determine
53whether a Kerberos principal is allowed to access a local account.
54
55By default, a Kerberos principal is allowed access to an account if
56its realm matches the default realm and its name matches the account
57name.  (For historical reasons, access is also granted by default if
58the name has two components and the second component matches the
59default realm; for instance, ``alice/ATHENA.MIT.EDU@ATHENA.MIT.EDU``
60is granted access to the ``alice`` account if ``ATHENA.MIT.EDU`` is
61the default realm.)
62
63The simplest way to control local access is using :ref:`.k5login(5)`
64files.  To use these, place a ``.k5login`` file in the home directory
65of each account listing the principal names which should have login
66access to that account.  If it is not desirable to use ``.k5login``
67files located in account home directories, the **k5login_directory**
68relation in the :ref:`libdefaults` section can specify a directory
69containing one file per account uname.
70
71By default, if a ``.k5login`` file is present, it controls
72authorization both positively and negatively--any principal name
73contained in the file is granted access and any other principal name
74is denied access, even if it would have had access if the ``.k5login``
75file didn't exist.  The **k5login_authoritative** relation in the
76:ref:`libdefaults` section can be set to false to make ``.k5login``
77files provide positive authorization only.
78
79The **auth_to_local** relation in the :ref:`realms` section for the
80default realm can specify pattern-matching rules to control login
81authorization.  For example, the following configuration allows access
82to 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
103The **auth_to_local_names** subsection of the :ref:`realms` section
104for the default realm can specify explicit mappings from principal
105names to local accounts.  The key used in this subsection is the
106principal name without realm, so it is only safe to use in a Kerberos
107environment with a single realm or a tightly controlled set of realms.
108An 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
119Local authorization behavior can also be modified using plugin
120modules; see :ref:`hostrealm_plugin` for details.
121
122
123.. _plugin_config:
124
125Plugin module configuration
126---------------------------
127
128Many aspects of Kerberos behavior, such as client preauthentication
129and KDC service location, can be modified through the use of plugin
130modules.  For most of these behaviors, you can use the :ref:`plugins`
131section of krb5.conf to register third-party modules, and to switch
132off registered or built-in modules.
133
134A plugin module takes the form of a Unix shared object
135(``modname.so``) or Windows DLL (``modname.dll``).  If you have
136installed a third-party plugin module and want to register it, you do
137so using the **module** relation in the appropriate subsection of the
138[plugins] section.  The value for **module** must give the module name
139and the path to the module, separated by a colon.  The module name
140will often be the same as the shared object's name, but in unusual
141cases (such as a shared object which implements multiple modules for
142the same interface) it might not be.  For example, to register a
143client 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
151Many of the pluggable behaviors in MIT krb5 contain built-in modules
152which can be switched off.  You can disable a built-in module (or one
153you have registered) using the **disable** directive in the
154appropriate subsection of the [plugins] section.  For example, to
155disable the use of .k5identity files to select credential caches, you
156could write::
157
158    [plugins]
159        ccselect = {
160            disable = k5identity
161        }
162
163If you want to disable multiple modules, specify the **disable**
164directive multiple times, giving one module to disable each time.
165
166Alternatively, you can explicitly specify which modules you want to be
167enabled for that behavior using the **enable_only** directive.  For
168example, to make :ref:`kadmind(8)` check password quality using only a
169module 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
177Again, if you want to specify multiple modules, specify the
178**enable_only** directive multiple times, giving one module to enable
179each time.
180
181Some Kerberos interfaces use different mechanisms to register plugin
182modules.
183
184
185KDC location modules
186~~~~~~~~~~~~~~~~~~~~
187
188For historical reasons, modules to control how KDC servers are located
189are 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
192locator 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
198GSSAPI mechanism modules
199~~~~~~~~~~~~~~~~~~~~~~~~
200
201GSSAPI 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``
204suffix.  Each line in these files has the form::
205
206    name  oid  pathname  [options]  <type>
207
208Only the name, oid, and pathname are required.  *name* is the
209mechanism name, which may be used for debugging or logging purposes.
210*oid* is the object identifier of the GSSAPI mechanism to be
211registered.  *pathname* is a path to the module shared object or DLL.
212*options* (if present) are options provided to the plugin module,
213surrounded in square brackets.  *type* (if present) can be used to
214indicate a special type of module.  Currently the only special module
215type is "interposer", for a module designed to intercept calls to
216other mechanisms.
217
218If the environment variable **GSS_MECH_CONFIG** is set, its value is
219used as the sole mechanism configuration filename.
220
221
222.. _profile_plugin_config:
223
224Configuration profile modules
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227A configuration profile module replaces the information source for
228:ref:`krb5.conf(5)` itself.  To use a profile module, begin krb5.conf
229with the line::
230
231    module PATHNAME:STRING
232
233where *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
235take over, and the rest of krb5.conf will be ignored.
236