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

MXS-2049: Update GSSAPI documentation

Browse Source 
Corrected the documentation and provided more details on how to configure
the authenticator.
This commit is contained in:
Markus Mäkelä
2018-09-28 10:24:17 +03:00
parent f65c890287
commit d87d462c76
1 changed files with 22 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
Documentation/Authenticators/GSSAPI-Authenticator.md
View File

@ -12,29 +12,32 @@ _GSSAPIBackendAuth_ module implements the backend authentication.
For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short
guide on how to set up Kerberos for MaxScale. guide on how to set up Kerberos for MaxScale.
The first step is to create a new principal for MaxScale. This can be done with The first step is to configure MariaDB to use GSSAPI authentication. The MariaDB
the _kadmin_ or _kadmin.local_ tools. 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.
``` ```
kadmin.local -q "addprinc -nokey mariadb/example.com@EXAMPLE.COM" authenticator=GSSAPIAuth
authenticator_options=principal_name=mariadb/localhost.localdomain@EXAMPLE.COM
``` ```
The `-nokey` option will make the principal a passwordless one. This allows the Change the principal name to the same value you configured for the MariaDB
_maxscale_ user to acquire a ticket for it without a password being prompted. server.
The next step is to export this principal into the Kerberos keytab file. After the listeners are configured, add the following to all servers that use GSSAPI users.
``` ```
kadmin.local -q "ktadd -k /etc/krb5.keytab -norandkey mariadb/example.com@EXAMPLE.COM" authenticator=GSSAPIBackendAuth
``` ```
This adds the _mariadb/example.com@EXAMPLE.COM_ principal into the keytab
file. The `-norandkey` option tells that the password we defined earlier,
i.e. no password at all, should be used instead of a random password.
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 up a new principal for the MariaDB server.
## Authenticator options ## Authenticator options
The client side GSSAPIAuth authenticator supports one option, the service The client side GSSAPIAuth authenticator supports one option, the service
@ -43,14 +46,12 @@ module has no options.
### `principal_name` ### `principal_name`
The service principal name to send to the client. This parameter is a The service principal name to send to the client. This parameter is a string
string parameter which is used by the client to request the token. parameter which is used by the client to request the token. The default value
for this option is _mariadb/localhost.localdomain_.
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.
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 ## Implementation details