From 2708a4d7ac97d5b0cd7c1a53529dcff13dd0ad5f Mon Sep 17 00:00:00 2001 From: Esa Korhonen Date: Fri, 4 Aug 2017 18:45:03 +0300 Subject: [PATCH] Add PAM authenticator documentation Also fixed some small errors in general authenticator documentation. --- .../Authenticators/Authentication-Modules.md | 35 ++++---- .../Authenticators/PAM-Authenticator.md | 84 +++++++++++++++++++ 2 files changed, 100 insertions(+), 19 deletions(-) create mode 100644 Documentation/Authenticators/PAM-Authenticator.md diff --git a/Documentation/Authenticators/Authentication-Modules.md b/Documentation/Authenticators/Authentication-Modules.md index 96f233c7c..6a3795fb9 100644 --- a/Documentation/Authenticators/Authentication-Modules.md +++ b/Documentation/Authenticators/Authentication-Modules.md @@ -7,6 +7,10 @@ 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](MySQL-Authenticator.md), [GSSAPI](GSSAPI-Authenticator.md) and +[PAM](PAM-Authenticator.md). + ## Authenticator initialization When the authentication module is first loaded, the `initialize` entry point is @@ -26,18 +30,16 @@ first parameter. # MySQL Authentication Modules -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. +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](https://dev.mysql.com/doc/internals/en/connection-phase-packets.html#packet-Protocol::AuthSwitchRequest). -This is where the pluggable authentication in MaxScale starts. +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. ## Client authentication in MaxScale @@ -46,12 +48,8 @@ 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 +`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` @@ -59,7 +57,7 @@ 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_ +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. @@ -86,7 +84,6 @@ 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 diff --git a/Documentation/Authenticators/PAM-Authenticator.md b/Documentation/Authenticators/PAM-Authenticator.md new file mode 100644 index 000000000..2096e8f72 --- /dev/null +++ b/Documentation/Authenticators/PAM-Authenticator.md @@ -0,0 +1,84 @@ +# PAM Authenticator + +Pluggable authentication module (PAM) is a general purpose authentication API. +An application using PAM can authenticate a user without knowledge about the +underlying authentication implementation. The actual authentication scheme is +defined in the operating system PAM config (e.g. `/etc/pam.d/`), and can be +quite elaborate. MaxScale supports a very limited form of the PAM protocol, +which this document details. + +## Configuration + +The MaxScale PAM modules themselves have no configuration. All that is required +is to change the listener and backend authenticator modules to `PAMAuth` and +`PAMBackendAuth`, respectively. + +``` +[Read-Write-Listener] +type=listener +address=:: +service=Read-Write-Service +protocol=MySQLClient +authenticator=PAMAuth + +[Master-Server] +type=server +address=123.456.789.10 +port=12345 +protocol=MySQLBackend +authenticator=PAMBackendAuth +``` + +The client PAM authenticator will fetch user entries with `plugin='pam'` from +the `mysql.user` table. The entries should also have a PAM service name set in +the `authetication_string` column. The matching PAM service in the operating +system PAM config will be used for authenticating a user. If the +`authetication_string` for an entry is empty, a fallback service (e.g. `other`) +is used. If a username@host has multiple matching entries, they will all be +attempted until authentication succeeds or all fail. + +PAM service configuration is out of the scope of this document, see +[The Linux-PAM System Administrators' Guide +](http://www.linux-pam.org/Linux-PAM-html/Linux-PAM_SAG.html) for more +information. A simple service definition used for testing this module is below. + +``` +auth required pam_unix.so +account required pam_unix.so +``` + +## Implementation details and limitations + +The PAM general authentication scheme is difficult for a proxy such as MaxScale. +An application using the PAM interface needs to define a *conversation function* +to allow the OS PAM modules to communicate with the client, possibly exchanging +multiple messages. This works when a client logs in to a normal server, but not +with MaxScale since it needs to autonomously log into multiple backends. For +MaxScale to successfully log into the servers, the messages and answers need to +be predefined. This requirement denies the use of more exotic schemes such as +one-time passwords or two-factor authentication. + +The current version of the MaxScale PAM authentication module only supports a +simple password exchange. On the client side, the authentication begins with +MaxScale sending an AuthSwitchRequest packet. In addition to the command, the +packet contains the client plugin name `dialog`, a message type byte `4` and the +message `Password: `. In the next packet, the client should send the password, +which MaxScale will forward to the PAM API running on the local machine. If the +password is correct, an OK packet is sent to the client. No additional +PAM-related messaging is allowed, as this would indicate a more complicated +authentication scheme. + +On the backend side, MaxScale expects the servers to act as MaxScale did towards +the client. The servers should send an AuthSwitchRequest packet as defined +above, MaxScale responds with the password received by the client authenticator +and finally backend replies with OK. + +## SSL support + +PAM Authenticator supports SSL connections from client to MaxScale, but not from +MaxScale to backends. + +## Building the module + +The PAM authenticator modules require the PAM and SQLite3 development +libraries (libpam0g-dev and sqlite3-dev on Ubuntu).