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/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.