1.. _otp_preauth:
2
3OTP Preauthentication
4=====================
5
6OTP is a preauthentication mechanism for Kerberos 5 which uses One
7Time Passwords (OTP) to authenticate the client to the KDC.  The OTP
8is passed to the KDC over an encrypted FAST channel in clear-text.
9The KDC uses the password along with per-user configuration to proxy
10the request to a third-party RADIUS system.  This enables
11out-of-the-box compatibility with a large number of already widely
12deployed proprietary systems.
13
14Additionally, our implementation of the OTP system allows for the
15passing of RADIUS requests over a UNIX domain stream socket.  This
16permits the use of a local companion daemon which can handle the
17details of authentication.
18
19
20Defining token types
21--------------------
22
23Token types are defined in either :ref:`krb5.conf(5)` or
24:ref:`kdc.conf(5)` according to the following format::
25
26    [otp]
27        <name> = {
28            server = <host:port or filename> (default: see below)
29            secret = <filename>
30            timeout = <integer> (default: 5 [seconds])
31            retries = <integer> (default: 3)
32            strip_realm = <boolean> (default: true)
33            indicator = <string> (default: none)
34        }
35
36If the server field begins with '/', it will be interpreted as a UNIX
37socket.  Otherwise, it is assumed to be in the format host:port.  When
38a UNIX domain socket is specified, the secret field is optional and an
39empty secret is used by default.  If the server field is not
40specified, it defaults to |kdcrundir|\ ``/<name>.socket``.
41
42When forwarding the request over RADIUS, by default the principal is
43used in the User-Name attribute of the RADIUS packet.  The strip_realm
44parameter controls whether the principal is forwarded with or without
45the realm portion.
46
47If an indicator field is present, tickets issued using this token type
48will be annotated with the specified authentication indicator (see
49:ref:`auth_indicator`).  This key may be specified multiple times to
50add multiple indicators.
51
52
53The default token type
54----------------------
55
56A default token type is used internally when no token type is specified for a
57given user.  It is defined as follows::
58
59    [otp]
60        DEFAULT = {
61            strip_realm = false
62        }
63
64The administrator may override the internal ``DEFAULT`` token type
65simply by defining a configuration with the same name.
66
67
68Token instance configuration
69----------------------------
70
71To enable OTP for a client principal, the administrator must define
72the **otp** string attribute for that principal.  (See
73:ref:`set_string`.)  The **otp** user string is a JSON string of the
74format:
75
76.. code-block:: xml
77
78    [{
79        "type": <string>,
80        "username": <string>,
81        "indicators": [<string>, ...]
82     }, ...]
83
84This is an array of token objects.  Both fields of token objects are
85optional.  The **type** field names the token type of this token; if
86not specified, it defaults to ``DEFAULT``.  The **username** field
87specifies the value to be sent in the User-Name RADIUS attribute.  If
88not specified, the principal name is sent, with or without realm as
89defined in the token type.  The **indicators** field specifies a list
90of authentication indicators to annotate tickets with, overriding any
91indicators specified in the token type.
92
93For ease of configuration, an empty array (``[]``) is treated as
94equivalent to one DEFAULT token (``[{}]``).
95
96
97Other considerations
98--------------------
99
100#. FAST is required for OTP to work.
101