Skip to content

Commit 7df2f35

Browse files
patrickbirchpatrickbirch
authored
Merge pull request #444 from percona/ps-9629
PS-9629 [DOCS] - Review Simple LDAP documentation variables 8.0
2 parents 92c3470 + 7e845cd commit 7df2f35

4 files changed

+391
-377
lines changed

‎docs/ldap-authentication.md

+120-128
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,6 @@ individuals, groups, and organizations.
88

99
*Percona Server for MySQL* 8.0.30-22 implements an SASL-based LDAP authentication plugin. This plugin only supports the SCRAM-SHA-1 SASL mechanism.
1010

11-
!!! important
12-
13-
--8<--- "tech.preview.md:5:5"
14-
1511
*Percona Server for MySQL* 8.0.19-10 implements the simple LDAP authentication. The Percona simple LDAP authentication plugin is a free and Open Source implementation of the MySQL Enterprise Simple LDAP authentication plugin.
1612

1713
## Plugin names and file names
@@ -114,12 +110,6 @@ Install the plugin with the following statements.
114110
mysql> INSTALL PLUGIN authentication_ldap_simple SONAME 'authentication_ldap_simple.so';
115111
```
116112

117-
To set and persist values at runtime, use the following statements:
118-
119-
```{.bash data-prompt="mysql>"}
120-
mysql> SET PERSIST authentication_ldap_simple_server_host='127.0.0.1';
121-
mysql> SET PERSIST authentication_ldap_simple_bind_base_dn='dc=percona, dc=com';
122-
```
123113

124114
=== "Load the SASL-based LDAP authentication plugin"
125115

@@ -134,130 +124,134 @@ Install the plugin with the following statements.
134124
mysql> SET PERSIST authentication_ldap_sasl_bind_base_dn='dc=percona, dc=com';
135125
```
136126

137-
## Create a user using simple LDAP authentication
127+
## Create a user
138128

139129
There are several methods to add or modify a user.
140130

141-
=== "Use authentication_ldap_simple plugin"
142-
143-
In the `CREATE USER` statement or the `ALTER USER` statement, for simple LDAP authentication, you can specify the `authentication_ldap_simple` plugin in the `IDENTIFIED WITH` clause:
131+
=== "Using LDAP Simple authentication"
144132

