d87d462c76
Corrected the documentation and provided more details on how to configure the authenticator.
83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
## Preparing the GSSAPI system
|
|
|
|
For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short
|
|
guide on how to set up Kerberos for MaxScale.
|
|
|
|
The first step is to configure MariaDB to use GSSAPI authentication. The MariaDB
|
|
documentation for the
|
|
[GSSAPI Authentication Plugin](https://mariadb.com/kb/en/mariadb/gssapi-authentication-plugin/)
|
|
is a good example on how to set it up.
|
|
|
|
The next step is to copy the keytab file from the server where MariaDB is
|
|
installed to the server where MaxScale is located. The keytab file must be
|
|
placed in the configured default location which almost always is
|
|
`/etc/krb5.keytab`.
|
|
|
|
To take GSSAPI authentication into use, add the following to the listener.
|
|
|
|
```
|
|
authenticator=GSSAPIAuth
|
|
authenticator_options=principal_name=mariadb/localhost.localdomain@EXAMPLE.COM
|
|
```
|
|
|
|
Change the principal name to the same value you configured for the MariaDB
|
|
server.
|
|
|
|
After the listeners are configured, add the following to all servers that use GSSAPI users.
|
|
|
|
```
|
|
authenticator=GSSAPIBackendAuth
|
|
```
|
|
|
|
## 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_.
|
|
|
|
This parameter *must* be the same as the principal name that the backend MariaDB
|
|
server uses.
|
|
|
|
## 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.
|
|
|
|
## Building the module
|
|
|
|
The GSSAPI authenticator modules require the GSSAPI and the SQLite3 development
|
|
libraries (krb5-devel and sqlite-devel on CentOS 7).
|