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 authenticator.h header unless otherwise mentioned.
Authenticator modules compatible with MySQL protocol in MaxScale are MySQL, GSSAPI and PAM.
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.
The MySQL protocol authentication starts when the server sends the handshake packet to the client to which the client responds with a handshake response packet. If the server is using the default mysql_native_password authentication plugin, the server responds with either an OK packet or an ERR packet 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. This is where the pluggable authentication in MaxScale starts.
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 MXS_AUTH_SUCCEEDED, the authenticate
entry point
will be called.
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.
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
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.