145-
```text
146-
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple;
147-
```
148-
149-
Using the `IDENTIFIED WITH` clause, the database server assigns the specified plugin.
150-
151-
=== "Use the authentication string in simple LDAP"
152-
153-
If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.
154-
155-
```text
156-
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
157-
```
158-
159-
Unless the [authentication_ldap_simple_group_role_mapping](ldap-system-variables.md#authentication_ldap_simple_group_role_mapping) variable is used, creating a user with an authentication string does not use the following system variables:
160-
161-
* [authentication_ldap_simple_bind_base_dn](ldap-system-variables.md#authentication_ldap_simple_bind_base_dn)
162-
163-
* [authentication_ldap_simple_bind_root_dn](ldap-system-variables.md#authentication_ldap_simple_bind_root_dn)
164-
165-
* [authentication_ldap_simple_bind_root_pwd](ldap-system-variables.md#authentication_ldap_simple_bind_root_pwd)
166-
167-
* [authentication_ldap_simple_user_search_attr](ldap-system-variables.md#authentication_ldap_simple_user_search_attr)
168-
169-
* [authentication_ldap_simple_group_search_attr](ldap-system-variables.md#authentication_ldap_simple_group_search_attr)
170-
171-
Creating the user with `IDENTIFIED BY authentication_ldap_simple` uses the variables.
133+
There are several methods to add or modify a user.
134+
135+
=== "Use authentication_ldap_simple plugin"
136+
137+
In the `CREATE USER` statement or the `ALTER USER` statement, for simple LDAP authentication, you can specify the `authentication_ldap_simple` plugin in the `IDENTIFIED WITH` clause:
138+
139+
```text
140+
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple;
141+
```
142+
143+
Using the `IDENTIFIED WITH` clause, the database server assigns the specified plugin.
144+
145+
=== "Use the authentication string in simple LDAP"
146+
147+
If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.
148+
149+
```text
150+
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_simple BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
151+
```
152+
153+
Unless the [authentication_ldap_simple_group_role_mapping](ldap-simple-variables.md#authentication_ldap_simple_group_role_mapping) variable is used, creating a user with an authentication string does not use the following system variables:
154+
155+
* [authentication_ldap_simple_bind_base_dn](ldap-simple-variables.md#authentication_ldap_simple_bind_base_dn)
156+
157+
* [authentication_ldap_simple_bind_root_dn](ldap-simple-variables.md#authentication_ldap_simple_bind_root_dn)
158+
159+
* [authentication_ldap_simple_bind_root_pwd](ldap-simple-variables.md#authentication_ldap_simple_bind_root_pwd)
160+
161+
* [authentication_ldap_simple_user_search_attr](ldap-simple-variables.md#authentication_ldap_simple_user_search_attr)
162+
163+
* [authentication_ldap_simple_group_search_attr](ldap-simple-variables.md#authentication_ldap_simple_group_search_attr)
164+
165+
Creating the user with `IDENTIFIED BY authentication_ldap_simple` uses the variables.
166+
167+
Creating the user with the [authentication_ldap_simple_group_role_mapping](ldap-simple-variables.md#authentication_ldap_simple_group_role_mapping) variable also adds the [authentication_ldap_simple_bind_root_dn](ldap-simple-variables.md#authentication_ldap_simple_bind_root_dn) and [authentication_ldap_simple_bind_root_pwd](ldap-simple-variables.md#authentication_ldap_simple_bind_root_pwd) variables.
168+
169+
=== "Using SASL-based LDAP authentication"
170+
171+
There are several methods to add or modify a user.
172+
173+
=== "Use authentication_ldap_sasl plugin"
174+
175+
For SASL-based LDAP authentication, in the `CREATE USER` statement or the `ALTER USER` statement, you can specify the `authentication_ldap_sasl` plugin:
176+
177+
```text
178+
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl;
179+
```
180+
181+
=== "Use the authentication string in SASL-based LDAP"
182+
183+
If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.
184+
185+
```text
186+
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
187+
```
188+
189+
Unless the [authentication_ldap_sasl_group_role_mapping](ldap-sasl-variables.md#authentication_ldap_sasl_group_role_mapping) variable is used, creating a user with an authentication string does not use the following system variables:
190+
191+
* [authentication_ldap_sasl_bind_base_dn](ldap-sasl-variables.md#authentication_ldap_sasl_bind_base_dn)
192+
193+
* [authentication_ldap_sasl_bind_root_dn](ldap-sasl-variables.md#authentication_ldap_sasl_bind_root_dn)
194+
195+
* [authentication_ldap_sasl_bind_root_pwd](ldap-sasl-variables.md#authentication_ldap_sasl_bind_root_pwd)
196+
197+
* [authentication_ldap_sasl_user_search_attr](ldap-sasl-variables.md#authentication_ldap_sasl_user_search_attr)
198+
199+
* [authentication_ldap_sasl_group_search_attr](ldap-sasl-variables.md#authentication_ldap_sasl_group_search_attr)
200+
201+
Creating the user with `IDENTIFIED BY authentication_ldap_sasl` uses the variables.
202+
203+
Creating the user with the [authentication_ldap_sasl_group_role_mapping](ldap-sasl-variables.md#authentication_ldap_sasl_group_role_mapping) variable also adds the[authentication_ldap_sasl_bind_root_dn](ldap-sasl-variables.md#authentication_ldap_sasl_bind_root_dn) and [authentication_ldap_sasl_bind_root_pwd](ldap-sasl-variables.md#authentication_ldap_sasl_bind_root_pwd) variables.
204+
205+
## Examples
206+
207+
The following sections are examples of using simple LDAP authentication and SASL-based LDAP authentication.
208+
209+
For the purposes of this example, we use the following LDAP user:
172210

173-
Creating the user with the [authentication_ldap_simple_group_role_mapping](ldap-system-variables.md#authentication_ldap_simple_group_role_mapping) variable also adds the [authentication_ldap_simple_bind_root_dn](ldap-system-variables.md#authentication_ldap_simple_bind_root_dn) and [authentication_ldap_simple_bind_root_pwd](ldap-system-variables.md#authentication_ldap_simple_bind_root_pwd) variables.
174-
175-
## Create a user using SASL-based LDAP authentication
176-
177-
There are several methods to add or modify a user.
178-
179-
=== "Use authentication_ldap_sasl plugin"
180-
181-
For SASL-based LDAP authentication, in the `CREATE USER` statement or the `ALTER USER` statement, you can specify the `authentication_ldap_sasl` plugin:
182-
183-
```text
184-
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl;
185-
```
186-
187-
=== "Use the authentication string in SASL-based LDAP"
188-
189-
If you provide the optional authentication string clause, ‘cn,ou,dc,dc’ in the example, the string is stored along with the password.
190-
191211
```text
192-
mysql> CREATE USER ... IDENTIFIED WITH authentication_ldap_sasl BY 'cn=[user name],ou=[organization unit],dc=[domain component],dc=com'
212+
uid=ldapuser,ou=testusers,dc=percona,dc=com
193213
```
194-
195-
Unless the [authentication_ldap_sasl_group_role_mapping](ldap-system-variables.md#authentication_ldap_sasl_group_role_mapping) variable is used, creating a user with an authentication string does not use the following system variables:
196-
197-
* [authentication_ldap_sasl_bind_base_dn](ldap-system-variables.md#authentication_ldap_sasl_bind_base_dn)
198-
199-
* [authentication_ldap_sasl_bind_root_dn](ldap-system-variables.md#authentication_ldap_sasl_bind_root_dn)
200-
201-
* [authentication_ldap_sasl_bind_root_pwd](ldap-system-variables.md#authentication_ldap_sasl_bind_root_pwd)
202-
203-
* [authentication_ldap_sasl_user_search_attr](ldap-system-variables.md#authentication_ldap_sasl_user_search_attr)
204-
205-
* [authentication_ldap_sasl_group_search_attr](ldap-system-variables.md#authentication_ldap_sasl_group_search_attr)
206-
207-
Creating the user with `IDENTIFIED BY authentication_ldap_sasl` uses the variables.
208214

209-
Creating the user with the [authentication_ldap_sasl_group_role_mapping](ldap-system-variables.md#authentication_ldap_sasl_group_role_mapping) variable also adds the[authentication_ldap_sasl_bind_root_dn](ldap-system-variables.md#authentication_ldap_sasl_bind_root_dn) and [authentication_ldap_sasl_bind_root_pwd](ldap-system-variables.md#authentication_ldap_sasl_bind_root_pwd) variables.
210-
211-
## Examples
212-
213-
The following sections are examples of using simple LDAP authentication and SASL-based LDAP authentication.
214-
215-
For the purposes of this example, we use the following LDAP user:
216-
217-
```text
218-
uid=ldapuser,ou=testusers,dc=percona,dc=com
219-
```
220-
221-
=== "Simple LDAP authentication"
222-
223-
The following example configures an LDAP user and connects to the database server.
224-
225-
Create a database server account for `ldapuser` with the following statement:
226-
227-
```{.bash data-prompt="mysql>"}
228-
mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_simple BY 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
229-
```
230-
231-
The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.
232-
233-
```{.bash data-prompt="mysql>"}
234-
mysql> mysql --user=ldapuser --password --enable-cleartext-plugin
235-
```
236-
237-
The user enters the `ldapuser` password. The client sends the password as cleartext, which is necessary when using a server-side LDAP library without SASL. The following actions may minimize the risk:
238-
239-
* Require that the database server clients explicitly enable the `mysql_clear_password` plugin with `--enable-cleartext-plugin`.
240-
* Require that the database server clients connect to the database server using an encrypted connection
241-
242-
=== "SASL-based LDAP authentication"
243-
244-
The following example configures an LDAP user and connect to the database server.
245-
246-
Create a database server account for `ldapuser` with the following statement:
247-
248-
```{.bash data-prompt="mysql>"}
249-
mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_sasl AS 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
250-
```
251-
252-
The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.
253-
254-
Clients connect ot the database server by providing the database server user name and LDAP password:
255-
256-
```{.bash data-prompt="mysql>"}
257-
mysql> mysql --user=ldapuser --password
258-
```
259-
260-
The authentication is similar to the authentication method used by simple LDAP authentication, except that the client and the database server SASL LDAP plugins use SASL messages. These messages are secure within the LDAP protocol.
215+
=== "Simple LDAP authentication"
216+
217+
The following example configures an LDAP user and connects to the database server.
218+
219+
Create a database server account for `ldapuser` with the following statement:
220+
221+
```{.bash data-prompt="mysql>"}
222+
mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_simple BY 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
223+
```
224+
225+
The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.
226+
227+
```{.bash data-prompt="mysql>"}
228+
mysql> mysql --user=ldapuser --password --enable-cleartext-plugin
229+
```
230+
231+
The user enters the `ldapuser` password. The client sends the password as cleartext, which is necessary when using a server-side LDAP library without SASL. The following actions may minimize the risk:
232+
233+
* Require that the database server clients explicitly enable the `mysql_clear_password` plugin with `--enable-cleartext-plugin`.
234+
* Require that the database server clients connect to the database server using an encrypted connection
235+
236+
=== "SASL-based LDAP authentication"
237+
238+
The following example configures an LDAP user and connect to the database server.
239+
240+
Create a database server account for `ldapuser` with the following statement:
241+
242+
```{.bash data-prompt="mysql>"}
243+
mysql> CREATE USER 'ldapuser'@'localhost' IDENTIFIED WITH authentication_ldap_sasl AS 'uid=ldapuser,ou=testusers,dc=percona,dc=com';
244+
```
245+
246+
The authentication string does not include the LDAP password. This password must be provided by the client user when they connect.
247+
248+
Clients connect ot the database server by providing the database server user name and LDAP password:
249+
250+
```{.bash data-prompt="mysql>"}
251+
mysql> mysql --user=ldapuser --password
252+
```
253+
254+
The authentication is similar to the authentication method used by simple LDAP authentication, except that the client and the database server SASL LDAP plugins use SASL messages. These messages are secure within the LDAP protocol.
261255

262256
### Uninstall the plugins
263257

@@ -271,8 +265,6 @@ If you installed either plugin at [server startup](#load-the-plugins-at-server-s
271265
mysql> UNINSTALL PLUGIN authentication_ldap_simple;
272266
```
273267

274-
If you used `SET_PERSIST`, use `RESET PERSIST` to remove the settings.
275-
276268
=== "Uninstall the SASL-based LDAP authentication plugin"
277269

278270
If you installed the plugins at [runtime](#load-the-sasl-based-ldap-authentication-plugin-at-runtime), run the following statements:

0 commit comments

Comments
 (0)