MXS-862: Add authenticator documentation

The authentication process in MaxScale is now described in
Authentication-Modules.md. The GSSAPI authenticator also has its own
document.

Documentation/About/Limitations.md

@@ -32,6 +32,14 @@ Issues [MXS-710](https://jira.mariadb.org/browse/MXS-710) and
 
 Compression is not included in MySQL server handshake
 
+# Authenticator limitations
+
+## Limitations in the GSSAPI authentication
+
+Currently MaxScale only supports GSSAPI authentication when the backend
+connections use GSSAPI authentication. Client side GSSAPI authentication with a
+different backend authentication module is not supported.
+
 # Monitor limitations
 
 A server can only be monitored by one monitor. If multiple monitors monitor the

Documentation/Authenticators/Authentication-Modules.md

@@ -0,0 +1,106 @@
+# Authentication Modules in MaxScale
+
+This document describes the modular authentication in MaxScale. It contains
+protocol specific information on authentication and how it is handled in
+MaxScale.
+
+The constants described in this document are defined in the gw_authenticator.h
+header unless otherwise mentioned.
+
+## Authenticator initialization
+
+When the authentication module is first loaded, the `initialize` entry point is
+called. The return value of this function will be passed as the first argument
+to the other entry points.
+
+The `loadUsers` entry point of the client side authenticator is called when a
+service starts. The authenticator can load external user data when this entry
+point is called. This entry point is also called when user authentication has
+failed and the external user data needs to be refreshed.
+
+When a connection is created, the `create` entry point is called to create per
+connection data. The return value of this function is stored in the
+`dcb->authenticator_data` field of the DCB object. This data is freed in the
+`destroy` entry point and the value returned by `create` will be given as the
+first parameter.
+
+# MySQL Authentication Moduels
+
+The MySQL protocol authentication starts when the server sends the
+[handshake packet](https://dev.mysql.com/doc/internals/en/connection-phase-packets.html#packet-Protocol::Handshake)
+to the client to which the client responds with a [handshake response packet](https://dev.mysql.com/doc/internals/en/connection-phase-packets.html#packet-Protocol::HandshakeResponse).
+If the server is using the default _mysql_native_password_ authentication plugin, the server responds with either an
+[OK packet](https://dev.mysql.com/doc/internals/en/packet-OK_Packet.html) or an
+[ERR packet](https://dev.mysql.com/doc/internals/en/packet-ERR_Packet.html) and
+the authentication is complete.
+
+If a different authentication plugin is required to complete the authentication, instead of
+sending an OK or ERR packet, the server responds with an
+[AuthSwitchRequest packet](https://dev.mysql.com/doc/internals/en/connection-phase-packets.html#packet-Protocol::AuthSwitchRequest).
+This is where the pluggable authentication in MaxScale starts.
+
+## Client authentication in MaxScale
+
+The first packet the client side authenticator plugins will receive is the
+client's handshake response packet.
+
+The client protocol module will call the `extract` entry point of the
+authenticator where the authenticator should extract client information. If the
+`extract` entry point returns one of the following constants, the `authenticate`
+entry point will be called.
+
+- MXS_AUTH_SUCCEEDED
+- MXS_AUTH_INCOMPLETE
+- MXS_AUTH_SSL_INCOMPLETE
+
+The `authenticate` entry point is where the authenticator plugin should
+authenticate the client. If authentication is successful, the `authenticate`
+entry point should return MXS_AUTH_SUCCEEDED. If authentication is not yet
+complete or if the authentication module should be changed, the `authenticate`
+entry point should return MXS_AUTH_INCOMPLETE.
+
+Authenticator plugins which do not use the default _mysql_native_password_
+authentication plugin should send an AuthSwitchRequest packet to the client and
+return MXS_AUTH_INCOMPLETE. When more data is available, the `extract` and
+`authenticate` entry points will be called again.
+
+If either of the aforementioned entry points returns one of the following
+constants, the authentication is considered to have failed and the session will
+be closed.
+
+- MXS_AUTH_FAILED
+- MXS_AUTH_FAILED_DB
+- MXS_AUTH_FAILED_SSL
+
+Read the individual authenticator module documentation for more details on the
+authentication process of each authentication plugin.
+
+## Backend authentication in MaxScale
+
+The first packet the authentication plugins in MaxScale will receive is either
+the AuthSwitchRequest packet or, in case of _mysql_native_password_, the OK
+packet. At this point, the protocol plugin will call the `extract` entry point
+of the backend authenticator. If the return value of the call is one of the
+following constants, the protocol plugin will call the `authenticate` entry
+point of the authenticator.
+
+- MXS_AUTH_SUCCEEDED
+- MXS_AUTH_INCOMPLETE
+- MXS_AUTH_SSL_INCOMPLETE
+
+If the `authenticate` entry point returns MXS_AUTH_SUCCEEDED, then
+authentication is complete and any queued queries from the clients will be sent
+to the backend server. If the return value is MXS_AUTH_INCOMPLETE or
+MXS_AUTH_SSL_INCOMPLETE, the protocol module will continue the authentication by
+calling the `extract` entry point once more data is available.
+
+If either of the aforementioned entry points returns one of the following
+constants, the authentication is considered to have failed and the session will
+be closed.
+
+- MXS_AUTH_FAILED
+- MXS_AUTH_FAILED_DB
+- MXS_AUTH_FAILED_SSL
+
+Read the individual authenticator module documentation for more details on the
+authentication process of each authentication plugin.

Documentation/Authenticators/GSSAPI-Authenticator.md

@@ -0,0 +1,48 @@
+# GSSAPI Client Authenticator
+
+GSSAPI is an authentication protocol that is commonly implemented with
+Kerberos on Unix or Active Directory on Windows. This document describes
+the GSSAPI authentication in MaxScale.
+
+The _GSSAPIAuth_ module implements the client side authentication and the
+_GSSAPIBackendAuth_ module implements the backend authentication.
+
+## Authenticator options
+
+The client side GSSAPIAuth authenticator supports one option, the service
+principal name that MaxScale sends to the client. The backend authenticator
+module has no options.
+
+### `principal_name`
+
+The service principal name to send to the client. This parameter is a
+string parameter which is used by the client to request the token.
+
+The default value for this option is _mariadb/localhost.localdomain_.
+
+The parameter must be a valid GSSAPI principal name
+e.g. `styx/pluto@EXAMPLE.COM`. The principal name can also be defined
+without the realm part in which case the default realm will be used.
+
+## Implementation details
+
+Read the [Authentication Modules](Authentication-Modules.md) document for more
+details on how authentication modules work in MaxScale.
+
+### GSSAPI authentication
+
+The GSSAPI plugin authentication starts when the database server sends the
+service principal name in the AuthSwitchRequest packet. The principal name will
+usually be in the form `service@REALM.COM`.
+
+The client will then request a token for this service from the GSSAPI server and
+send the token to the database server. The database server will verify the
+authenticity of the token by contacting the GSSAPI server and if the token is
+authentic, the server sends the final OK packet.
+
+## Limitations
+
+Client side GSSAPI authentication is only supported when the backend
+connections use GSSAPI authentication.
+
+See the [Limitations](../About/Limitations.md) document for more details.

Documentation/Getting-Started/Configuration-Guide.md

@@ -435,6 +435,12 @@ router_options=master,slave
 
 A more complete description of router options and what is available for a given router is included with the documentation of the router itself.
 
+#### `router_options`
+
+Option string given to the router module. The value of this parameter
+should be a comma-separated list of key-value pairs. See router specific
+documentation for more details.
+
 #### `filters`
 
 The filters option allow a set of filters to be defined for a service; requests from the client are passed through these filters before being sent to the router for dispatch to the backend server.  The filters parameter takes one or more filter names, as defined within the filter definition section of the configuration file. Multiple filters are separated using the | character.
@@ -833,6 +839,18 @@ The `socket` option may be included in a listener definition, this configures th
 
 If a socket option and an address option is given then the listener will listen on both the specific IP address and the Unix socket.
 
+#### `authenticator`
+
+The authenticator module to use. Each protocol module defines a default
+authentication module which is used if no `authenticator` parameter is
+found from the configuration.
+
+#### `authenticator_options`
+
+Option string given to the authenticator module. The value of this
+parameter should be a comma-separated list of key-value pairs. See
+authenticator specific documentation for more details.
+
 #### Available Protocols
 
 The protocols supported by MariaDB MaxScale are implemented as external modules that are loaded dynamically into the MariaDB MaxScale core. They allow MariaDB MaxScale to communicate in various protocols both on the client side and the backend side. Each of the protocols can be either a client protocol or a backend protocol. Client protocols are used for client-MariaDB MaxScale communication and backend protocols are for MariaDB MaxScale-database communication.