doc/html/_sources/admin/otp.txt

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