hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add PAM authenticator documentation

Browse Source 
Also fixed some small errors in general authenticator documentation.
This commit is contained in:
Esa Korhonen
2017-08-04 18:45:03 +03:00
parent ed05d24a9a
commit 2708a4d7ac
2 changed files with 100 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
Documentation/Authenticators/Authentication-Modules.md
View File

@ -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

84
Documentation/Authenticators/PAM-Authenticator.md Normal file
View File

@ -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).