diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/admin/conf_files/kdc_conf.rst | 66 | ||||
| -rw-r--r-- | doc/admin/index.rst | 1 | ||||
| -rw-r--r-- | doc/admin/otp.rst | 85 |
3 files changed, 152 insertions, 0 deletions
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index c7007d647b..3b56e61e82 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -491,6 +491,72 @@ administrative server will be appended to the file admin_server = DEVICE=/dev/tty04 +.. _otp: + +[otp] +~~~~~ + +Each subsection of [otp] is the name of an OTP token type. The tags +within the subsection define the configuration required to forward a +One Time Password request to a RADIUS server. + +For each token type, the following tags may be specified: + +**server** + This is the server to send the RADIUS request to. It can be a + hostname with optional port, an ip address with optional port, or + a Unix domain socket address. The default is + |kdcdir|\ ``/<name>.socket``. + +**secret** + This tag indicates a filename (which may be relative to |kdcdir|) + containing the secret used to encrypt the RADIUS packets. The + secret should appear in the first line of the file by itself; + leading and trailing whitespace on the line will be removed. If + the value of **server** is a Unix domain socket address, this tag + is optional, and an empty secret will be used if it is not + specified. Otherwise, this tag is required. + +**timeout** + An integer which specifies the time in seconds during which the + KDC should attempt to contact the RADIUS server. This tag is the + total time across all retries and should be less than the time + which an OTP value remains valid for. The default is 5 seconds. + +**retries** + This tag specifies the number of retries to make to the RADIUS + server. The default is 3 retries (4 tries). + +**strip_realm** + If this tag is ``true``, the principal without the realm will be + passed to the RADIUS server. Otherwise, the realm will be + included. The default value is ``true``. + +In the following example, requests are sent to a remote server via UDP. + + :: + + [otp] + MyRemoteTokenType = { + server = radius.mydomain.com:1812 + secret = SEmfiajf42$ + timeout = 15 + retries = 5 + strip_realm = true + } + +An implicit default token type named ``DEFAULT`` is defined for when +the per-principal configuration does not specify a token type. Its +configuration is shown below. You may override this token type to +something applicable for your situation. + + :: + + [otp] + DEFAULT = { + strip_realm = false + } + PKINIT options -------------- diff --git a/doc/admin/index.rst b/doc/admin/index.rst index c40d51016c..3406843b10 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -14,6 +14,7 @@ For administrators host_config.rst backup_host.rst pkinit.rst + otp.rst princ_dns.rst enctypes.rst diff --git a/doc/admin/otp.rst b/doc/admin/otp.rst new file mode 100644 index 0000000000..0abd5ff837 --- /dev/null +++ b/doc/admin/otp.rst @@ -0,0 +1,85 @@ +OTP Preauthentication +===================== + +OTP is a preauthentication mechanism for Kerberos 5 which uses One +Time Passwords (OTP) to authenticate the client to the KDC. The OTP +is passed to the KDC over an encrypted FAST channel in clear-text. +The KDC uses the password along with per-user configuration to proxy +the request to a third-party RADIUS system. This enables +out-of-the-box compatibility with a large number of already widely +deployed proprietary systems. + +Additionally, our implementation of the OTP system allows for the +passing of RADIUS requests over a UNIX domain stream socket. This +permits the use of a local companion daemon which can handle the +details of authentication. + + +Defining token types +-------------------- + +Token types are defined in either krb5.conf or kdc.conf according to +the following format:: + + [otp] + <name> = { + server = <host:port or filename> (default: $KDCDIR/<name>.socket) + secret = <filename> + timeout = <integer> (default: 5 [seconds]) + retries = <integer> (default: 3) + strip_realm = <boolean> (default: true) + } + +If the server field begins with '/', it will be interpreted as a UNIX +socket. Otherwise, it is assumed to be in the format host:port. When +a UNIX domain socket is specified, the secret field is optional and an +empty secret is used by default. + +When forwarding the request over RADIUS, by default the principal is +used in the User-Name attribute of the RADIUS packet. The strip_realm +parameter controls whether the principal is forwarded with or without +the realm portion. + + +The default token type +---------------------- + +A default token type is used internally when no token type is specified for a +given user. It is defined as follows:: + + [otp] + DEFAULT = { + strip_realm = false + } + +The administrator may override the internal ``DEFAULT`` token type +simply by defining a configuration with the same name. + + +Token instance configuration +---------------------------- + +To enable OTP for a client principal, the administrator must define +the **otp** string attribute for that principal. The **otp** user +string is a JSON string of the format:: + + [{ + "type": <string>, + "username": <string> + }, ...] + +This is an array of token objects. Both fields of token objects are +optional. The **type** field names the token type of this token; if +not specified, it defaults to ``DEFAULT``. The **username** field +specifies the value to be sent in the User-Name RADIUS attribute. If +not specified, the principal name is sent, with or without realm as +defined in the token type. + +For ease of configuration, an empty array (``[]``) is treated as +equivalent to one DEFAULT token (``[{}]``). + + +Other considerations +-------------------- + +#. FAST is required for OTP to work. |