Table of Contents
When thinking about security within a MySQL installation, you should consider a wide range of possible topics and how they affect the security of your MySQL server and related applications:
General factors that affect security. These include choosing good passwords, not granting unnecessary privileges to users, ensuring application security by preventing SQL injections and data corruption, and others. See Section 6.1, “General Security Issues”.
Security of the installation itself. The data files, log files, and the all the application files of your installation should be protected to ensure that they are not readable or writable by unauthorized parties. For more information, see Section 2.10, “Postinstallation Setup and Testing”.
Access control and security within the database system itself, including the users and databases granted with access to the databases, views and stored programs in use within the database. For more information, see Section 6.2, “Access Control and Account Management”.
The features offered by security-related plugins. See Section 6.4, “Security Plugins”.
Network security of MySQL and your system. The security is related to the grants for individual users, but you may also wish to restrict MySQL so that it is available only locally on the MySQL server host, or to a limited set of other hosts.
Ensure that you have adequate and appropriate backups of your database files, configuration and log files. Also be sure that you have a recovery solution in place and test that you are able to successfully recover the information from your backups. See Chapter 7, Backup and Recovery.
This section describes general security issues to be aware of and what you can do to make your MySQL installation more secure against attack or misuse. For information specifically about the access control system that MySQL uses for setting up user accounts and checking database access, see Section 2.10, “Postinstallation Setup and Testing”.
For answers to some questions that are often asked about MySQL Server security issues, see Section A.9, “MySQL 5.7 FAQ: Security”.
Anyone using MySQL on a computer connected to the Internet should read this section to avoid the most common security mistakes.
In discussing security, it is necessary to consider fully protecting the entire server host (not just the MySQL server) against all types of applicable attacks: eavesdropping, altering, playback, and denial of service. We do not cover all aspects of availability and fault tolerance here.
MySQL uses security based on Access Control Lists (ACLs) for all connections, queries, and other operations that users can attempt to perform. There is also support for SSL-encrypted connections between MySQL clients and servers. Many of the concepts discussed here are not specific to MySQL at all; the same general ideas apply to almost all applications.
When running MySQL, follow these guidelines:
Do not ever give anyone (except MySQL
root
accounts) access to the
user
table in the mysql
system database! This is critical.
Learn how the MySQL access privilege system works (see
Section 6.2, “Access Control and Account Management”). Use the
GRANT
and
REVOKE
statements to control
access to MySQL. Do not grant more privileges than necessary.
Never grant privileges to all hosts.
Checklist:
Try mysql -u root
. If you are able to
connect successfully to the server without being asked for
a password, anyone can connect to your MySQL server as the
MySQL root
user with full privileges!
Review the MySQL installation instructions, paying
particular attention to the information about setting a
root
password. See
Section 2.10.4, “Securing the Initial MySQL Account”.
Use the SHOW GRANTS
statement to check which accounts have access to what.
Then use the REVOKE
statement to remove those privileges that are not
necessary.
Do not store cleartext passwords in your database. If your
computer becomes compromised, the intruder can take the full
list of passwords and use them. Instead, use
SHA2()
or some other one-way
hashing function and store the hash value.
To prevent password recovery using rainbow tables, do not use these functions on a plain password; instead, choose some string to be used as a salt, and use hash(hash(password)+salt) values.
Do not choose passwords from dictionaries. Special programs exist to break passwords. Even passwords like “xfish98” are very bad. Much better is “duag98” which contains the same word “fish” but typed one key to the left on a standard QWERTY keyboard. Another method is to use a password that is taken from the first characters of each word in a sentence (for example, “Four score and seven years ago” results in a password of “Fsasya”). The password is easy to remember and type, but difficult to guess for someone who does not know the sentence. In this case, you can additionally substitute digits for the number words to obtain the phrase “4 score and 7 years ago”, yielding the password “4sa7ya” which is even more difficult to guess.
Invest in a firewall. This protects you from at least 50% of all types of exploits in any software. Put MySQL behind the firewall or in a demilitarized zone (DMZ).
Checklist:
Try to scan your ports from the Internet using a tool such
as nmap
. MySQL uses port 3306 by
default. This port should not be accessible from untrusted
hosts. As a simple way to check whether your MySQL port is
open, try the following command from some remote machine,
where server_host
is the host
name or IP address of the host on which your MySQL server
runs:
shell> telnet server_host
3306
If telnet hangs or the connection is refused, the port is blocked, which is how you want it to be. If you get a connection and some garbage characters, the port is open, and should be closed on your firewall or router, unless you really have a good reason to keep it open.
Applications that access MySQL should not trust any data entered by users, and should be written using proper defensive programming techniques. See Section 6.1.7, “Client Programming Security Guidelines”.
Do not transmit plain (unencrypted) data over the Internet. This information is accessible to everyone who has the time and ability to intercept it and use it for their own purposes. Instead, use an encrypted protocol such as SSL or SSH. MySQL supports internal SSL connections. Another technique is to use SSH port-forwarding to create an encrypted (and compressed) tunnel for the communication.
Learn to use the tcpdump and strings utilities. In most cases, you can check whether MySQL data streams are unencrypted by issuing a command like the following:
shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings
This works under Linux and should work with small modifications under other systems.
If you do not see cleartext data, this does not always mean that the information actually is encrypted. If you need high security, consult with a security expert.
Passwords occur in several contexts within MySQL. The following sections provide guidelines that enable end users and administrators to keep these passwords secure and avoid exposing them. There is also a discussion of how MySQL uses password hashing internally and of a plugin that you can use to enforce stricter passwords.
MySQL users should use the following guidelines to keep passwords secure.
When you run a client program to connect to the MySQL server, it is inadvisable to specify your password in a way that exposes it to discovery by other users. The methods you can use to specify your password when you run client programs are listed here, along with an assessment of the risks of each method. In short, the safest methods are to have the client program prompt for the password or to specify the password in a properly protected option file.
Use the mysql_config_editor utility,
which enables you to store authentication credentials in an
encrypted login path file named
.mylogin.cnf
. The file can be read
later by MySQL client programs to obtain authentication
credentials for connecting to MySQL Server. See
Section 4.6.6, “mysql_config_editor — MySQL Configuration Utility”.
Use a
--password=
or password
-p
option on the command line. For example:
password
shell> mysql -u francis -pfrank db_name
This is convenient but insecure. On some systems, your password becomes visible to system status programs such as ps that may be invoked by other users to display command lines. MySQL clients typically overwrite the command-line password argument with zeros during their initialization sequence. However, there is still a brief interval during which the value is visible. Also, on some systems this overwriting strategy is ineffective and the password remains visible to ps. (SystemV Unix systems and perhaps others are subject to this problem.)
If your operating environment is set up to display your current command in the title bar of your terminal window, the password remains visible as long as the command is running, even if the command has scrolled out of view in the window content area.
Use the --password
or
-p
option on the command line with no
password value specified. In this case, the client program
solicits the password interactively:
shell> mysql -u francis -p db_name
Enter password: ********
The *
characters indicate where you enter
your password. The password is not displayed as you enter
it.
It is more secure to enter your password this way than to specify it on the command line because it is not visible to other users. However, this method of entering a password is suitable only for programs that you run interactively. If you want to invoke a client from a script that runs noninteractively, there is no opportunity to enter the password from the keyboard. On some systems, you may even find that the first line of your script is read and interpreted (incorrectly) as your password.
Store your password in an option file. For example, on Unix,
you can list your password in the
[client]
section of the
.my.cnf
file in your home directory:
[client]
password=password
To keep the password safe, the file should not be accessible
to anyone but yourself. To ensure this, set the file access
mode to 400
or 600
.
For example:
shell> chmod 600 .my.cnf
To name from the command line a specific option file
containing the password, use the
--defaults-file=
option, where file_name
file_name
is the full
path name to the file. For example:
shell> mysql --defaults-file=/home/francis/mysql-opts
Section 4.2.2.2, “Using Option Files”, discusses option files in more detail.
Store your password in the MYSQL_PWD
environment variable. See
Section 4.9, “Environment Variables”.
This method of specifying your MySQL password must be
considered extremely insecure and
should not be used. Some versions of ps
include an option to display the environment of running
processes. On some systems, if you set
MYSQL_PWD
, your password is exposed to
any other user who runs ps. Even on
systems without such a version of ps, it
is unwise to assume that there are no other methods by which
users can examine process environments.
On Unix, the mysql client writes a record of
executed statements to a history file (see
Section 4.5.1.3, “mysql Client Logging”). By default, this file is named
.mysql_history
and is created in your home
directory. Passwords can be written as plain text in SQL
statements such as CREATE USER
and ALTER USER
, so if you use
these statements, they are logged in the history file. To keep
this file safe, use a restrictive access mode, the same way as
described earlier for the .my.cnf
file.
If your command interpreter is configured to maintain a history,
any file in which the commands are saved will contain MySQL
passwords entered on the command line. For example,
bash uses
~/.bash_history
. Any such file should have
a restrictive access mode.
Database administrators should use the following guidelines to keep passwords secure.
MySQL stores passwords for user accounts in the
mysql.user
system table. Access to this table
should never be granted to any nonadministrative accounts.
Account passwords can be expired so that users must reset them. See Section 6.2.11, “Password Management”, and Section 6.2.12, “Server Handling of Expired Passwords”.
The validate_password
plugin can be used to
enforce a policy on acceptable password. See
Section 6.4.3, “The Password Validation Plugin”.
A user who has access to modify the plugin directory (the value
of the plugin_dir
system
variable) or the my.cnf
file that specifies
the plugin directory location can replace plugins and modify the
capabilities provided by plugins, including authentication
plugins.
Files such as log files to which passwords might be written should be protected. See Section 6.1.2.3, “Passwords and Logging”.
Passwords can be written as plain text in SQL statements such as
CREATE USER
,
GRANT
, SET
PASSWORD
, and statements that invoke the
PASSWORD()
function. If such
statements are logged by the MySQL server as written, passwords
in them become visible to anyone with access to the logs.
Statement logging avoids writing passwords as cleartext for the following statements:
CREATE USER ... IDENTIFIED BY ... ALTER USER ... IDENTIFIED BY ... GRANT ... IDENTIFIED BY ... SET PASSWORD ... SLAVE START ... PASSWORD = ... CREATE SERVER ... OPTIONS(... PASSWORD ...) ALTER SERVER ... OPTIONS(... PASSWORD ...)
Passwords in those statements are rewritten to not appear
literally in statement text written to the general query log,
slow query log, and binary log. Rewriting does not apply to
other statements. In particular,
INSERT
or
UPDATE
statements for the
mysql.user
system table that refer to literal
passwords are logged as is, so you should avoid such statements.
(Direct modification of grant tables is discouraged, anyway.)
For the general query log, password rewriting can be suppressed
by starting the server with the
--log-raw
option. For security
reasons, this option is not recommended for production use. For
diagnostic purposes, it may be useful to see the exact text of
statements as received by the server.
Contents of the audit log file produced by the audit log plugin are not encrypted. For security reasons, this file should be written to a directory accessible only to the MySQL server and users with a legitimate reason to view the log. See Section 6.4.5.3, “MySQL Enterprise Audit Security Considerations”.
Statements received by the server may be rewritten if a query
rewrite plugin is installed (see
Query Rewrite Plugins). In this case, the
--log-raw
option affects
statement logging as follows:
An implication of password rewriting is that statements that
cannot be parsed (due, for example, to syntax errors) are not
written to the general query log because they cannot be known to
be password free. Use cases that require logging of all
statements including those with errors should use the
--log-raw
option, bearing in mind
that this also bypasses password rewriting.
Password rewriting occurs only when plain text passwords are expected. For statements with syntax that expect a password hash value, no rewriting occurs. If a plain text password is supplied erroneously for such syntax, the password is logged as given, without rewriting. For example, the following statement is logged as shown because a password hash value is expected:
CREATE USER 'user1'@'localhost' IDENTIFIED BY PASSWORD 'not-so-secret';
To guard log files against unwarranted exposure, locate them in
a directory that restricts access to the server and the database
administrator. If the server logs to tables in the
mysql
database, grant access to those tables
only to the database administrator.
Replication slaves store the password for the replication master
in the master info repository, which can be either a file or a
table (see Section 16.2.4, “Replication Relay and Status Logs”). Ensure that the
repository can be accessed only by the database administrator.
An alternative to storing the password in a file is to use the
START SLAVE
statement to specify
credentials for connecting to the master.
Use a restricted access mode to protect database backups that include log tables or log files containing passwords.
The information in this section applies fully only before
MySQL 5.7.5, and only for accounts that use the
mysql_native_password
or
mysql_old_password
authentication plugins.
Support for pre-4.1 password hashes was removed in MySQL
5.7.5. This includes removal of the
mysql_old_password
authentication plugin
and the OLD_PASSWORD()
function. Also,
secure_auth
cannot be
disabled, and old_passwords
cannot be set to 1.
As of MySQL 5.7.5, only the information about 4.1 password
hashes and the mysql_native_password
authentication plugin remains relevant.
MySQL lists user accounts in the user
table
of the mysql
database. Each MySQL account can
be assigned a password, although the user
table does not store the cleartext version of the password, but
a hash value computed from it.
MySQL uses passwords in two phases of client/server communication:
When a client attempts to connect to the server, there is an
initial authentication step in which the client must present
a password that has a hash value matching the hash value
stored in the user
table for the account
the client wants to use.
After the client connects, it can (if it has sufficient
privileges) set or change the password hash for accounts
listed in the user
table. The client can
do this by using the
PASSWORD()
function to
generate a password hash, or by using a password-generating
statement (CREATE USER
,
GRANT
, or
SET PASSWORD
).
In other words, the server checks hash
values during authentication when a client first attempts to
connect. The server generates hash values
if a connected client invokes the
PASSWORD()
function or uses a
password-generating statement to set or change a password.
Password hashing methods in MySQL have the history described
following. These changes are illustrated by changes in the
result from the PASSWORD()
function that computes password hash values and in the structure
of the user
table where passwords are stored.
The original hashing method produced a 16-byte string. Such hashes look like this:
mysql> SELECT PASSWORD('mypass');
+--------------------+
| PASSWORD('mypass') |
+--------------------+
| 6f8c114b58f2ce9e |
+--------------------+
To store account passwords, the Password
column of the user
table was at this point 16
bytes long.
MySQL 4.1 introduced password hashing that provided better security and reduced the risk of passwords being intercepted. There were several aspects to this change:
Different format of password values produced by the
PASSWORD()
function
Widening of the Password
column
Control over the default hashing method
Control over the permitted hashing methods for clients attempting to connect to the server
The changes in MySQL 4.1 took place in two stages:
MySQL 4.1.0 used a preliminary version of the 4.1 hashing method. This method was short lived and the following discussion says nothing more about it.
In MySQL 4.1.1, the hashing method was modified to produce a longer 41-byte hash value:
mysql> SELECT PASSWORD('mypass');
+-------------------------------------------+
| PASSWORD('mypass') |
+-------------------------------------------+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+-------------------------------------------+
The longer password hash format has better cryptographic properties, and client authentication based on long hashes is more secure than that based on the older short hashes.
To accommodate longer password hashes, the
Password
column in the
user
table was changed at this point to
be 41 bytes, its current length.
A widened Password
column can store
password hashes in both the pre-4.1 and 4.1 formats. The
format of any given hash value can be determined two ways:
The length: 4.1 and pre-4.1 hashes are 41 and 16 bytes, respectively.
Password hashes in the 4.1 format always begin with a
*
character, whereas passwords in the
pre-4.1 format never do.
To permit explicit generation of pre-4.1 password hashes, two additional changes were made:
The OLD_PASSWORD()
function was
added, which returns hash values in the 16-byte format.
For compatibility purposes, the
old_passwords
system
variable was added, to enable DBAs and applications
control over the hashing method. The default
old_passwords
value of
0 causes hashing to use the 4.1 method (41-byte hash
values), but setting
old_passwords=1
causes
hashing to use the pre-4.1 method. In this case,
PASSWORD()
produces
16-byte values and is equivalent to
OLD_PASSWORD()
To permit DBAs control over how clients are permitted to
connect, the secure_auth
system variable was added. Starting the server with this
variable disabled or enabled permits or prohibits clients to
connect using the older pre-4.1 password hashing method.
Before MySQL 5.6.5,
secure_auth
is disabled by
default. As of 5.6.5,
secure_auth
is enabled by
default to promote a more secure default configuration DBAs
can disable it at their discretion, but this is not
recommended, and pre-4.1 password hashes are deprecated and
should be avoided. (For account upgrade instructions, see
Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password
Plugin”.)
In addition, the mysql client supports a
--secure-auth
option that is
analogous to secure_auth
,
but from the client side. It can be used to prevent
connections to less secure accounts that use pre-4.1
password hashing. This option is disabled by default before
MySQL 5.6.7, enabled thereafter.
The widening of the Password
column in MySQL
4.1 from 16 bytes to 41 bytes affects installation or upgrade
operations as follows:
If you perform a new installation of MySQL, the
Password
column is made 41 bytes long
automatically.
Upgrades from MySQL 4.1 or later to current versions of
MySQL should not give rise to any issues in regard to the
Password
column because both versions use
the same column length and password hashing method.
For upgrades from a pre-4.1 release to 4.1 or later, you must upgrade the system tables after upgrading. (See Section 4.4.7, “mysql_upgrade — Check and Upgrade MySQL Tables”.)
The 4.1 hashing method is understood only by MySQL 4.1 (and higher) servers and clients, which can result in some compatibility problems. A 4.1 or higher client can connect to a pre-4.1 server, because the client understands both the pre-4.1 and 4.1 password hashing methods. However, a pre-4.1 client that attempts to connect to a 4.1 or higher server may run into difficulties. For example, a 4.0 mysql client may fail with the following error message:
shell> mysql -h localhost -u root
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
This phenomenon also occurs for attempts to use the older PHP
mysql
extension after upgrading to MySQL 4.1
or higher. (See Common Problems with MySQL and PHP.)
The following discussion describes the differences between the pre-4.1 and 4.1 hashing methods, and what you should do if you upgrade your server but need to maintain backward compatibility with pre-4.1 clients. (However, permitting connections by old clients is not recommended and should be avoided if possible.) This information is of particular importance to PHP programmers migrating MySQL databases from versions older than 4.1 to 4.1 or higher.
The differences between short and long password hashes are relevant both for how the server uses passwords during authentication and for how it generates password hashes for connected clients that perform password-changing operations.
The way in which the server uses password hashes during
authentication is affected by the width of the
Password
column:
If the column is short, only short-hash authentication is used.
If the column is long, it can hold either short or long hashes, and the server can use either format:
Pre-4.1 clients can connect, but because they know only about the pre-4.1 hashing method, they can authenticate only using accounts that have short hashes.
4.1 and later clients can authenticate using accounts that have short or long hashes.
Even for short-hash accounts, the authentication process is actually a bit more secure for 4.1 and later clients than for older clients. In terms of security, the gradient from least to most secure is:
Pre-4.1 client authenticating with short password hash
4.1 or later client authenticating with short password hash
4.1 or later client authenticating with long password hash
The way in which the server generates password hashes for
connected clients is affected by the width of the
Password
column and by the
old_passwords
system variable.
A 4.1 or later server generates long hashes only if certain
conditions are met: The Password
column must
be wide enough to hold long values and
old_passwords
must not be set
to 1.
Those conditions apply as follows:
The Password
column must be wide enough
to hold long hashes (41 bytes). If the column has not been
updated and still has the pre-4.1 width of 16 bytes, the
server notices that long hashes cannot fit into it and
generates only short hashes when a client performs
password-changing operations using the
PASSWORD()
function or a
password-generating statement. This is the behavior that
occurs if you have upgraded from a version of MySQL older
than 4.1 to 4.1 or later but have not yet run the
mysql_upgrade program to widen the
Password
column.
If the Password
column is wide, it can
store either short or long password hashes. In this case,
the PASSWORD()
function and
password-generating statements generate long hashes unless
the server was started with the
old_passwords
system
variable set to 1 to force the server to generate short
password hashes instead.
The purpose of the
old_passwords
system variable
is to permit backward compatibility with pre-4.1 clients under
circumstances where the server would otherwise generate long
password hashes. The option does not affect authentication (4.1
and later clients can still use accounts that have long password
hashes), but it does prevent creation of a long password hash in
the user
table as the result of a
password-changing operation. Were that permitted to occur, the
account could no longer be used by pre-4.1 clients. With
old_passwords
disabled, the
following undesirable scenario is possible:
An old pre-4.1 client connects to an account that has a short password hash.
The client changes its own password. With
old_passwords
disabled,
this results in the account having a long password hash.
The next time the old client attempts to connect to the account, it cannot, because the account has a long password hash that requires the 4.1 hashing method during authentication. (Once an account has a long password hash in the user table, only 4.1 and later clients can authenticate for it because pre-4.1 clients do not understand long hashes.)
This scenario illustrates that, if you must support older
pre-4.1 clients, it is problematic to run a 4.1 or higher server
without old_passwords
set to 1.
By running the server with
old_passwords=1
,
password-changing operations do not generate long password
hashes and thus do not cause accounts to become inaccessible to
older clients. (Those clients cannot inadvertently lock
themselves out by changing their password and ending up with a
long password hash.)
The downside of old_passwords=1
is that any passwords created or changed use short hashes, even
for 4.1 or later clients. Thus, you lose the additional security
provided by long password hashes. To create an account that has
a long hash (for example, for use by 4.1 clients) or to change
an existing account to use a long password hash, an
administrator can set the session value of
old_passwords
set to 0 while
leaving the global value set to 1:
mysql>SET @@SESSION.old_passwords = 0;
Query OK, 0 rows affected (0.00 sec) mysql>SELECT @@SESSION.old_passwords, @@GLOBAL.old_passwords;
+-------------------------+------------------------+ | @@SESSION.old_passwords | @@GLOBAL.old_passwords | +-------------------------+------------------------+ | 0 | 1 | +-------------------------+------------------------+ 1 row in set (0.00 sec) mysql>CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'newpass';
Query OK, 0 rows affected (0.03 sec) mysql>SET PASSWORD FOR 'existinguser'@'localhost' = PASSWORD('existingpass');
Query OK, 0 rows affected (0.00 sec)
The following scenarios are possible in MySQL 4.1 or later. The
factors are whether the Password
column is
short or long, and, if long, whether the server is started with
old_passwords
enabled or
disabled.
Scenario 1: Short
Password
column in user table:
Only short hashes can be stored in the
Password
column.
The server uses only short hashes during client authentication.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use short hashes
exclusively. Any change to an account's password results in
that account having a short password hash.
The value of old_passwords
is irrelevant because with a short
Password
column, the server generates
only short password hashes anyway.
This scenario occurs when a pre-4.1 MySQL installation has been
upgraded to 4.1 or later but mysql_upgrade
has not been run to upgrade the system tables in the
mysql
database. (This is not a recommended
configuration because it does not permit use of more secure 4.1
password hashing.)
Scenario 2: Long
Password
column; server started with
old_passwords=1
:
Short or long hashes can be stored in the
Password
column.
4.1 and later clients can authenticate for accounts that have short or long hashes.
Pre-4.1 clients can authenticate only for accounts that have short hashes.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use short hashes
exclusively. Any change to an account's password results in
that account having a short password hash.
In this scenario, newly created accounts have short password
hashes because old_passwords=1
prevents generation of long hashes. Also, if you create an
account with a long hash before setting
old_passwords
to 1, changing
the account's password while
old_passwords=1
results in the
account being given a short password, causing it to lose the
security benefits of a longer hash.
To create a new account that has a long password hash, or to
change the password of any existing account to use a long hash,
first set the session value of
old_passwords
set to 0 while
leaving the global value set to 1, as described previously.
In this scenario, the server has an up to date
Password
column, but is running with the
default password hashing method set to generate pre-4.1 hash
values. This is not a recommended configuration but may be
useful during a transitional period in which pre-4.1 clients and
passwords are upgraded to 4.1 or later. When that has been done,
it is preferable to run the server with
old_passwords=0
and
secure_auth=1
.
Scenario 3: Long
Password
column; server started with
old_passwords=0
:
Short or long hashes can be stored in the
Password
column.
4.1 and later clients can authenticate using accounts that have short or long hashes.
Pre-4.1 clients can authenticate only using accounts that have short hashes.
For connected clients, password hash-generating operations
involving the PASSWORD()
function or password-generating statements use long hashes
exclusively. A change to an account's password results in
that account having a long password hash.
As indicated earlier, a danger in this scenario is that it is
possible for accounts that have a short password hash to become
inaccessible to pre-4.1 clients. A change to such an account's
password made using the
PASSWORD()
function or a
password-generating statement results in the account being given
a long password hash. From that point on, no pre-4.1 client can
connect to the server using that account. The client must
upgrade to 4.1 or later.
If this is a problem, you can change a password in a special
way. For example, normally you use SET
PASSWORD
as follows to change an account password:
SET PASSWORD FOR 'some_user
'@'some_host
' = PASSWORD('password
');
To change the password but create a short hash, use the
OLD_PASSWORD()
function instead:
SET PASSWORD FOR 'some_user
'@'some_host
' = OLD_PASSWORD('password
');
OLD_PASSWORD()
is useful for situations in
which you explicitly want to generate a short hash.
The disadvantages for each of the preceding scenarios may be summarized as follows:
In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication.
In scenario 2, old_passwords=1
prevents accounts with short hashes from becoming inaccessible,
but password-changing operations cause accounts with long hashes
to revert to short hashes unless you take care to change the
session value of old_passwords
to 0 first.
In scenario 3, accounts with short hashes become inaccessible to
pre-4.1 clients if you change their passwords without explicitly
using OLD_PASSWORD()
.
The best way to avoid compatibility problems related to short password hashes is to not use them:
Upgrade all client programs to MySQL 4.1 or later.
Run the server with
old_passwords=0
.
Reset the password for any account with a short password hash to use a long password hash.
For additional security, run the server with
secure_auth=1
.
When you connect to a MySQL server, you should use a password. The password is not transmitted as cleartext over the connection. Password handling during the client connection sequence was upgraded in MySQL 4.1.1 to be very secure. If you are still using pre-4.1.1-style passwords, the encryption algorithm is not as strong as the newer algorithm. With some effort, a clever attacker who can sniff the traffic between the client and the server can crack the password. (See Section 6.1.2.4, “Password Hashing in MySQL”, for a discussion of the different password handling methods.)
All other information is transferred as text, and can be read by anyone who is able to watch the connection. If the connection between the client and the server goes through an untrusted network, and you are concerned about this, you can use the compressed protocol to make traffic much more difficult to decipher. You can also use MySQL's internal SSL support to make the connection even more secure. See Section 6.3, “Using Encrypted Connections”. Alternatively, use SSH to get an encrypted TCP/IP connection between a MySQL server and a MySQL client. You can find an Open Source SSH client at http://www.openssh.org/, and a comparison of both Open Source and Commercial SSH clients at http://en.wikipedia.org/wiki/Comparison_of_SSH_clients.
To make a MySQL system secure, you should strongly consider the following suggestions:
Require all MySQL accounts to have a password. A client
program does not necessarily know the identity of the person
running it. It is common for client/server applications that
the user can specify any user name to the client program. For
example, anyone can use the mysql program
to connect as any other person simply by invoking it as
mysql -u
if
other_user
db_name
other_user
has no password. If all
accounts have a password, connecting using another user's
account becomes much more difficult.
For a discussion of methods for setting passwords, see Section 6.2.10, “Assigning Account Passwords”.
Make sure that the only Unix user account with read or write privileges in the database directories is the account that is used for running mysqld.
Never run the MySQL server as the Unix root
user. This is extremely dangerous, because any user with the
FILE
privilege is able to cause
the server to create files as root
(for
example, ~root/.bashrc
). To prevent this,
mysqld refuses to run as
root
unless that is specified explicitly
using the --user=root
option.
mysqld can (and should) be run as an
ordinary, unprivileged user instead. You can create a separate
Unix account named mysql
to make everything
even more secure. Use this account only for administering
MySQL. To start mysqld as a different Unix
user, add a user
option that specifies the
user name in the [mysqld]
group of the
my.cnf
option file where you specify
server options. For example:
[mysqld] user=mysql
This causes the server to start as the designated user whether you start it manually or by using mysqld_safe or mysql.server. For more details, see Section 6.1.5, “How to Run MySQL as a Normal User”.
Running mysqld as a Unix user other than
root
does not mean that you need to change
the root
user name in the
user
table. User names for MySQL
accounts have nothing to do with user names for Unix
accounts.
Do not grant the FILE
privilege
to nonadministrative users. Any user that has this privilege
can write a file anywhere in the file system with the
privileges of the mysqld daemon. This
includes the server's data directory containing the files that
implement the privilege tables. To make
FILE
-privilege operations a bit
safer, files generated with
SELECT ... INTO
OUTFILE
do not overwrite existing files and are
writable by everyone.
The FILE
privilege may also be
used to read any file that is world-readable or accessible to
the Unix user that the server runs as. With this privilege,
you can read any file into a database table. This could be
abused, for example, by using LOAD
DATA
to load /etc/passwd
into a
table, which then can be displayed with
SELECT
.
To limit the location in which files can be read and written,
set the secure_file_priv
system to a specific directory. See
Section 5.1.7, “Server System Variables”.
Do not grant the PROCESS
or
SUPER
privilege to
nonadministrative users. The output of mysqladmin
processlist and SHOW
PROCESSLIST
shows the text of any statements
currently being executed, so any user who is permitted to see
the server process list might be able to see statements issued
by other users such as UPDATE user SET
password=PASSWORD('not_secure')
.
mysqld reserves an extra connection for
users who have the SUPER
privilege, so that a MySQL root
user can
log in and check server activity even if all normal
connections are in use.
The SUPER
privilege can be used
to terminate client connections, change server operation by
changing the value of system variables, and control
replication servers.
Do not permit the use of symlinks to tables. (This capability
can be disabled with the
--skip-symbolic-links
option.) This is especially important if you run
mysqld as root
, because
anyone that has write access to the server's data directory
then could delete any file in the system! See
Section 8.12.3.2, “Using Symbolic Links for MyISAM Tables on Unix”.
Stored programs and views should be written using the security guidelines discussed in Section 23.6, “Stored Object Access Control”.
If you do not trust your DNS, you should use IP addresses rather than host names in the grant tables. In any case, you should be very careful about creating grant table entries using host name values that contain wildcards.
If you want to restrict the number of connections permitted to
a single account, you can do so by setting the
max_user_connections
variable
in mysqld. The CREATE
USER
and ALTER USER
statements also support resource control options for limiting
the extent of server use permitted to an account. See
Section 13.7.1.2, “CREATE USER Statement”, and
Section 13.7.1.1, “ALTER USER Statement”.
If the plugin directory is writable by the server, it may be
possible for a user to write executable code to a file in the
directory using SELECT
... INTO DUMPFILE
. This can be prevented by making
plugin_dir
read only to the
server or by setting
secure_file_priv
to a
directory where SELECT
writes
can be made safely.
The following table shows mysqld options and system variables that affect security. For descriptions of each of these, see Section 5.1.6, “Server Command Options”, and Section 5.1.7, “Server System Variables”.
Table 6.1 Security Option and Variable Summary
Name | Cmd-Line | Option File | System Var | Status Var | Var Scope | Dynamic |
---|---|---|---|---|---|---|
allow-suspicious-udfs | Yes | Yes | ||||
automatic_sp_privileges | Yes | Yes | Yes | Global | Yes | |
chroot | Yes | Yes | ||||
des-key-file | Yes | Yes | ||||
local_infile | Yes | Yes | Yes | Global | Yes | |
old_passwords | Yes | Yes | Yes | Both | Yes | |
safe-user-create | Yes | Yes | ||||
secure_auth | Yes | Yes | Yes | Global | Yes | |
secure_file_priv | Yes | Yes | Yes | Global | No | |
skip-grant-tables | Yes | Yes | ||||
skip_name_resolve | Yes | Yes | Yes | Global | No | |
skip_networking | Yes | Yes | Yes | Global | No | |
skip_show_database | Yes | Yes | Yes | Global | No |
On Windows, you can run the server as a Windows service using a normal user account.
On Linux, for installations performed using a MySQL repository,
RPM packages, or Debian packages, the MySQL server
mysqld should be started by the local
mysql
operating system user. Starting by
another operating system user is not supported by the init scripts
that are included as part of the installation.
On Unix (or Linux for installations performed using
tar
or tar.gz
packages)
, the MySQL server mysqld can be started and
run by any user. However, you should avoid running the server as
the Unix root
user for security reasons. To
change mysqld to run as a normal unprivileged
Unix user user_name
, you must do the
following:
Stop the server if it is running (use mysqladmin shutdown).
Change the database directories and files so that
user_name
has privileges to read
and write files in them (you might need to do this as the Unix
root
user):
shell> chown -R user_name
/path/to/mysql/datadir
If you do not do this, the server will not be able to access
databases or tables when it runs as
user_name
.
If directories or files within the MySQL data directory are
symbolic links, chown -R
might not follow
symbolic links for you. If it does not, you will also need to
follow those links and change the directories and files they
point to.
Start the server as user user_name
.
Another alternative is to start mysqld as
the Unix root
user and use the
--user=
option. mysqld starts, then switches to run
as the Unix user user_name
user_name
before
accepting any connections.
To start the server as the given user automatically at system
startup time, specify the user name by adding a
user
option to the
[mysqld]
group of the
/etc/my.cnf
option file or the
my.cnf
option file in the server's data
directory. For example:
[mysqld]
user=user_name
If your Unix machine itself is not secured, you should assign
passwords to the MySQL root
account in the
grant tables. Otherwise, any user with a login account on that
machine can run the mysql client with a
--user=root
option and perform any
operation. (It is a good idea to assign passwords to MySQL
accounts in any case, but especially so when other login accounts
exist on the server host.) See
Section 2.10.4, “Securing the Initial MySQL Account”.
The LOAD DATA
statement can load a
file located on the server host, or, if the
LOCAL
keyword is specified, on the client host.
There are two potential security issues with the
LOCAL
version of LOAD
DATA
:
The transfer of the file from the client host to the server
host is initiated by the MySQL server. In theory, a patched
server could be built that would tell the client program to
transfer a file of the server's choosing rather than the file
named by the client in the LOAD
DATA
statement. Such a server could access any file
on the client host to which the client user has read access.
(A patched server could in fact reply with a file-transfer
request to any statement, not just
LOAD DATA
LOCAL
, so a more fundamental issue is that clients
should not connect to untrusted servers.)
In a Web environment where the clients are connecting from a
Web server, a user could use
LOAD DATA
LOCAL
to read any files that the Web server process
has read access to (assuming that a user could run any
statement against the SQL server). In this environment, the
client with respect to the MySQL server actually is the Web
server, not a remote program being run by users who connect to
the Web server.
To avoid LOAD DATA
issues, clients
should avoid using LOCAL
. To avoid connecting
to untrusted servers, clients can establish a secure connection
and verify the server identity by connecting using the
--ssl-mode=VERIFY_IDENTITY
option
and the appropriate CA certificate.
To enable adminstrators and applications to manage the local data
loading capability, LOCAL
configuration works
like this:
On the server side:
The local_infile
system
variable controls server-side LOCAL
capability. Depending on the
local_infile
setting, the
server refuses or permits local data loading by clients
that have LOCAL
enabled on the client
side. By default,
local_infile
is enabled.
To explicitly cause the server to refuse or permit
LOAD DATA
LOCAL
statements (regardless of how client
programs and libraries are configured at build time or
runtime), start mysqld with
local_infile
disabled or
enabled, respectively.
local_infile
can also be
set at runtime.
On the client side:
The ENABLED_LOCAL_INFILE
CMake option controls the compiled-in
default LOCAL
capability for the MySQL
client library. Clients that make no explicit arrangements
therefore have LOCAL
capability
disabled or enabled according to the
ENABLED_LOCAL_INFILE
setting
specified at MySQL build time.
By default, the client library in MySQL binary
distributions is compiled with
ENABLED_LOCAL_INFILE
enabled. If you compile MySQL from source, configure it
with ENABLED_LOCAL_INFILE
disabled or enabled based on whether clients that make no
explicit arrangements should have LOCAL
capability disabled or enabled, respectively.
Client programs that use the C API can control load data
loading explicitly by invoking
mysql_options()
to disable
or enable the MYSQL_OPT_LOCAL_INFILE
option. See Section 27.7.6.50, “mysql_options()”.
For the mysql client, local data
loading is disabled by default. To disable or enable it
explicitly, use the
--local-infile=0
or
--local-infile[=1]
option.
For the mysqlimport client, local data
loading is disabled by default. To disable or enable it
explicitly, use the
--local=0
or
--local[=1]
option.
If you use LOAD
DATA LOCAL
in Perl scripts or other programs
that read the [client]
group from
option files, you can add an
local-infile
option setting to that
group. To prevent problems for programs that do not
understand this option, specify it using the
loose-
prefix:
[client] loose-local-infile=0
or:
[client] loose-local-infile=1
In all cases, successful use of a LOCAL
load operation by a client also requires that the server
permits it.
If LOCAL
capability is disabled, on either the
server or client side, a client that attempts to issue a
LOAD DATA
LOCAL
statement receives the following error message:
ERROR 1148: The used command is not allowed with this MySQL version
Applications that access MySQL should not trust any data entered
by users, who can try to trick your code by entering special or
escaped character sequences in Web forms, URLs, or whatever
application you have built. Be sure that your application remains
secure if a user enters something like ; DROP DATABASE
mysql;
. This is an extreme example, but large security
leaks and data loss might occur as a result of hackers using
similar techniques, if you do not prepare for them.
A common mistake is to protect only string data values. Remember
to check numeric data as well. If an application generates a query
such as SELECT * FROM table WHERE ID=234
when a
user enters the value 234
, the user can enter
the value 234 OR 1=1
to cause the application
to generate the query SELECT * FROM table WHERE ID=234 OR
1=1
. As a result, the server retrieves every row in the
table. This exposes every row and causes excessive server load.
The simplest way to protect from this type of attack is to use
single quotation marks around the numeric constants:
SELECT * FROM table WHERE ID='234'
. If the user
enters extra information, it all becomes part of the string. In a
numeric context, MySQL automatically converts this string to a
number and strips any trailing nonnumeric characters from it.
Sometimes people think that if a database contains only publicly available data, it need not be protected. This is incorrect. Even if it is permissible to display any row in the database, you should still protect against denial of service attacks (for example, those that are based on the technique in the preceding paragraph that causes the server to waste resources). Otherwise, your server becomes unresponsive to legitimate users.
Checklist:
Enable strict SQL mode to tell the server to be more restrictive of what data values it accepts. See Section 5.1.10, “Server SQL Modes”.
Try to enter single and double quotation marks
('
and "
) in all of your
Web forms. If you get any kind of MySQL error, investigate the
problem right away.
Try to modify dynamic URLs by adding %22
("
), %23
(#
), and %27
('
) to them.
Try to modify data types in dynamic URLs from numeric to character types using the characters shown in the previous examples. Your application should be safe against these and similar attacks.
Try to enter characters, spaces, and special symbols rather than numbers in numeric fields. Your application should remove them before passing them to MySQL or else generate an error. Passing unchecked values to MySQL is very dangerous!
Check the size of data before passing it to MySQL.
Have your application connect to the database using a user name different from the one you use for administrative purposes. Do not give your applications any access privileges they do not need.
Many application programming interfaces provide a means of escaping special characters in data values. Properly used, this prevents application users from entering values that cause the application to generate statements that have a different effect than you intend:
MySQL C API: Use the
mysql_real_escape_string_quote()
API call.
MySQL++: Use the escape
and
quote
modifiers for query streams.
PHP: Use either the mysqli
or
pdo_mysql
extensions, and not the older
ext/mysql
extension. The preferred API's
support the improved MySQL authentication protocol and
passwords, as well as prepared statements with placeholders.
See also Choosing an API.
If the older ext/mysql
extension must be
used, then for escaping use the
mysql_real_escape_string_quote()
function and not
mysql_escape_string()
or
addslashes()
because only
mysql_real_escape_string_quote()
is character set-aware; the other functions can be
“bypassed” when using (invalid) multibyte
character sets.
Perl DBI: Use placeholders or the quote()
method.
Ruby DBI: Use placeholders or the quote()
method.
Java JDBC: Use a PreparedStatement
object
and placeholders.
Other programming interfaces might have similar capabilities.
MySQL enables the creation of accounts that permit client users to
connect to the server and access data managed by the server. The
primary function of the MySQL privilege system is to authenticate a
user who connects from a given host and to associate that user with
privileges on a database such as
SELECT
,
INSERT
,
UPDATE
, and
DELETE
. Additional functionality
includes the ability to grant privileges for administrative
operations.
To control which users can connect, each account can be assigned
authentication credentials such as a password. The user interface to
MySQL accounts consists of SQL statements such as
CREATE USER
,
GRANT
, and
REVOKE
. See
Section 13.7.1, “Account Management Statements”.
The MySQL privilege system ensures that all users may perform only the operations permitted to them. As a user, when you connect to a MySQL server, your identity is determined by the host from which you connect and the user name you specify. When you issue requests after connecting, the system grants privileges according to your identity and what you want to do.
MySQL considers both your host name and user name in identifying you
because there is no reason to assume that a given user name belongs
to the same person on all hosts. For example, the user
joe
who connects from
office.example.com
need not be the same person as
the user joe
who connects from
home.example.com
. MySQL handles this by enabling
you to distinguish users on different hosts that happen to have the
same name: You can grant one set of privileges for connections by
joe
from office.example.com
,
and a different set of privileges for connections by
joe
from home.example.com
. To
see what privileges a given account has, use the
SHOW GRANTS
statement. For example:
SHOW GRANTS FOR 'joe'@'office.example.com'; SHOW GRANTS FOR 'joe'@'home.example.com';
Internally, the server stores privilege information in the grant
tables of the mysql
system database. The MySQL
server reads the contents of these tables into memory when it starts
and bases access-control decisions on the in-memory copies of the
grant tables.
MySQL access control involves two stages when you run a client program that connects to the server:
Stage 1: The server accepts or rejects the connection based on your identity and whether you can verify your identity by supplying the correct password.
Stage 2: Assuming that you can
connect, the server checks each statement you issue to determine
whether you have sufficient privileges to perform it. For example,
if you try to select rows from a table in a database or drop a table
from the database, the server verifies that you have the
SELECT
privilege for the table or the
DROP
privilege for the database.
For a more detailed description of what happens during each stage, see Section 6.2.5, “Access Control, Stage 1: Connection Verification”, and Section 6.2.6, “Access Control, Stage 2: Request Verification”. For help in diagnosing privilege-related problems, see Section 6.2.17, “Troubleshooting Problems Connecting to MySQL”.
If your privileges are changed (either by yourself or someone else) while you are connected, those changes do not necessarily take effect immediately for the next statement that you issue. For details about the conditions under which the server reloads the grant tables, see Section 6.2.9, “When Privilege Changes Take Effect”.
There are some things that you cannot do with the MySQL privilege system:
You cannot explicitly specify that a given user should be denied access. That is, you cannot explicitly match a user and then refuse the connection.
You cannot specify that a user has privileges to create or drop tables in a database but not to create or drop the database itself.
A password applies globally to an account. You cannot associate a password with a specific object such as a database, table, or routine.
MySQL stores accounts in the user
table of the
mysql
system database. An account is defined in
terms of a user name and the client host or hosts from which the
user can connect to the server. For information about account
representation in the user
table, see
Section 6.2.3, “Grant Tables”.
An account may also have authentication credentials such as a password. The credentials are handled by the account authentication plugin. MySQL supports multiple authentication plugins. Some of them use built-in authentication methods, whereas others enable authentication using external authentication methods. See Section 6.2.13, “Pluggable Authentication”.
There are several distinctions between the way user names and passwords are used by MySQL and your operating system:
User names, as used by MySQL for authentication purposes, have
nothing to do with user names (login names) as used by Windows
or Unix. On Unix, most MySQL clients by default try to log in
using the current Unix user name as the MySQL user name, but
that is for convenience only. The default can be overridden
easily, because client programs permit any user name to be
specified with a -u
or
--user
option. This means that anyone can
attempt to connect to the server using any user name, so you
cannot make a database secure in any way unless all MySQL
accounts have passwords. Anyone who specifies a user name for
an account that has no password can connect successfully to
the server.
MySQL user names are up to 32 characters long. Operating system user names may have a different maximum length.
The MySQL user name length limit is hardcoded in MySQL
servers and clients, and trying to circumvent it by
modifying the definitions of the tables in the
mysql
database does not
work.
You should never alter the structure of tables in the
mysql
database in any manner whatsoever
except by means of the procedure that is described in
Section 2.11, “Upgrading MySQL”. Attempting to redefine MySQL's
system tables in any other fashion results in undefined and
unsupported behavior. The server is free to ignore rows that
become malformed as a result of such modifications.
To authenticate client connections for accounts that use
built-in authentication methods, the server uses passwords
stored in the user
table. These passwords
are distinct from passwords for logging in to your operating
system. There is no necessary connection between the
“external” password you use to log in to a
Windows or Unix machine and the password you use to access the
MySQL server on that machine.
If the server authenticates a client using some other plugin,
the authentication method that the plugin implements may or
may not use a password stored in the user
table. In this case, it is possible that an external password
is also used to authenticate to the MySQL server.
Passwords stored in the user
table are
encrypted using plugin-specific algorithms. For information
about MySQL native password hashing, see
Section 6.1.2.4, “Password Hashing in MySQL”.
If the user name and password contain only ASCII characters,
it is possible to connect to the server regardless of
character set settings. To enable connections when the user
name or password contain non-ASCII characters, client
applications should call the
mysql_options()
C API function
with the MYSQL_SET_CHARSET_NAME
option and
appropriate character set name as arguments. This causes
authentication to take place using the specified character
set. Otherwise, authentication fails unless the server default
character set is the same as the encoding in the
authentication defaults.
Standard MySQL client programs support a
--default-character-set
option that causes
mysql_options()
to be called
as just described. In addition, character set autodetection is
supported as described in
Section 10.4, “Connection Character Sets and Collations”. For programs that use a
connector that is not based on the C API, the connector may
provide an equivalent to
mysql_options()
that can be
used instead. Check the connector documentation.
The preceding notes do not apply for ucs2
,
utf16
, and utf32
, which
are not permitted as client character sets.
The MySQL installation process populates the grant tables with an
initial root
account, as described in
Section 2.10.4, “Securing the Initial MySQL Account”, which also discusses how to
assign a password to it. Thereafter, you normally set up, modify,
and remove MySQL accounts using statements such as
CREATE USER
,
DROP USER
,
GRANT
, and
REVOKE
. See
Section 6.2.7, “Adding Accounts, Assigning Privileges, and Dropping Accounts”, and
Section 13.7.1, “Account Management Statements”.
To connect to a MySQL server with a command-line client, specify user name and password options as necessary for the account that you want to use:
shell> mysql --user=finley --password db_name
If you prefer short options, the command looks like this:
shell> mysql -u finley -p db_name
If you omit the password value following the
--password
or -p
option on the command line (as just shown), the client prompts for
one. Alternatively, the password can be specified on the command
line:
shell>mysql --user=finley --password=
shell>password
db_name
mysql -u finley -p
password
db_name
If you use the -p
option, there must be
no space between -p
and the
following password value.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1, “End-User Guidelines for Password Security”. To avoid giving the password on the command line, use an option file or a login path file. See Section 4.2.2.2, “Using Option Files”, and Section 4.6.6, “mysql_config_editor — MySQL Configuration Utility”.
For additional information about specifying user names, passwords, and other connection parameters, see Section 4.2.4, “Connecting to the MySQL Server Using Command Options”.
The privileges granted to a MySQL account determine which operations the account can perform. MySQL privileges differ in the contexts in which they apply and at different levels of operation:
Administrative privileges enable users to manage operation of the MySQL server. These privileges are global because they are not specific to a particular database.
Database privileges apply to a database and to all objects within it. These privileges can be granted for specific databases, or globally so that they apply to all databases.
Privileges for database objects such as tables, indexes, views, and stored routines can be granted for specific objects within a database, for all objects of a given type within a database (for example, all tables in a database), or globally for all objects of a given type in all databases.
Information about account privileges is stored in the grant tables
in the mysql
system database. For a description
of the structure and contents of these tables, see
Section 6.2.3, “Grant Tables”. The MySQL server reads the
contents of the grant tables into memory when it starts, and
reloads them under the circumstances indicated in
Section 6.2.9, “When Privilege Changes Take Effect”. The server bases
access-control decisions on the in-memory copies of the grant
tables.
Some MySQL releases introduce changes to the grant tables to add new privileges or features. To make sure that you can take advantage of any new capabilities, update your grant tables to the current structure whenever you upgrade MySQL. See Section 2.11, “Upgrading MySQL”.
The following sections summarize the available privileges, provide more detailed descriptions of each privilege, and offer usage guidelines.
The following table shows the privilege names used in
GRANT
and
REVOKE
statements, along with the
column name associated with each privilege in the grant tables
and the context in which the privilege applies.
Table 6.2 Permissible Privileges for GRANT and REVOKE
Privilege | Grant Table Column | Context |
---|---|---|
ALL [PRIVILEGES] |
Synonym for “all privileges” | Server administration |
ALTER |
Alter_priv |
Tables |
ALTER ROUTINE |
Alter_routine_priv |
Stored routines |
CREATE |
Create_priv |
Databases, tables, or indexes |
CREATE ROUTINE |
Create_routine_priv |
Stored routines |
CREATE TABLESPACE |
Create_tablespace_priv |
Server administration |
CREATE TEMPORARY TABLES |
Create_tmp_table_priv |
Tables |
CREATE USER |
Create_user_priv |
Server administration |
CREATE VIEW |
Create_view_priv |
Views |
DELETE |
Delete_priv |
Tables |
DROP |
Drop_priv |
Databases, tables, or views |
EVENT |
Event_priv |
Databases |
EXECUTE |
Execute_priv |
Stored routines |
FILE |
File_priv |
File access on server host |
GRANT OPTION |
Grant_priv |
Databases, tables, or stored routines |
INDEX |
Index_priv |
Tables |
INSERT |
Insert_priv |
Tables or columns |
LOCK TABLES |
Lock_tables_priv |
Databases |
PROCESS |
Process_priv |
Server administration |
PROXY |
See proxies_priv table |
Server administration |
REFERENCES |
References_priv |
Databases or tables |
RELOAD |
Reload_priv |
Server administration |
REPLICATION CLIENT |
Repl_client_priv |
Server administration |
REPLICATION SLAVE |
Repl_slave_priv |
Server administration |
SELECT |
Select_priv |
Tables or columns |
SHOW DATABASES |
Show_db_priv |
Server administration |
SHOW VIEW |
Show_view_priv |
Views |
SHUTDOWN |
Shutdown_priv |
Server administration |
SUPER |
Super_priv |
Server administration |
TRIGGER |
Trigger_priv |
Tables |
UPDATE |
Update_priv |
Tables or columns |
USAGE |
Synonym for “no privileges” | Server administration |
The following list provides general descriptions of each privilege available in MySQL. Particular SQL statements might have more specific privilege requirements than indicated here. If so, the description for the statement in question provides the details.
These privilege specifiers are shorthand for “all
privileges available at a given privilege level”
(except GRANT OPTION
). For
example, granting ALL
at the
global or table level grants all global privileges or all
table-level privileges, respectively.
Enables use of the ALTER
TABLE
statement to change the structure of tables.
ALTER TABLE
also requires the
CREATE
and
INSERT
privileges. Renaming a
table requires ALTER
and
DROP
on the old table,
CREATE
, and
INSERT
on the new table.
Enables use of statements that alter or drop stored routines (stored procedures and functions).
Enables use of statements that create new databases and tables.
Enables use of statements that create stored routines (stored procedures and functions).
Enables use of statements that create, alter, or drop tablespaces and log file groups.
Enables the creation of temporary tables using the
CREATE TEMPORARY TABLE
statement.
After a session has created a temporary table, the server
performs no further privilege checks on the table. The
creating session can perform any operation on the table,
such as DROP TABLE
,
INSERT
,
UPDATE
, or
SELECT
. For more information,
see Section 13.1.18.3, “CREATE TEMPORARY TABLE Statement”.
Enables use of the ALTER
USER
, CREATE USER
,
DROP USER
,
RENAME USER
, and
REVOKE ALL
PRIVILEGES
statements.
Enables use of the CREATE
VIEW
statement.
Enables rows to be deleted from tables in a database.
Enables use of statements that drop (remove) existing
databases, tables, and views. The
DROP
privilege is required to
use the ALTER TABLE ... DROP PARTITION
statement on a partitioned table. The
DROP
privilege is also
required for TRUNCATE TABLE
.
Enables use of statements that create, alter, drop, or display events for the Event Scheduler.
Enables use of statements that execute stored routines (stored procedures and functions).
Affects the following operations and server behaviors:
Enables reading and writing files on the server host
using the LOAD DATA
and
SELECT ...
INTO OUTFILE
statements and the
LOAD_FILE()
function. A
user who has the FILE
privilege can read any file on the server host that is
either world-readable or readable by the MySQL server.
(This implies the user can read any file in any database
directory, because the server can access any of those
files.)
Enables creating new files in any directory where the MySQL server has write access. This includes the server's data directory containing the files that implement the privilege tables.
As of MySQL 5.7.17, enables use of the DATA
DIRECTORY
or INDEX
DIRECTORY
table option for the
CREATE TABLE
statement.
As a security measure, the server does not overwrite existing files.
To limit the location in which files can be read and
written, set the
secure_file_priv
system
variable to a specific directory. See
Section 5.1.7, “Server System Variables”.
Enables you to grant to or revoke from other users those privileges that you yourself possess.
Enables use of statements that create or drop (remove)
indexes. INDEX
applies to
existing tables. If you have the
CREATE
privilege for a table,
you can include index definitions in the
CREATE TABLE
statement.
Enables rows to be inserted into tables in a database.
INSERT
is also required for
the ANALYZE TABLE
,
OPTIMIZE TABLE
, and
REPAIR TABLE
table-maintenance statements.
Enables use of explicit LOCK
TABLES
statements to lock tables for which you
have the SELECT
privilege.
This includes use of write locks, which prevents other
sessions from reading the locked table.
Enables display of information about the threads executing
within the server (that is, information about the statements
being executed by sessions). The privilege enables use of
SHOW PROCESSLIST
or
mysqladmin processlist to see threads
belonging to other accounts; you can always see your own
threads. The PROCESS
privilege also enables use of SHOW
ENGINE
.
Enables one user to impersonate or become known as another user. See Section 6.2.14, “Proxy Users”.
Creation of a foreign key constraint requires the
REFERENCES
privilege for the
parent table.
Enables use of the FLUSH
statement. It also enables mysqladmin
commands that are equivalent to
FLUSH
operations:
flush-hosts
,
flush-logs
,
flush-privileges
,
flush-status
,
flush-tables
,
flush-threads
,
refresh
, and reload
.
The reload
command tells the server to
reload the grant tables into memory.
flush-privileges
is a synonym for
reload
. The refresh
command closes and reopens the log files and flushes all
tables. The other
flush-
commands perform functions similar to
xxx
refresh
, but are more specific and may be
preferable in some instances. For example, if you want to
flush just the log files, flush-logs
is a
better choice than refresh
.
The RELOAD
privilege also
enables use of the RESET
MASTER
and RESET
SLAVE
statements.
Enables use of the SHOW MASTER
STATUS
, SHOW SLAVE
STATUS
, and SHOW BINARY
LOGS
statements. Grant this privilege to accounts
that are used by slave servers to connect to the current
server as their master.
Enables the account to request updates that have been made
to databases on the master server, using the
SHOW SLAVE HOSTS
,
SHOW RELAYLOG EVENTS
, and
SHOW BINLOG EVENTS
statements. This privilege is also required to use the
mysqlbinlog options
--read-from-remote-server
(-R
) and
--read-from-remote-master
.
Grant this privilege to accounts that are used by slave
servers to connect to the current server as their master.
Enables rows to be selected from tables in a database.
SELECT
statements require the
SELECT
privilege only if they
actually access tables. Some
SELECT
statements do not
access tables and can be executed without permission for any
database. For example, you can use
SELECT
as a simple calculator
to evaluate expressions that make no reference to tables:
SELECT 1+1; SELECT PI()*2;
The SELECT
privilege is also
needed for other statements that read column values. For
example, SELECT
is needed for
columns referenced on the right hand side of
col_name
=expr
assignment in UPDATE
statements or for columns named in the
WHERE
clause of
DELETE
or
UPDATE
statements.
The SELECT
privilege is
needed for tables or views used with
EXPLAIN
, including any
underlying tables in view definitions.
Enables the account to see database names by issuing the
SHOW DATABASE
statement. Accounts that do
not have this privilege see only databases for which they
have some privileges, and cannot use the statement at all if
the server was started with the
--skip-show-database
option.
Because a global privilege is considered a privilege for
all databases, any global privilege
enables a user to see all database names with
SHOW DATABASES
or by
examining the INFORMATION_SCHEMA
SCHEMATA
table.
Enables use of the SHOW CREATE
VIEW
statement. This privilege is also needed for
views used with EXPLAIN
.
Enables use of the SHUTDOWN
statement, the mysqladmin shutdown
command, and the
mysql_shutdown()
C API
function.
Affects the following operations and server behaviors:
Enables server configuration changes by modifying global
system variables. For some system variables, setting the
session value also requires the
SUPER
privilege. If a
system variable is restricted and requires a special
privilege to set the session value, the variable
description indicates that restriction. Examples include
binlog_format
,
sql_log_bin
, and
sql_log_off
. See also
Section 5.1.8.1, “System Variable Privileges”.
Enables changes to global transaction characteristics (see Section 13.3.6, “SET TRANSACTION Statement”).
Enables the account to start and stop replication, including Group Replication.
Enables use of the CHANGE MASTER
TO
and CHANGE REPLICATION
FILTER
statements.
Enables binary log control by means of the
PURGE BINARY LOGS
and
BINLOG
statements.
Enables setting the effective authorization ID when
executing a view or stored program. A user with this
privilege can specify any account in the
DEFINER
attribute of a view or stored
program.
Enables use of the CREATE
SERVER
, ALTER
SERVER
, and DROP
SERVER
statements.
Enables use of the mysqladmin debug command.
Enables InnoDB
encryption key
rotation.
Enables reading the DES key file by the
DES_ENCRYPT()
function.
Enables execution of Version Tokens user-defined functions.
Enables control over client connections not permitted to
non-SUPER
accounts:
Enables use of the
KILL
statement or
mysqladmin kill command to kill
threads belonging to other accounts. (An account can
always kill its own threads.)
The server does not execute
init_connect
system
variable content when
SUPER
clients
connect.
The server accepts one connection from a
SUPER
client even if
the connection limit configured by the
max_connections
system variable is reached.
A server in offline mode
(offline_mode
enabled) does not terminate
SUPER
client
connections at the next client request, and accepts
new connections from
SUPER
clients.
Updates can be performed even when the
read_only
system
variable is enabled. This applies to explicit table
updates, and to use of account-management statements
such as GRANT
and
REVOKE
that update
tables implicitly.
You may also need the SUPER
privilege to create or alter stored functions if binary
logging is enabled, as described in
Section 23.7, “Stored Program Binary Logging”.
Enables trigger operations. You must have this privilege for a table to create, drop, execute, or display triggers for that table.
When a trigger is activated (by a user who has privileges to
execute INSERT
,
UPDATE
, or
DELETE
statements for the
table associated with the trigger), trigger execution
requires that the user who defined the trigger still have
the TRIGGER
privilege for the
table.
Enables rows to be updated in tables in a database.
This privilege specifier stands for “no
privileges.” It is used at the global level with
GRANT
to modify account
attributes such as resource limits or SSL characteristics
without naming specific account privileges in the privilege
list. SHOW GRANTS
displays
USAGE
to indicate that an
account has no privileges at a privilege level.
It is a good idea to grant to an account only those privileges
that it needs. You should exercise particular caution in
granting the FILE
and
administrative privileges:
FILE
can be abused to read
into a database table any files that the MySQL server can
read on the server host. This includes all world-readable
files and files in the server's data directory. The table
can then be accessed using
SELECT
to transfer its
contents to the client host.
GRANT OPTION
enables users to
give their privileges to other users. Two users that have
different privileges and with the GRANT
OPTION
privilege are able to combine privileges.
ALTER
may be used to subvert
the privilege system by renaming tables.
SHUTDOWN
can be abused to
deny service to other users entirely by terminating the
server.
PROCESS
can be used to view
the plain text of currently executing statements, including
statements that set or change passwords.
SUPER
can be used to
terminate other sessions or change how the server operates.
Privileges granted for the mysql
system
database itself can be used to change passwords and other
access privilege information:
Passwords are stored encrypted, so a malicious user
cannot simply read them to know the plain text password.
However, a user with write access to the
mysql.user
system table
authentication_string
column can
change an account's password, and then connect to the
MySQL server using that account.
INSERT
or
UPDATE
granted for the
mysql
system database enable a user
to add privileges or modify existing privileges,
respectively.
DROP
for the
mysql
system database enables a user
to remote privilege tables, or even the database itself.
The mysql
system database includes several
grant tables that contain information about user accounts and the
privileges held by them. This section describes those tables. For
information about other tables in the system database, see
Section 5.3, “The mysql System Database”.
The discussion here describes the underlying structure of the
grant tables and how the server uses their contents when
interacting with clients. However, normally you do not modify the
grant tables directly. Modifications occur indirectly when you use
account-management statements such as CREATE
USER
, GRANT
, and
REVOKE
to set up accounts and
control the privileges available to each one. See
Section 13.7.1, “Account Management Statements”. When you use such
statements to perform account manipulations, the server modifies
the grant tables on your behalf.
Direct modification of grant tables using statements such as
INSERT
,
UPDATE
, or
DELETE
is discouraged and done at
your own risk. The server is free to ignore rows that become
malformed as a result of such modifications.
As of MySQL 5.7.18, for any operation that modifies a grant table, the server checks whether the table has the expected structure and produces an error if not. To update the tables to the expected structure, perform the MySQL upgrade procedure. See Section 2.11, “Upgrading MySQL”.
These mysql
database tables contain grant
information:
user
:
User accounts, global privileges, and other nonprivilege
columns.
db
:
Database-level privileges.
tables_priv
:
Table-level privileges.
columns_priv
:
Column-level privileges.
procs_priv
:
Stored procedure and function privileges.
proxies_priv
:
Proxy-user privileges.
Each grant table contains scope columns and privilege columns:
Scope columns determine the scope of each row in the tables;
that is, the context in which the row applies. For example,
a user
table row with
Host
and User
values
of 'h1.example.net'
and
'bob'
applies to authenticating
connections made to the server from the host
h1.example.net
by a client that specifies
a user name of bob
. Similarly, a
db
table row with
Host
, User
, and
Db
column values of
'h1.example.net'
,
'bob'
and 'reports'
applies when bob
connects from the host
h1.example.net
to access the
reports
database. The
tables_priv
and
columns_priv
tables contain scope columns
indicating tables or table/column combinations to which each
row applies. The procs_priv
scope columns
indicate the stored routine to which each row applies.
Privilege columns indicate which privileges a table row grants; that is, which operations it permits to be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. Section 6.2.6, “Access Control, Stage 2: Request Verification”, describes the rules for this.
In addition, a grant table may contain columns used for purposes other than scope or privilege assessment.
The server uses the grant tables in the following manner:
The user
table scope columns determine
whether to reject or permit incoming connections. For
permitted connections, any privileges granted in the
user
table indicate the user's global
privileges. Any privileges granted in this table apply to
all databases on the server.
Because a global privilege is considered a privilege for
all databases, any global privilege
enables a user to see all database names with
SHOW DATABASES
or by
examining the INFORMATION_SCHEMA
SCHEMATA
table.
The db
table scope columns determine
which users can access which databases from which hosts. The
privilege columns determine the permitted operations. A
privilege granted at the database level applies to the
database and to all objects in the database, such as tables
and stored programs.
The tables_priv
and
columns_priv
tables are similar to the
db
table, but are more fine-grained: They
apply at the table and column levels rather than at the
database level. A privilege granted at the table level
applies to the table and to all its columns. A privilege
granted at the column level applies only to a specific
column.
The procs_priv
table applies to stored
routines (stored procedures and functions). A privilege
granted at the routine level applies only to a single
procedure or function.
The proxies_priv
table indicates which
users can act as proxies for other users and whether a user
can grant the PROXY
privilege
to other users.
The server reads the contents of the grant tables into memory
when it starts. You can tell it to reload the tables by issuing
a FLUSH PRIVILEGES
statement or
executing a mysqladmin flush-privileges or
mysqladmin reload command. Changes to the
grant tables take effect as indicated in
Section 6.2.9, “When Privilege Changes Take Effect”.
When you modify an account, it is a good idea to verify that
your changes have the intended effect. To check the privileges
for a given account, use the SHOW
GRANTS
statement. For example, to determine the
privileges that are granted to an account with user name and
host name values of bob
and
pc84.example.com
, use this statement:
SHOW GRANTS FOR 'bob'@'pc84.example.com';
To display nonprivilege properties of an account, use
SHOW CREATE USER
:
SHOW CREATE USER 'bob'@'pc84.example.com';
The server uses the user
and
db
tables in the mysql
database at both the first and second stages of access control
(see Section 6.2, “Access Control and Account Management”). The columns in the
user
and db
tables are
shown here.
Table 6.3 user and db Table Columns
Table Name | user |
db |
---|---|---|
Scope columns | Host |
Host |
User |
Db |
|
User |
||
Privilege columns | Select_priv |
Select_priv |
Insert_priv |
Insert_priv |
|
Update_priv |
Update_priv |
|
Delete_priv |
Delete_priv |
|
Index_priv |
Index_priv |
|
Alter_priv |
Alter_priv |
|
Create_priv |
Create_priv |
|
Drop_priv |
Drop_priv |
|
Grant_priv |
Grant_priv |
|
Create_view_priv |
Create_view_priv |
|
Show_view_priv |
Show_view_priv |
|
Create_routine_priv |
Create_routine_priv |
|
Alter_routine_priv |
Alter_routine_priv |
|
Execute_priv |
Execute_priv |
|
Trigger_priv |
Trigger_priv |
|
Event_priv |
Event_priv |
|
Create_tmp_table_priv |
Create_tmp_table_priv |
|
Lock_tables_priv |
Lock_tables_priv |
|
References_priv |
References_priv |
|
Reload_priv |
||
Shutdown_priv |
||
Process_priv |
||
File_priv |
||
Show_db_priv |
||
Super_priv |
||
Repl_slave_priv |
||
Repl_client_priv |
||
Create_user_priv |
||
Create_tablespace_priv |
||
Security columns | ssl_type |
|
ssl_cipher |
||
x509_issuer |
||
x509_subject |
||
plugin |
||
authentication_string |
||
password_expired |
||
password_last_changed |
||
password_lifetime |
||
account_locked |
||
Resource control columns | max_questions |
|
max_updates |
||
max_connections |
||
max_user_connections |
The user
table plugin
and
authentication_string
columns store
authentication plugin and credential information.
The server uses the plugin named in the
plugin
column of an account row to
authenticate connection attempts for the account.
The plugin
column must be nonempty. At
startup, and at runtime when FLUSH
PRIVILEGES
is executed, the server checks
user
table rows. For any row with an empty
plugin
column, the server writes a warning to
the error log of this form:
[Warning] User entry 'user_name
'@'host_name
' has an empty plugin value. The user will be ignored and no one can login with this user anymore.
To address this problem, see Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password Plugin”.
The password_expired
column permits DBAs to
expire account passwords and require users to reset their
password. The default password_expired
value
is 'N'
, but can be set to
'Y'
with the ALTER
USER
statement. After an account's password has been
expired, all operations performed by the account in subsequent
connections to the server result in an error until the user
issues an ALTER USER
statement to
establish a new account password.
Although it is possible to “reset” an expired password by setting it to its current value, it is preferable, as a matter of good policy, to choose a different password.
password_last_changed
is a
TIMESTAMP
column indicating when the password
was last changed. The value is non-NULL
only
for accounts that use MySQL built-in authentication methods
(accounts that use an authentication plugin of
mysql_native_password
or
sha256_password
). The value is
NULL
for other accounts, such as those
authenticated using an external authentication system.
password_last_changed
is updated by the
CREATE USER
,
ALTER USER
, and
SET PASSWORD
statements, and by
GRANT
statements that create an
account or change an account password.
password_lifetime
indicates the account
password lifetime, in days. If the password is past its lifetime
(assessed using the password_last_changed
column), the server considers the password expired when clients
connect using the account. A value of
N
greater than zero means that the
password must be changed every N
days. A value of 0 disables automatic password expiration. If
the value is NULL
(the default), the global
expiration policy applies, as defined by the
default_password_lifetime
system variable.
account_locked
indicates whether the account
is locked (see Section 6.2.15, “Account Locking”).
During the second stage of access control, the server performs
request verification to ensure that each client has sufficient
privileges for each request that it issues. In addition to the
user
and db
grant tables,
the server may also consult the tables_priv
and columns_priv
tables for requests that
involve tables. The latter tables provide finer privilege
control at the table and column levels. They have the columns
shown in the following table.
Table 6.4 tables_priv and columns_priv Table Columns
Table Name | tables_priv |
columns_priv |
---|---|---|
Scope columns | Host |
Host |
Db |
Db |
|
User |
User |
|
Table_name |
Table_name |
|
Column_name |
||
Privilege columns | Table_priv |
Column_priv |
Column_priv |
||
Other columns | Timestamp |
Timestamp |
Grantor |
The Timestamp
and Grantor
columns are set to the current timestamp and the
CURRENT_USER
value, respectively,
but are otherwise unused.
For verification of requests that involve stored routines, the
server may consult the procs_priv
table,
which has the columns shown in the following table.
Table 6.5 procs_priv Table Columns
Table Name | procs_priv |
---|---|
Scope columns | Host |
Db |
|
User |
|
Routine_name |
|
Routine_type |
|
Privilege columns | Proc_priv |
Other columns | Timestamp |
Grantor |
The Routine_type
column is an
ENUM
column with values of
'FUNCTION'
or 'PROCEDURE'
to indicate the type of routine the row refers to. This column
enables privileges to be granted separately for a function and a
procedure with the same name.
The Timestamp
and Grantor
columns are unused.
The proxies_priv
table records information
about proxy accounts. It has these columns:
For an account to be able to grant the
PROXY
privilege to other
accounts, it must have a row in the
proxies_priv
table with
With_grant
set to 1 and
Proxied_host
and
Proxied_user
set to indicate the account or
accounts for which the privilege can be granted. For example,
the 'root'@'localhost'
account created during
MySQL installation has a row in the
proxies_priv
table that enables granting the
PROXY
privilege for
''@''
, that is, for all users and all hosts.
This enables root
to set up proxy users, as
well as to delegate to other accounts the authority to set up
proxy users. See Section 6.2.14, “Proxy Users”.
Scope columns in the grant tables contain strings. The default value for each is the empty string. The following table shows the number of characters permitted in each column.
Table 6.6 Grant Table Scope Column Lengths
Column Name | Maximum Permitted Characters |
---|---|
Host , Proxied_host |
60 |
User , Proxied_user |
32 |
Password |
41 |
Db |
64 |
Table_name |
64 |
Column_name |
64 |
Routine_name |
64 |
Host
and Proxied_host
values are converted to lowercase before being stored in the
grant tables.
For access-checking purposes, comparisons of
User
, Proxied_user
,
Password
,
authentication_string
, Db
,
and Table_name
values are case-sensitive.
Comparisons of Host
,
Proxied_host
, Column_name
,
and Routine_name
values are not
case-sensitive.
The user
and db
tables
list each privilege in a separate column that is declared as
ENUM('N','Y') DEFAULT 'N'
. In other words,
each privilege can be disabled or enabled, with the default
being disabled.
The tables_priv
,
columns_priv
, and
procs_priv
tables declare the privilege
columns as SET
columns. Values in
these columns can contain any combination of the privileges
controlled by the table. Only those privileges listed in the
column value are enabled.
Table 6.7 Set-Type Privilege Column Values
Table Name | Column Name | Possible Set Elements |
---|---|---|
tables_priv |
Table_priv |
'Select', 'Insert', 'Update', 'Delete', 'Create', 'Drop',
'Grant', 'References', 'Index', 'Alter', 'Create View',
'Show view', 'Trigger' |
tables_priv |
Column_priv |
'Select', 'Insert', 'Update', 'References' |
columns_priv |
Column_priv |
'Select', 'Insert', 'Update', 'References' |
procs_priv |
Proc_priv |
'Execute', 'Alter Routine', 'Grant' |
Only the user
table specifies administrative
privileges, such as RELOAD
and
SHUTDOWN
. Administrative
operations are operations on the server itself and are not
database-specific, so there is no reason to list these
privileges in the other grant tables. Consequently, the server
need consult only the user
table to determine
whether a user can perform an administrative operation.
The FILE
privilege also is
specified only in the user
table. It is not
an administrative privilege as such, but a user's ability to
read or write files on the server host is independent of the
database being accessed.
MySQL account names consist of a user name and a host name, which enables creation of distinct accounts for users with the same user name who can connect from different hosts. This section describes how to write account names, including special values and wildcard rules.
In SQL statements such as CREATE
USER
, GRANT
, and
SET PASSWORD
, account names follow
these rules:
Account name syntax is
'
.
user_name
'@'host_name
'
An account name consisting only of a user name is equivalent
to
'
.
For example, user_name
'@'%''me'
is equivalent to
'me'@'%'
.
The user name and host name need not be quoted if they are
legal as unquoted identifiers. Quotes are necessary to specify
a user_name
string containing
special characters (such as space or -
), or
a host_name
string containing
special characters or wildcard characters (such as
.
or %
). For example, in
the account name 'test-user'@'%.com'
, both
the user name and host name parts require quotes.
Quote user names and host names as identifiers or as strings,
using either backticks (`
), single
quotation marks ('
), or double quotation
marks ("
). For string-quoting and
identifier-quoting guidelines, see
Section 9.1.1, “String Literals”, and
Section 9.2, “Schema Object Names”.
The user name and host name parts, if quoted, must be quoted
separately. That is, write
'me'@'localhost'
, not
'me@localhost'
. The latter is actually
equivalent to 'me@localhost'@'%'
.
A reference to the CURRENT_USER
or CURRENT_USER()
function is
equivalent to specifying the current client's user name and
host name literally.
MySQL stores account names in grant tables in the
mysql
system database using separate columns
for the user name and host name parts:
The user
table contains one row for each
account. The User
and
Host
columns store the user name and host
name. This table also indicates which global privileges the
account has.
Other grant tables indicate privileges an account has for
databases and objects within databases. These tables have
User
and Host
columns to
store the account name. Each row in these tables associates
with the account in the user
table that has
the same User
and Host
values.
For access-checking purposes, comparisons of User values are case-sensitive. Comparisons of Host values are not case-sensitive.
For additional detail about the properties of user names and host names as stored in the grant tables, such as maximum length, see Grant Table Scope Column Properties.
User names and host names have certain special values or wildcard conventions, as described following.
The user name part of an account name is either a nonblank value
that literally matches the user name for incoming connection
attempts, or a blank value (empty string) that matches any user
name. An account with a blank user name is an anonymous user. To
specify an anonymous user in SQL statements, use a quoted empty
user name part, such as ''@'localhost'
.
The host name part of an account name can take many forms, and wildcards are permitted:
A host value can be a host name or an IP address (IPv4 or
IPv6). The name 'localhost'
indicates the
local host. The IP address '127.0.0.1'
indicates the IPv4 loopback interface. The IP address
'::1'
indicates the IPv6 loopback
interface.
The %
and _
wildcard
characters are permitted in host name or IP address values.
These have the same meaning as for pattern-matching operations
performed with the LIKE
operator.
For example, a host value of '%'
matches
any host name, whereas a value of
'%.mysql.com'
matches any host in the
mysql.com
domain.
'198.51.100.%'
matches any host in the
198.51.100 class C network.
Because IP wildcard values are permitted in host values (for
example, '198.51.100.%'
to match every host
on a subnet), someone could try to exploit this capability by
naming a host 198.51.100.somewhere.com
. To
foil such attempts, MySQL does not perform matching on host
names that start with digits and a dot. For example, if a host
is named 1.2.example.com
, its name never
matches the host part of account names. An IP wildcard value
can match only IP addresses, not host names.
For a host value specified as an IPv4 address, a netmask can be given to indicate how many address bits to use for the network number. Netmask notation cannot be used for IPv6 addresses.
The syntax is
.
For example:
host_ip
/netmask
CREATE USER 'david'@'198.51.100.0/255.255.255.0';
This enables david
to connect from any
client host having an IP address
client_ip
for which the following
condition is true:
client_ip
&netmask
=host_ip
That is, for the CREATE USER
statement just shown:
client_ip
& 255.255.255.0 = 198.51.100.0
IP addresses that satisfy this condition range from
198.51.100.0
to
198.51.100.255
.
A netmask typically begins with bits set to 1, followed by bits set to 0. Examples:
198.0.0.0/255.0.0.0
: Any host on the
198 class A network
198.51.100.0/255.255.0.0
: Any host on
the 198.51 class B network
198.51.100.0/255.255.255.0
: Any host on
the 198.51.100 class C network
198.51.100.1
: Only the host with this
specific IP address
The server performs matching of host values in account names against the client host using the value returned by the system DNS resolver for the client host name or IP address. Except in the case that the account host value is specified using netmask notation, the server performs this comparison as a string match, even for an account host value given as an IP address. This means that you should specify account host values in the same format used by DNS. Here are examples of problems to watch out for:
Suppose that a host on the local network has a fully qualified
name of host1.example.com
. If DNS returns
name lookups for this host as
host1.example.com
, use that name in account
host values. If DNS returns just host1
, use
host1
instead.
If DNS returns the IP address for a given host as
198.51.100.2
, that will match an account
host value of 198.51.100.2
but not
198.051.100.2
. Similarly, it will match an
account host pattern like 198.51.100.%
but
not 198.051.100.%
.
To avoid problems like these, it is advisable to check the format in which your DNS returns host names and addresses. Use values in the same format in MySQL account names.
When you attempt to connect to a MySQL server, the server accepts or rejects the connection based on these conditions:
Your identity and whether you can verify your identity by supplying the correct password
Whether your account is locked or unlocked
The server checks credentials first, then account locking state. A failure for either step causes the server to deny access to you completely. Otherwise, the server accepts the connection, and then enters Stage 2 and waits for requests.
Credential checking is performed using the three
user
table scope columns
(Host
, User
, and
authentication_string
). Locking state is
recorded in the user
table
account_locked
column. The server accepts the
connection only if the Host
and
User
columns in some user
table row match the client host name and user name, the client
supplies the password specified in that row, and the
account_locked
value is 'N'
.
The rules for permissible Host
and
User
values are given in
Section 6.2.4, “Specifying Account Names”. Account locking can be changed
with the ALTER USER
statement.
Your identity is based on two pieces of information:
The client host from which you connect
Your MySQL user name
If the User
column value is nonblank, the user
name in an incoming connection must match exactly. If the
User
value is blank, it matches any user name.
If the user
table row that matches an incoming
connection has a blank user name, the user is considered to be an
anonymous user with no name, not a user with the name that the
client actually specified. This means that a blank user name is
used for all further access checking for the duration of the
connection (that is, during Stage 2).
The authentication_string
column can be blank.
This is not a wildcard and does not mean that any password
matches. It means that the user must connect without specifying a
password. If the server authenticates a client using a plugin, the
authentication method that the plugin implements may or may not
use the password in the authentication_string
column. In this case, it is possible that an external password is
also used to authenticate to the MySQL server.
Nonblank authentication_string
values in the
user
table represent encrypted passwords. MySQL
does not store passwords as cleartext for anyone to see. Rather,
the password supplied by a user who is attempting to connect is
encrypted (using the password hashing method implemented by the
account authentication plugin). The encrypted password then is
used during the connection process when checking whether the
password is correct. This is done without the encrypted password
ever traveling over the connection. See
Section 6.2.1, “Account User Names and Passwords”.
From MySQL's point of view, the encrypted password is the
real password, so you should never give
anyone access to it. In particular, do not give
nonadministrative users read access to tables in the
mysql
system database.
The following table shows how various combinations of
User
and Host
values in the
user
table apply to incoming connections.
User Value |
Host Value |
Permissible Connections |
---|---|---|
'fred' |
'h1.example.net' |
fred , connecting from
h1.example.net |
'' |
'h1.example.net' |
Any user, connecting from h1.example.net |
'fred' |
'%' |
fred , connecting from any host |
'' |
'%' |
Any user, connecting from any host |
'fred' |
'%.example.net' |
fred , connecting from any host in the
example.net domain |
'fred' |
'x.example.%' |
fred , connecting from
x.example.net ,
x.example.com ,
x.example.edu , and so on; this is
probably not useful |
'fred' |
'198.51.100.177' |
fred , connecting from the host with IP address
198.51.100.177 |
'fred' |
'198.51.100.%' |
fred , connecting from any host in the
198.51.100 class C subnet |
'fred' |
'198.51.100.0/255.255.255.0' |
Same as previous example |
It is possible for the client host name and user name of an
incoming connection to match more than one row in the
user
table. The preceding set of examples
demonstrates this: Several of the entries shown match a connection
from h1.example.net
by fred
.
When multiple matches are possible, the server must determine which of them to use. It resolves this issue as follows:
Whenever the server reads the user
table
into memory, it sorts the rows.
When a client attempts to connect, the server looks through the rows in sorted order.
The server uses the first row that matches the client host name and user name.
The server uses sorting rules that order rows with the
most-specific Host
values first. Literal host
names and IP addresses are the most specific. (The specificity of
a literal IP address is not affected by whether it has a netmask,
so 198.51.100.13
and
198.51.100.0/255.255.255.0
are considered
equally specific.) The pattern '%'
means
“any host” and is least specific. The empty string
''
also means “any host” but sorts
after '%'
. Rows with the same
Host
value are ordered with the most-specific
User
values first (a blank
User
value means “any user” and is
least specific). For rows with equally-specific
Host
and User
values, the
order is nondeterministic.
To see how this works, suppose that the user
table looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | % | root | ... | % | jeffrey | ... | localhost | root | ... | localhost | | ... +-----------+----------+-
When the server reads the table into memory, it sorts the rows using the rules just described. The result after sorting looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | localhost | root | ... | localhost | | ... | % | jeffrey | ... | % | root | ... +-----------+----------+-
When a client attempts to connect, the server looks through the
sorted rows and uses the first match found. For a connection from
localhost
by jeffrey
, two of
the rows from the table match: the one with
Host
and User
values of
'localhost'
and ''
, and the
one with values of '%'
and
'jeffrey'
. The 'localhost'
row appears first in sorted order, so that is the one the server
uses.
Here is another example. Suppose that the user
table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | % | jeffrey | ... | h1.example.net | | ... +----------------+----------+-
The sorted table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | h1.example.net | | ... | % | jeffrey | ... +----------------+----------+-
A connection by jeffrey
from
h1.example.net
is matched by the first row,
whereas a connection by jeffrey
from any host
is matched by the second.
It is a common misconception to think that, for a given user
name, all rows that explicitly name that user are used first
when the server attempts to find a match for the connection.
This is not true. The preceding example illustrates this, where
a connection from h1.example.net
by
jeffrey
is first matched not by the row
containing 'jeffrey'
as the
User
column value, but by the row with no
user name. As a result, jeffrey
is
authenticated as an anonymous user, even though he specified a
user name when connecting.
If you are able to connect to the server, but your privileges are
not what you expect, you probably are being authenticated as some
other account. To find out what account the server used to
authenticate you, use the
CURRENT_USER()
function. (See
Section 12.15, “Information Functions”.) It returns a value in
format that indicates the user_name
@host_name
User
and
Host
values from the matching
user
table row. Suppose that
jeffrey
connects and issues the following
query:
mysql> SELECT CURRENT_USER();
+----------------+
| CURRENT_USER() |
+----------------+
| @localhost |
+----------------+
The result shown here indicates that the matching
user
table row had a blank
User
column value. In other words, the server
is treating jeffrey
as an anonymous user.
Another way to diagnose authentication problems is to print out
the user
table and sort it by hand to see where
the first match is being made.
After you establish a connection, the server enters Stage 2 of
access control. For each request that you issue through that
connection, the server determines what operation you want to
perform, then checks whether you have sufficient privileges to do
so. This is where the privilege columns in the grant tables come
into play. These privileges can come from any of the
user
, db
,
tables_priv
, columns_priv
,
or procs_priv
tables. (You may find it helpful
to refer to Section 6.2.3, “Grant Tables”, which lists the
columns present in each grant table.)
The user
table grants global privileges. The
user
table row for an account indicates the
account privileges that apply on a global basis no matter what the
default database is. For example, if the user
table grants you the DELETE
privilege, you can delete rows from any table in any database on
the server host. It is wise to grant privileges in the
user
table only to people who need them, such
as database administrators. For other users, leave all privileges
in the user
table set to 'N'
and grant privileges at more specific levels only (for particular
databases, tables, columns, or routines).
The db
table grants database-specific
privileges. Values in the scope columns of this table can take the
following forms:
A blank User
value matches the anonymous
user. A nonblank value matches literally; there are no
wildcards in user names.
The wildcard characters %
and
_
can be used in the
Host
and Db
columns.
These have the same meaning as for pattern-matching operations
performed with the LIKE
operator.
If you want to use either character literally when granting
privileges, you must escape it with a backslash. For example,
to include the underscore character (_
) as
part of a database name, specify it as \_
in the GRANT
statement.
A '%'
or blank Host
value means “any host.”
A '%'
or blank Db
value
means “any database.”
The server reads the db
table into memory and
sorts it at the same time that it reads the
user
table. The server sorts the
db
table based on the Host
,
Db
, and User
scope columns.
As with the user
table, sorting puts the
most-specific values first and least-specific values last, and
when the server looks for matching rows, it uses the first match
that it finds.
The tables_priv
,
columns_priv
, and procs_priv
tables grant table-specific, column-specific, and routine-specific
privileges. Values in the scope columns of these tables can take
the following forms:
The wildcard characters %
and
_
can be used in the
Host
column. These have the same meaning as
for pattern-matching operations performed with the
LIKE
operator.
A '%'
or blank Host
value means “any host.”
The Db
, Table_name
,
Column_name
, and
Routine_name
columns cannot contain
wildcards or be blank.
The server sorts the tables_priv
,
columns_priv
, and procs_priv
tables based on the Host
,
Db
, and User
columns. This
is similar to db
table sorting, but simpler
because only the Host
column can contain
wildcards.
The server uses the sorted tables to verify each request that it
receives. For requests that require administrative privileges such
as SHUTDOWN
or
RELOAD
, the server checks only the
user
table row because that is the only table
that specifies administrative privileges. The server grants access
if the row permits the requested operation and denies access
otherwise. For example, if you want to execute mysqladmin
shutdown but your user
table row does
not grant the SHUTDOWN
privilege to
you, the server denies access without even checking the
db
table. (The latter table contains no
Shutdown_priv
column, so there is no need to
check it.)
For database-related requests
(INSERT
,
UPDATE
, and so on), the server
first checks the user's global privileges in the
user
table row. If the row permits the
requested operation, access is granted. If the global privileges
in the user
table are insufficient, the server
determines the user's database-specific privileges from the
db
table:
The server looks in the db
table for a match on
the Host
, Db
, and
User
columns. The Host
and
User
columns are matched to the connecting
user's host name and MySQL user name. The Db
column is matched to the database that the user wants to access.
If there is no row for the Host
and
User
, access is denied.
After determining the database-specific privileges granted by the
db
table rows, the server adds them to the
global privileges granted by the user
table. If
the result permits the requested operation, access is granted.
Otherwise, the server successively checks the user's table and
column privileges in the tables_priv
and
columns_priv
tables, adds those to the user's
privileges, and permits or denies access based on the result. For
stored-routine operations, the server uses the
procs_priv
table rather than
tables_priv
and
columns_priv
.
Expressed in boolean terms, the preceding description of how a user's privileges are calculated may be summarized like this:
global privileges OR (database privileges AND host privileges) OR table privileges OR column privileges OR routine privileges
It may not be apparent why, if the global privileges are initially
found to be insufficient for the requested operation, the server
adds those privileges to the database, table, and column
privileges later. The reason is that a request might require more
than one type of privilege. For example, if you execute an
INSERT INTO ...
SELECT
statement, you need both the
INSERT
and the
SELECT
privileges. Your privileges
might be such that the user
table row grants
one privilege global and the db
table row
grants the other specifically for the relevant database. In this
case, you have the necessary privileges to perform the request,
but the server cannot tell that from either your global or
database privileges alone. It must make an access-control decision
based on the combined privileges.
To manage MySQL accounts, use the SQL statements intended for that purpose:
CREATE USER
and
DROP USER
create and remove
accounts.
GRANT
and
REVOKE
assign privileges to and
revoke privileges from accounts.
SHOW GRANTS
displays account
privilege assignments.
Account-management statements cause the server to make appropriate modifications to the underlying grant tables, which are discussed in Section 6.2.3, “Grant Tables”.
Direct modification of grant tables using statements such as
INSERT
,
UPDATE
, or
DELETE
is discouraged and done at
your own risk. The server is free to ignore rows that become
malformed as a result of such modifications.
As of MySQL 5.7.18, for any operation that modifies a grant table, the server checks whether the table has the expected structure and produces an error if not. mysql_upgrade must be run to update the tables to the expected structure.
Another option for creating accounts is to use the GUI tool
MySQL Workbench. Also, several third-party programs offer capabilities
for MySQL account administration. phpMyAdmin
is
one such program.
This section discusses the following topics:
For additional information about the statements discussed here, see Section 13.7.1, “Account Management Statements”.
The following examples show how to use the
mysql client program to set up new accounts.
These examples assume that the MySQL root
account has the CREATE USER
privilege and all privileges that it grants to other accounts.
At the command line, connect to the server as the MySQL
root
user, supplying the appropriate password
at the password prompt:
shell>mysql -u root -p
Enter password:(enter root password here)
After connecting to the server, you can add new accounts. The
following example uses CREATE USER
and GRANT
statements
to set up four accounts (where you see
'
,
substitute an appropriate password):
password
'
CREATE USER 'finley'@'localhost' IDENTIFIED BY 'password
'; GRANT ALL ON *.* TO 'finley'@'localhost' WITH GRANT OPTION; CREATE USER 'finley'@'%.example.com' IDENTIFIED BY 'password
'; GRANT ALL ON *.* TO 'finley'@'%.example.com' WITH GRANT OPTION; CREATE USER 'admin'@'localhost' IDENTIFIED BY 'password
'; GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost'; CREATE USER 'dummy'@'localhost';
The accounts created by those statements have the following properties:
Two accounts have a user name of finley
.
Both are superuser accounts with full global privileges to
do anything. The 'finley'@'localhost'
account can be used only when connecting from the local
host. The 'finley'@'%.example.com'
account uses the '%'
wildcard in the host
part, so it can be used to connect from any host in the
example.com
domain.
The 'finley'@'localhost'
account is
necessary if there is an anonymous-user account for
localhost
. Without the
'finley'@'localhost'
account, that
anonymous-user account takes precedence when
finley
connects from the local host and
finley
is treated as an anonymous user.
The reason for this is that the anonymous-user account has a
more specific Host
column value than the
'finley'@'%'
account and thus comes
earlier in the user
table sort order.
(For information about user
table
sorting, see Section 6.2.5, “Access Control, Stage 1: Connection Verification”.)
The 'admin'@'localhost'
account can be
used only by admin
to connect from the
local host. It is granted the global
RELOAD
and
PROCESS
administrative
privileges. These privileges enable the
admin
user to execute the
mysqladmin reload, mysqladmin
refresh, and mysqladmin
flush-xxx
commands, as
well as mysqladmin processlist . No
privileges are granted for accessing any databases. You
could add such privileges using
GRANT
statements.
The 'dummy'@'localhost'
account has no
password (which is insecure and not recommended). This
account can be used only to connect from the local host. No
privileges are granted. It is assumed that you will grant
specific privileges to the account using
GRANT
statements.
The previous example grants privileges at the global level. The
next example creates three accounts and grants them access at
lower levels; that is, to specific databases or objects within
databases. Each account has a user name of
custom
, but the host name parts differ:
CREATE USER 'custom'@'localhost' IDENTIFIED BY 'password
'; GRANT ALL ON bankaccount.* TO 'custom'@'localhost'; CREATE USER 'custom'@'host47.example.com' IDENTIFIED BY 'password
'; GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON expenses.* TO 'custom'@'host47.example.com'; CREATE USER 'custom'@'%.example.com' IDENTIFIED BY 'password
'; GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON customer.addresses TO 'custom'@'%.example.com';
The three accounts can be used as follows:
The 'custom'@'localhost'
account has all
database-level privileges to access the
bankaccount
database. The account can be
used to connect to the server only from the local host.
The 'custom'@'host47.example.com'
account
has specific database-level privileges to access the
expenses
database. The account can be
used to connect to the server only from the host
host47.example.com
.
The 'custom'@'%.example.com'
account has
specific table-level privileges to access the
addresses
table in the
customer
database, from any host in the
example.com
domain. The account can be
used to connect to the server from all machines in the
domain due to use of the %
wildcard
character in the host part of the account name.
To see the privileges for an account, use
SHOW GRANTS
:
mysql> SHOW GRANTS FOR 'admin'@'localhost';
+-----------------------------------------------------+
| Grants for admin@localhost |
+-----------------------------------------------------+
| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' |
+-----------------------------------------------------+
To see nonprivilege properties for an account, use
SHOW CREATE USER
:
mysql> SHOW CREATE USER 'admin'@'localhost'\G
*************************** 1. row ***************************
CREATE USER for admin@localhost: CREATE USER 'admin'@'localhost'
IDENTIFIED WITH 'mysql_native_password'
AS '*67ACDEBDAB923990001F0FFB017EB8ED41861105'
REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK
To revoke account privileges, use the
REVOKE
statement. Privileges can
be revoked at different levels, just as they can be granted at
different levels.
Revoke global privileges:
REVOKE ALL ON *.* FROM 'finley'@'%.example.com'; REVOKE RELOAD ON *.* FROM 'admin'@'localhost';
Revoke database-level privileges:
REVOKE CREATE,DROP ON expenses.* FROM 'custom'@'host47.example.com';
Revoke table-level privileges:
REVOKE INSERT,UPDATE,DELETE ON customer.addresses FROM 'custom'@'%.example.com';
To check the effect of privilege revocation, use
SHOW GRANTS
:
mysql> SHOW GRANTS FOR 'admin'@'localhost';
+---------------------------------------------+
| Grants for admin@localhost |
+---------------------------------------------+
| GRANT PROCESS ON *.* TO 'admin'@'localhost' |
+---------------------------------------------+
To remove an account, use the DROP
USER
statement. For example, to drop some of the
accounts created previously:
DROP USER 'finley'@'localhost'; DROP USER 'finley'@'%.example.com'; DROP USER 'admin'@'localhost'; DROP USER 'dummy'@'localhost';
One part of the MySQL installation process is data directory initialization (see Section 2.10.1, “Initializing the Data Directory”). During data directory initialization, MySQL creates user accounts that should be considered reserved:
'root'@'localhost
: Used for administrative
purposes. This account has all privileges and can perform any
operation.
Strictly speaking, this account name is not reserved, in the
sense that some installations rename the
root
account to something else to avoid
exposing a highly privileged account with a well-known name.
'mysql.sys'@'localhost'
: Used as the
DEFINER
for
sys
schema objects. Use of the
mysql.sys
account avoids problems that
occur if a DBA renames or removes the root
account. This account is locked so that it cannot be used for
client connections.
'mysql.session'@'localhost'
: Used
internally by plugins to access the server. This account is
locked so that it cannot be used for client connections.
If the mysqld server is started without the
--skip-grant-tables
option, it
reads all grant table contents into memory during its startup
sequence. The in-memory tables become effective for access control
at that point.
If you modify the grant tables indirectly using an
account-management statement, the server notices these changes and
loads the grant tables into memory again immediately.
Account-management statements are described in
Section 13.7.1, “Account Management Statements”. Examples include
GRANT
,
REVOKE
, SET
PASSWORD
, and RENAME
USER
.
If you modify the grant tables directly using statements such as
INSERT
,
UPDATE
, or
DELETE
(which is not recommended),
the changes have no effect on privilege checking until you either
tell the server to reload the tables or restart it. Thus, if you
change the grant tables directly but forget to reload them, the
changes have no effect until you restart the
server. This may leave you wondering why your changes seem to make
no difference!
To tell the server to reload the grant tables, perform a
flush-privileges operation. This can be done by issuing a
FLUSH PRIVILEGES
statement or by
executing a mysqladmin flush-privileges or
mysqladmin reload command.
A grant table reload affects privileges for each existing client session as follows:
Table and column privilege changes take effect with the client's next request.
Database privilege changes take effect the next time the
client executes a USE
statement.
db_name
Client applications may cache the database name; thus, this effect may not be visible to them without actually changing to a different database.
Global privileges and passwords are unaffected for a connected client. These changes take effect only in sessions for subsequent connections.
If the server is started with the
--skip-grant-tables
option, it does
not read the grant tables or implement any access control. Any
user can connect and perform any operation, which is
insecure. To cause a server thus started to read the
tables and enable access checking, flush the privileges.
Required credentials for clients that connect to the MySQL server can include a password. This section describes how to assign passwords for MySQL accounts.
MySQL stores credentials in the user
table in
the mysql
system database. Operations that
assign or modify passwords are permitted only to users with the
CREATE USER
privilege, or,
alternatively, privileges for the mysql
database (INSERT
privilege to
create new accounts, UPDATE
privilege to modify existing accounts). If the
read_only
system variable is
enabled, use of account-modification statements such as
CREATE USER
or
ALTER USER
additionally requires
the SUPER
privilege.
The discussion here summarizes syntax only for the most common password-assignment statements. For complete details on other possibilities, see Section 13.7.1.2, “CREATE USER Statement”, Section 13.7.1.1, “ALTER USER Statement”, Section 13.7.1.4, “GRANT Statement”, and Section 13.7.1.7, “SET PASSWORD Statement”.
MySQL uses plugins to perform client authentication; see
Section 6.2.13, “Pluggable Authentication”. In password-assigning
statements, the authentication plugin associated with an account
performs any hashing required of a cleartext password specified.
This enables MySQL to obfuscate passwords prior to storing them in
the mysql.user
system table. For the statements
described here, MySQL automatically hashes the password specified.
There are also syntax for CREATE
USER
and ALTER USER
that
permits hashed values to be specified literally. For details, see
the descriptions of those statements.
To assign a password when you create a new account, use
CREATE USER
and include an
IDENTIFIED BY
clause:
CREATE USER 'jeffrey'@'localhost' IDENTIFIED BY 'password
';
CREATE USER
also supports syntax
for specifying the account authentication plugin. See
Section 13.7.1.2, “CREATE USER Statement”.
To assign or change a password for an existing account, use the
ALTER USER
statement with an
IDENTIFIED BY
clause:
ALTER USER 'jeffrey'@'localhost' IDENTIFIED BY 'password
';
If you are not connected as an anonymous user, you can change your own password without naming your own account literally:
ALTER USER USER() IDENTIFIED BY 'password
';
To change an account password from the command line, use the mysqladmin command:
mysqladmin -uuser_name
-hhost_name
password "password
"
The account for which this command sets the password is the one
with a row in the mysql.user
system table that
matches user_name
in the
User
column and the client host from
which you connect in the Host
column.
Setting a password using mysqladmin should be considered insecure. On some systems, your password becomes visible to system status programs such as ps that may be invoked by other users to display command lines. MySQL clients typically overwrite the command-line password argument with zeros during their initialization sequence. However, there is still a brief interval during which the value is visible. Also, on some systems this overwriting strategy is ineffective and the password remains visible to ps. (SystemV Unix systems and perhaps others are subject to this problem.)
If you are using MySQL Replication, be aware that, currently, a
password used by a replication slave as part of a
CHANGE MASTER TO
statement is
effectively limited to 32 characters in length; if the password is
longer, any excess characters are truncated. This is not due to
any limit imposed by the MySQL Server generally, but rather is an
issue specific to MySQL Replication. (For more information, see
Bug #43439.)
MySQL enables database administrators to expire account passwords manually, and to establish a policy for automatic password expiration. Expiration policy can be established globally, and individual accounts can be set to either defer to the global policy or override the global policy with specific per-account behavior.
Some authentication plugins store account credentials internally
to MySQL, in the mysql.user
system table:
mysql_native_password
sha256_password
The discussion in this section applies to such authentication plugins because the password-management capabilities described here are based on internal credentials storage handled by MySQL itself.
Other authentication plugins store account credentials externally to MySQL. For accounts that use plugins that perform authentication against an external credentials system, password management must be handled externally against that system as well.
For information about individual authentication plugins, see Section 6.4.1, “Authentication Plugins”.
To expire an account password manually, use the
ALTER USER
statement:
ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE;
This operation marks the password expired in the corresponding
mysql.user
system table row.
Password expiration according to policy is automatic and is
based on password age, which for a given account is assessed
from the date and time of its most recent password change. The
mysql.user
system table indicates for each
account when its password was last changed, and the server
automatically treats the password as expired at client
connection time if its age is greater than its permitted
lifetime. This works with no explicit manual password
expiration.
To establish automatic password-expiration policy globally, use
the default_password_lifetime
system variable. Its default value is 0, which disables
automatic password expiration. If the value of
default_password_lifetime
is a
positive integer N
, it indicates the
permitted password lifetime, such that passwords must be changed
every N
days.
Prior to 5.7.11, the default
default_password_lifetime
value is 360 (passwords must be changed approximately once per
year). For such versions, be aware that, if you make no
changes to the
default_password_lifetime
variable or to individual user accounts, each user password
expires after 360 days and the account starts running in
restricted mode. Clients that connect to the server using the
account then get an error indicating that the password must be
changed: ERROR 1820 (HY000): You must reset your
password using ALTER USER statement before executing this
statement.
However, this is easy to miss for clients that automatically connect to the server, such as connections made from scripts. To avoid having such clients suddenly stop working due to a password expiring, make sure to change the password expiration settings for those clients, like this:
ALTER USER 'script'@'localhost' PASSWORD EXPIRE NEVER
Alternatively, set the
default_password_lifetime
variable to 0
, thus disabling automatic
password expiration for all users.
Examples:
To establish a global policy that passwords have a lifetime
of approximately six months, start the server with these
lines in a server my.cnf
file:
[mysqld] default_password_lifetime=180
To establish a global policy such that passwords never
expire, set
default_password_lifetime
to 0:
[mysqld] default_password_lifetime=0
default_password_lifetime
can also be changed at runtime:
SET GLOBAL default_password_lifetime = 180; SET GLOBAL default_password_lifetime = 0;
The global password-expiration policy applies to all accounts
that have not been set to override it. To establish policy for
individual accounts, use the PASSWORD EXPIRE
options of the CREATE USER
and
ALTER USER
statements. See
Section 13.7.1.2, “CREATE USER Statement”, and Section 13.7.1.1, “ALTER USER Statement”.
Example account-specific statements:
Require the password to be changed every 90 days:
CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 90 DAY; ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE INTERVAL 90 DAY;
This expiration option overrides the global policy for all accounts named by the statement.
Disable password expiration:
CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER; ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE NEVER;
This expiration option overrides the global policy for all accounts named by the statement.
Defer to the global expiration policy for all accounts named by the statement:
CREATE USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT; ALTER USER 'jeffrey'@'localhost' PASSWORD EXPIRE DEFAULT;
When a client successfully connects, the server determines whether the account password has expired:
The server checks whether the password has been manually expired.
Otherwise, the server checks whether the password age is greater than its permitted lifetime according to the automatic password expiration policy. If so, the server considers the password expired.
If the password is expired (whether manually or automatically), the server either disconnects the client or restricts the operations permitted to it (see Section 6.2.12, “Server Handling of Expired Passwords”). Operations performed by a restricted client result in an error until the user establishes a new account password:
mysql>SELECT 1;
ERROR 1820 (HY000): You must reset your password using ALTER USER statement before executing this statement. mysql>ALTER USER USER() IDENTIFIED BY '
Query OK, 0 rows affected (0.01 sec) mysql>password
';SELECT 1;
+---+ | 1 | +---+ | 1 | +---+ 1 row in set (0.00 sec)
This restricted mode of operation permits
SET
statements, which is useful before MySQL 5.7.6 if
SET PASSWORD
must be used instead
of ALTER USER
and the account
password has a hashing format that requires
old_passwords
to be set to a
value different from its default.
After the client resets the password, the server restores normal access for the session, as well as for subsequent connections that use the account. It is also possible for an administrative user to reset the account password, but any existing restricted sessions for that account remain restricted. A client using the account must disconnect and reconnect before statements can be executed successfully.
Although it is possible to “reset” an expired password by setting it to its current value, it is preferable, as a matter of good policy, to choose a different password.
MySQL provides password-expiration capability, which enables database administrators to require that users reset their password. Passwords can be expired manually, and on the basis of a policy for automatic expiration (see Section 6.2.11, “Password Management”).
The ALTER USER
statement enables
account password expiration. For example:
ALTER USER 'myuser'@'localhost' PASSWORD EXPIRE;
For each connection that uses an account with an expired password, the server either disconnects the client or restricts the client to “sandbox mode,” in which the server permits the client to perform only those operations necessary to reset the expired password. Which action is taken by the server depends on both client and server settings, as discussed later.
If the server disconnects the client, it returns an
ER_MUST_CHANGE_PASSWORD_LOGIN
error:
shell>mysql -u myuser -p
Password:******
ERROR 1862 (HY000): Your password has expired. To log in you must change it using a client that supports expired passwords.
If the server restricts the client to sandbox mode, these operations are permitted within the client session:
The client can reset the account password with
ALTER USER
or
SET PASSWORD
. After that has
been done, the server restores normal access for the session,
as well as for subsequent connections that use the account.
Although it is possible to “reset” an expired password by setting it to its current value, it is preferable, as a matter of good policy, to choose a different password.
The client can use the
SET
statement, which is useful before MySQL 5.7.6 if
SET PASSWORD
must be used
instead of ALTER USER
and the
account uses an authentication plugin for which the
old_passwords
system variable
must first be set to a nondefault value to perform password
hashing in a specific way.
For any operation not permitted within the session, the server
returns an ER_MUST_CHANGE_PASSWORD
error:
mysql>USE performance_schema;
ERROR 1820 (HY000): You must reset your password using ALTER USER statement before executing this statement. mysql>SELECT 1;
ERROR 1820 (HY000): You must reset your password using ALTER USER statement before executing this statement.
That is what normally happens for interactive invocations of the mysql client because by default such invocations are put in sandbox mode. To resume normal functioning, select a new password.
For noninteractive invocations of the mysql
client (for example, in batch mode), the server normally
disconnects the client if the password is expired. To permit
noninteractive mysql invocations to stay
connected so that the password can be changed (using the
statements permitted in sandbox mode), add the
--connect-expired-password
option to
the mysql command.
As mentioned previously, whether the server disconnects an expired-password client or restricts it to sandbox mode depends on a combination of client and server settings. The following discussion describes the relevant settings and how they interact.
This discussion applies only for accounts with expired passwords. If a client connects using a nonexpired password, the server handles the client normally.
On the client side, a given client indicates whether it can handle sandbox mode for expired passwords. For clients that use the C client library, there are two ways to do this:
Pass the
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
flag
to mysql_options()
prior to
connecting:
my_bool arg = 1; mysql_options(mysql, MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, &arg);
This is the technique used within the mysql
client, which enables
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
if
invoked interactively or with the
--connect-expired-password
option.
Pass the
CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS
flag to
mysql_real_connect()
at
connect time:
MYSQL mysql; mysql_init(&mysql); if (!mysql_real_connect(&mysql, host, user, password, db, port, unix_socket, CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS)) { ... handle error ... }
Other MySQL Connectors have their own conventions for indicating readiness to handle sandbox mode. See the documentation for the Connector in which you are interested.
On the server side, if a client indicates that it can handle expired passwords, the server puts it in sandbox mode.
If a client does not indicate that it can handle expired passwords
(or uses an older version of the client library that cannot so
indicate), the server action depends on the value of the
disconnect_on_expired_password
system variable:
If
disconnect_on_expired_password
is enabled (the default), the server disconnects the client
with an
ER_MUST_CHANGE_PASSWORD_LOGIN
error.
If
disconnect_on_expired_password
is disabled, the server puts the client in sandbox mode.
When a client connects to the MySQL server, the server uses the
user name provided by the client and the client host to select the
appropriate account row from the mysql.user
system table. The server then authenticates the client,
determining from the account row which authentication plugin
applies to the client:
If the server cannot find the plugin, an error occurs and the connection attempt is rejected.
Otherwise, the server invokes that plugin to authenticate the user, and the plugin returns a status to the server indicating whether the user provided the correct password and is permitted to connect.
Pluggable authentication enables these important capabilities:
Choice of authentication methods. Pluggable authentication makes it easy for DBAs to choose and change the authentication method used for individual MySQL accounts.
External authentication.
Pluggable authentication makes it possible for clients to
connect to the MySQL server with credentials appropriate for
authentication methods that store credentials elsewhere than
in the mysql.user
system table. For
example, plugins can be created to use external
authentication methods such as PAM, Windows login IDs, LDAP,
or Kerberos.
Proxy users: If a user is permitted to connect, an authentication plugin can return to the server a user name different from the name of the connecting user, to indicate that the connecting user is a proxy for another user (the proxied user). While the connection lasts, the proxy user is treated, for purposes of access control, as having the privileges of the proxied user. In effect, one user impersonates another. For more information, see Section 6.2.14, “Proxy Users”.
If you start the server with the
--skip-grant-tables
option,
authentication plugins are not used even if loaded because the
server performs no client authentication and permits any client
to connect. Because this is insecure, you might want to use
--skip-grant-tables
in
conjunction with enabling the
skip_networking
system variable
to prevent remote clients from connecting.
MySQL 5.7 provides these authentication plugins:
Plugins that perform native authentication; that is,
authentication based on the password hashing methods in use
from before the introduction of pluggable authentication in
MySQL. The mysql_native_password
plugin
implements authentication based on the native password
hashing method. The mysql_old_password
plugin implements native authentication based on the older
(pre-4.1) password hashing method (and is deprecated and
removed in MySQL 5.7.5). See
Section 6.4.1.1, “Native Pluggable Authentication”, and
Section 6.4.1.2, “Old Native Pluggable Authentication”.
Plugins that perform authentication using SHA-256 password hashing. This is stronger encryption than that available with native authentication. See Section 6.4.1.5, “SHA-256 Pluggable Authentication”, and Section 6.4.1.4, “Caching SHA-2 Pluggable Authentication”.
A client-side plugin that sends the password to the server without hashing or encryption. This plugin is used in conjunction with server-side plugins that require access to the password exactly as provided by the client user. See Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”.
A plugin that performs external authentication using PAM (Pluggable Authentication Modules), enabling MySQL Server to use PAM to authenticate MySQL users. This plugin supports proxy users as well. See Section 6.4.1.7, “PAM Pluggable Authentication”.
A plugin that performs external authentication on Windows, enabling MySQL Server to use native Windows services to authenticate client connections. Users who have logged in to Windows can connect from MySQL client programs to the server based on the information in their environment without specifying an additional password. This plugin supports proxy users as well. See Section 6.4.1.8, “Windows Pluggable Authentication”.
Plugins that perform authentication using LDAP (Lightweight Directory Access Protocol) to authenticate MySQL users by accessing directory services such as X.500. These plugins support proxy users as well. See Section 6.4.1.9, “LDAP Pluggable Authentication”.
A plugin that prevents all client connections to any account that uses it. Use cases for this plugin include proxied accounts that should never permit direct login but are accessed only through proxy accounts and accounts that must be able to execute stored programs and views with elevated privileges without exposing those privileges to ordinary users. See Section 6.4.1.10, “No-Login Pluggable Authentication”.
A plugin that authenticates clients that connect from the local host through the Unix socket file. See Section 6.4.1.11, “Socket Peer-Credential Pluggable Authentication”.
A test plugin that checks account credentials and logs success or failure to the server error log. This plugin is intended for testing and development purposes, and as an example of how to write an authentication plugin. See Section 6.4.1.12, “Test Pluggable Authentication”.
For information about current restrictions on the use of pluggable authentication, including which connectors support which plugins, see Restrictions on Pluggable Authentication.
Third-party connector developers should read that section to determine the extent to which a connector can take advantage of pluggable authentication capabilities and what steps to take to become more compliant.
If you are interested in writing your own authentication plugins, see Section 28.2.4.9, “Writing Authentication Plugins”.
This section provides general instructions for installing and using authentication plugins. For instructions specific to a given plugin, see the section that describes that plugin under Section 6.4.1, “Authentication Plugins”.
In general, pluggable authentication uses a pair of corresponding plugins on the server and client sides, so you use a given authentication method like this:
If necessary, install the plugin library or libraries containing the appropriate plugins. On the server host, install the library containing the server-side plugin, so that the server can use it to authenticate client connections. Similarly, on each client host, install the library containing the client-side plugin for use by client programs. Authentication plugins that are built in need not be installed.
For each MySQL account that you create, specify the
appropriate server-side plugin to use for authentication. If
the account is to use the default authentication plugin, the
account-creation statement need not specify the plugin
explicitly. The
default_authentication_plugin
system variable configures the default authentication
plugin.
When a client connects, the server-side plugin tells the client program which client-side plugin to use for authentication.
In the case that an account uses an authentication method that is the default for both the server and the client program, the server need not communicate to the client which client-side plugin to use, and a round trip in client/server negotiation can be avoided. This is true for accounts that use native MySQL authentication.
For standard MySQL clients such as mysql and
mysqladmin, the
--default-auth=
option can be specified on the command line as a hint about
which client-side plugin the program can expect to use, although
the server will override this if the server-side plugin
associated with the user account requires a different
client-side plugin.
plugin_name
If the client program does not find the client-side plugin
library file, specify a
--plugin-dir=
option to indicate the plugin library directory location.
dir_name
The first part of this section describes general restrictions on the applicability of the pluggable authentication framework described at Section 6.2.13, “Pluggable Authentication”. The second part describes how third-party connector developers can determine the extent to which a connector can take advantage of pluggable authentication capabilities and what steps to take to become more compliant.
The term “native authentication” used here refers
to authentication against passwords stored in the
mysql.user
system table. This is the same
authentication method provided by older MySQL servers, before
pluggable authentication was implemented. “Windows native
authentication” refers to authentication using the
credentials of a user who has already logged in to Windows, as
implemented by the Windows Native Authentication plugin
(“Windows plugin” for short).
Connector/C++: Clients that use this connector can connect to the server only through accounts that use native authentication.
Exception: A connector supports pluggable authentication if
it was built to link to libmysqlclient
dynamically (rather than statically) and it loads the
current version of libmysqlclient
if that
version is installed, or if the connector is recompiled from
source to link against the current
libmysqlclient
.
Connector/NET: Clients that use Connector/NET can connect to the server through accounts that use native authentication or Windows native authentication.
Connector/PHP: Clients that
use this connector can connect to the server only through
accounts that use native authentication, when compiled using
the MySQL native driver for PHP
(mysqlnd
).
Windows native authentication: Connecting through an account that uses the Windows plugin requires Windows Domain setup. Without it, NTLM authentication is used and then only local connections are possible; that is, the client and server must run on the same computer.
Proxy users: Proxy user
support is available to the extent that clients can connect
through accounts authenticated with plugins that implement
proxy user capability (that is, plugins that can return a
user name different from that of the connecting user). For
example, the PAM and Windows plugins support proxy users.
The mysql_native_password
and
sha256_password
authentication plugins do
not support proxy users by default, but can be configured to
do so; see
Server Support for Proxy User Mapping.
Replication: Replication
slaves can employ not only master accounts using native
authentication, but can also connect through master accounts
that use nonnative authentication if the required
client-side plugin is available. If the plugin is built into
libmysqlclient
, it is available by
default. Otherwise, the plugin must be installed on the
slave side in the directory named by the slave
plugin_dir
system variable.
FEDERATED
tables: A FEDERATED
table can access the remote table only through accounts on
the remote server that use native authentication.
Third-party connector developers can use the following guidelines to determine readiness of a connector to take advantage of pluggable authentication capabilities and what steps to take to become more compliant:
An existing connector to which no changes have been made uses native authentication and clients that use the connector can connect to the server only through accounts that use native authentication. However, you should test the connector against a recent version of the server to verify that such connections still work without problem.
Exception: A connector might work with pluggable
authentication without any changes if it links to
libmysqlclient
dynamically (rather than
statically) and it loads the current version of
libmysqlclient
if that version is
installed.
To take advantage of pluggable authentication capabilities,
a connector that is libmysqlclient
-based
should be relinked against the current version of
libmysqlclient
. This enables the
connector to support connections though accounts that
require client-side plugins now built into
libmysqlclient
(such as the cleartext
plugin needed for PAM authentication and the Windows plugin
needed for Windows native authentication). Linking with a
current libmysqlclient
also enables the
connector to access client-side plugins installed in the
default MySQL plugin directory (typically the directory
named by the default value of the local server's
plugin_dir
system
variable).
If a connector links to libmysqlclient
dynamically, it must be ensured that the newer version of
libmysqlclient
is installed on the client
host and that the connector loads it at runtime.
Another way for a connector to support a given authentication method is to implement it directly in the client/server protocol. Connector/NET uses this approach to provide support for Windows native authentication.
If a connector should be able to load client-side plugins
from a directory different from the default plugin
directory, it must implement some means for client users to
specify the directory. Possibilities for this include a
command-line option or environment variable from which the
connector can obtain the directory name. Standard MySQL
client programs such as mysql and
mysqladmin implement a
--plugin-dir
option. See also
Section 27.7.13, “C API Client Plugin Functions”.
Proxy user support by a connector depends, as described earlier in this section, on whether the authentication methods that it supports permit proxy users.
The MySQL server authenticates client connections using authentication plugins. The plugin that authenticates a given connection may request that the connecting (external) user be treated as a different user for privilege-checking purposes. This enables the external user to be a proxy for the second user; that is, to assume the privileges of the second user:
The external user is a “proxy user” (a user who can impersonate or become known as another user).
The second user is a “proxied user” (a user whose identity and privileges can be assumed by a proxy user).
This section describes how the proxy user capability works. For general information about authentication plugins, see Section 6.2.13, “Pluggable Authentication”. For information about specific plugins, see Section 6.4.1, “Authentication Plugins”. For information about writing authentication plugins that support proxy users, see Section 28.2.4.9.4, “Implementing Proxy User Support in Authentication Plugins”.
For proxying to occur for a given authentication plugin, these conditions must be satisfied:
Proxying must be supported, either by the plugin itself, or by the MySQL server on behalf of the plugin. In the latter case, server support may need to be enabled explicitly; see Server Support for Proxy User Mapping.
The account for the external proxy user must be set up to be
authenticated by the plugin. Use the
CREATE USER
statement to
associate an account with an authentication plugin, or
ALTER USER
to change its
plugin.
The account for the proxied user must exist and be granted
the privileges to be assumed by the proxy user. Use the
CREATE USER
and
GRANT
statements for this.
Normally, the proxied user is configured so that it can be used only in proxying scenaries and not for direct logins.
The proxy user account must have the
PROXY
privilege for the
proxied account. Use the
GRANT
statement for this.
For a client connecting to the proxy account to be treated as a proxy user, the authentication plugin must return a user name different from the client user name, to indicate the user name of the proxied account that defines the privileges to be assumed by the proxy user.
Alternatively, for plugins that are provided proxy mapping
by the server, the proxied user is determined from the
PROXY
privilege held by the
proxy user.
The proxy mechanism permits mapping only the external client user name to the proxied user name. There is no provision for mapping host names:
When a client connects to the server, the server determines the proper account based on the user name passed by the client program and the host from which the client connects.
If that account is a proxy account, the server attempts to determine the appropriate proxied account by finding a match for a proxied account using the user name returned by the authentication plugin and the host name of the proxy account. The host name in the proxied account is ignored.
Consider the following account definitions:
-- create proxy account
CREATE USER 'employee_ext'@'localhost'
IDENTIFIED WITH my_auth_plugin
AS 'my_auth_string
';
-- create proxied account and grant its privileges;
-- use mysql_no_login plugin to prevent direct login
CREATE USER 'employee'@'localhost'
IDENTIFIED WITH mysql_no_login;
GRANT ALL
ON employees.*
TO 'employee'@'localhost';
-- grant to proxy account the
-- PROXY privilege for proxied account
GRANT PROXY
ON 'employee'@'localhost'
TO 'employee_ext'@'localhost';
When a client connects as employee_ext
from
the local host, MySQL uses the plugin named
my_auth_plugin
to perform authentication.
Suppose that my_auth_plugin
returns a user
name of employee
to the server, based on the
content of
'
and perhaps by consulting some external authentication system.
The name my_auth_string
'employee
differs from
employee_ext
, so returning
employee
serves as a request to the server to
treat the employee_ext
external user, for
purposes of privilege checking, as the
employee
local user.
In this case, employee_ext
is the proxy user
and employee
is the proxied user.
The server verifies that proxy authentication for
employee
is possible for the
employee_ext
user by checking whether
employee_ext
(the proxy user) has the
PROXY
privilege for
employee
(the proxied user). If this
privilege has not been granted, an error occurs. Otherwise,
employee_ext
assumes the privileges of
employee
. The server checks statements
executed during the client session by
employee_ext
against the privileges granted
to employee
. In this case,
employee_ext
can access tables in the
employees
database.
The proxied account, employee
, uses the
mysql_no_login
authentication plugin to
prevent clients from using the account to log in directly. (This
assumes that the plugin is installed. For instructions, see
Section 6.4.1.10, “No-Login Pluggable Authentication”.) For
alternative methods of protecting proxied accounts against
direct use, see
Preventing Direct Login to Proxied Accounts.
When proxying occurs, the USER()
and CURRENT_USER()
functions can
be used to see the difference between the connecting user (the
proxy user) and the account whose privileges apply during the
current session (the proxied user). For the example just
described, those functions return these values:
mysql> SELECT USER(), CURRENT_USER();
+------------------------+--------------------+
| USER() | CURRENT_USER() |
+------------------------+--------------------+
| employee_ext@localhost | employee@localhost |
+------------------------+--------------------+
In the CREATE USER
statement that
creates the proxy user account, the IDENTIFIED
WITH
clause that names the proxy-supporting
authentication plugin is optionally followed by an AS
'
clause
specifying a string that the server passes to the plugin when
the user connects. If present, the string provides information
that helps the plugin determine how to map the proxy (external)
client user name to a proxied user name. It is up to each plugin
whether it requires the auth_string
'AS
clause. If so, the
format of the authentication string depends on how the plugin
intends to use it. Consult the documentation for a given plugin
for information about the authentication string values it
accepts.
Proxied accounts generally are intended to be used only by means of proxy accounts. That is, clients connect using a proxy account, then are mapped onto and assume the privileges of the appropriate proxied user.
There are multiple ways to ensure that a proxied account cannot be used directly:
Associate the account with the
mysql_no_login
authentication plugin. In
this case, the account cannot be used for direct logins
under any circumstances. This assumes that the plugin is
installed. For instructions, see
Section 6.4.1.10, “No-Login Pluggable Authentication”.
Include the ACCOUNT LOCK
option when you
create the account. See Section 13.7.1.2, “CREATE USER Statement”. With
this method, also include a password so that if the account
is unlocked later, it cannot be accessed with no password.
(If the validate_password
plugin is
enabled, it will not permit creating an account without a
password, even if the account is locked. See
Section 6.4.3, “The Password Validation Plugin”.)
Create the account with a password but do not tell anyone else the password. If you do not let anyone know the password for the account, clients cannot use it to connect directly to the MySQL server.
The PROXY
privilege is needed to
enable an external user to connect as and have the privileges of
another user. To grant this privilege, use the
GRANT
statement. For example:
GRANT PROXY ON 'proxied_user
' TO 'proxy_user
';
The statement creates a row in the
mysql.proxies_priv
grant table.
At connect time, proxy_user
must
represent a valid externally authenticated MySQL user, and
proxied_user
must represent a valid
locally authenticated user. Otherwise, the connection attempt
fails.
The corresponding REVOKE
syntax
is:
REVOKE PROXY ON 'proxied_user
' FROM 'proxy_user
';
MySQL GRANT
and
REVOKE
syntax extensions work as
usual. Examples:
-- grant PROXY to multiple accounts GRANT PROXY ON 'a' TO 'b', 'c', 'd'; -- revoke PROXY from multiple accounts REVOKE PROXY ON 'a' FROM 'b', 'c', 'd'; -- grant PROXY to an account and enable the account to grant -- PROXY to the proxied account GRANT PROXY ON 'a' TO 'd' WITH GRANT OPTION; -- grant PROXY to default proxy account GRANT PROXY ON 'a' TO ''@'';
The PROXY
privilege can be
granted in these cases:
By a user that has GRANT PROXY ... WITH GRANT
OPTION
for
proxied_user
.
By proxied_user
for itself: The
value of USER()
must exactly
match CURRENT_USER()
and
proxied_user
, for both the user
name and host name parts of the account name.
The initial root
account created during MySQL
installation has the
PROXY ... WITH GRANT
OPTION
privilege for ''@''
, that
is, for all users and all hosts. This enables
root
to set up proxy users, as well as to
delegate to other accounts the authority to set up proxy users.
For example, root
can do this:
CREATE USER 'admin'@'localhost'
IDENTIFIED BY 'admin_password
';
GRANT PROXY
ON ''@''
TO 'admin'@'localhost'
WITH GRANT OPTION;
Those statements create an admin
user that
can manage all GRANT PROXY
mappings. For
example, admin
can do this:
GRANT PROXY ON sally TO joe;
To specify that some or all users should connect using a given
authentication plugin, create a “blank” MySQL
account with an empty user name and host name
(''@''
), associate it with that plugin, and
let the plugin return the real authenticated user name (if
different from the blank user). Suppose that there exists a
plugin named ldap_auth
that implements LDAP
authentication and maps connecting users onto either a developer
or manager account. To set up proxying of users onto these
accounts, use the following statements:
-- create default proxy account CREATE USER ''@'' IDENTIFIED WITH ldap_auth AS 'O=Oracle, OU=MySQL'; -- create proxied accounts; use -- mysql_no_login plugin to prevent direct login CREATE USER 'developer'@'localhost' IDENTIFIED WITH mysql_no_login; CREATE USER 'manager'@'localhost' IDENTIFIED WITH mysql_no_login; -- grant to default proxy account the -- PROXY privilege for proxied accounts GRANT PROXY ON 'manager'@'localhost' TO ''@''; GRANT PROXY ON 'developer'@'localhost' TO ''@'';
Now assume that a client connects as follows:
shell>mysql --user=myuser --password ...
Enter password:myuser_password
The server will not find myuser
defined as a
MySQL user. But because there is a blank user account
(''@''
) that matches the client user name and
host name, the server authenticates the client against that
account: The server invokes the ldap_auth
authentication plugin and passes myuser
and
myuser_password
to it as the user
name and password.
If the ldap_auth
plugin finds in the LDAP
directory that myuser_password
is not
the correct password for myuser
,
authentication fails and the server rejects the connection.
If the password is correct and ldap_auth
finds that myuser
is a developer, it returns
the user name developer
to the MySQL server,
rather than myuser
. Returning a user name
different from the client user name of myuser
signals to the server that it should treat
myuser
as a proxy. The server verifies that
''@''
can authenticate as
developer
(because ''@''
has the PROXY
privilege to do so)
and accepts the connection. The session proceeds with
myuser
having the privileges of the
developer
proxied user. (These privileges
should be set up by the DBA using
GRANT
statements, not shown.) The
USER()
and
CURRENT_USER()
functions return
these values:
mysql> SELECT USER(), CURRENT_USER();
+------------------+---------------------+
| USER() | CURRENT_USER() |
+------------------+---------------------+
| myuser@localhost | developer@localhost |
+------------------+---------------------+
If the plugin instead finds in the LDAP directory that
myuser
is a manager, it returns
manager
as the user name and the session
proceeds with myuser
having the privileges of
the manager
proxied user.
mysql> SELECT USER(), CURRENT_USER();
+------------------+-------------------+
| USER() | CURRENT_USER() |
+------------------+-------------------+
| myuser@localhost | manager@localhost |
+------------------+-------------------+
For simplicity, external authentication cannot be multilevel:
Neither the credentials for developer
nor
those for manager
are taken into account in
the preceding example. However, they are still used if a client
tries to connect and authenticate directly as the
developer
or manager
account, which is why those proxied accounts should be protected
against direct login (see
Preventing Direct Login to Proxied Accounts).
If you intend to create a default proxy user, check for other existing “match any user” accounts that take precedence over the default proxy user because they can prevent that user from working as intended.
In the preceding discussion, the default proxy user account has
''
in the host part, which matches any host.
If you set up a default proxy user, take care to also check
whether nonproxy accounts exist with the same user part and
'%'
in the host part, because
'%'
also matches any host, but has precedence
over ''
by the rules that the server uses to
sort account rows internally (see
Section 6.2.5, “Access Control, Stage 1: Connection Verification”).
Suppose that a MySQL installation includes these two accounts:
-- create default proxy account CREATE USER ''@'' IDENTIFIED WITH some_plugin AS 'some_auth_string
'; -- create anonymous account CREATE USER ''@'%' IDENTIFIED BY 'anon_user_password
';
The first account (''@''
) is intended as the
default proxy user, used to authenticate connections for users
who do not otherwise match a more-specific account. The second
account (''@'%'
) is an anonymous-user
account, which might have been created, for example, to enable
users without their own account to connect anonymously.
Both accounts have the same user part (''
),
which matches any user. And each account has a host part that
matches any host. Nevertheless, there is a priority in account
matching for connection attempts because the matching rules sort
a host of '%'
ahead of ''
.
For accounts that do not match any more-specific account, the
server attempts to authenticate them against
''@'%'
(the anonymous user) rather than
''@''
(the default proxy user). As a result,
the default proxy account is never used.
To avoid this problem, use one of the following strategies:
Remove the anonymous account so that it does not conflict with the default proxy user.
Use a more-specific default proxy user that matches ahead of
the anonymous user. For example, to permit only
localhost
proxy connections, use
''@'localhost'
:
CREATE USER ''@'localhost'
IDENTIFIED WITH some_plugin
AS 'some_auth_string
';
In addition, modify any GRANT PROXY
statements to name ''@'localhost'
rather
than ''@''
as the proxy user.
Be aware that this strategy prevents anonymous-user
connections from localhost
.
Use a named default account rather than an anonymous default
account. For an example of this technique, consult the
instructions for using the
authentication_windows
plugin. See
Section 6.4.1.8, “Windows Pluggable Authentication”.
Create multiple proxy users, one for local connections and one for “everything else” (remote connections). This can be useful particularly when local users should have different privileges from remote users.
Create the proxy users:
-- create proxy user for local connections CREATE USER ''@'localhost' IDENTIFIED WITH some_plugin AS 'some_auth_string
'; -- create proxy user for remote connections CREATE USER ''@'%' IDENTIFIED WITH some_plugin AS 'some_auth_string
';
Create the proxied users:
-- create proxied user for local connections CREATE USER 'developer'@'localhost' IDENTIFIED WITH mysql_no_login; -- create proxied user for remote connections CREATE USER 'developer'@'%' IDENTIFIED WITH mysql_no_login;
Grant to each proxy account the
PROXY
privilege for the
corresponding proxied account:
GRANT PROXY ON 'developer'@'localhost' TO ''@'localhost'; GRANT PROXY ON 'developer'@'%' TO ''@'%';
Finally, grant appropriate privileges to the local and remote proxied users (not shown).
Assume that the
some_plugin
/'
combination causes some_auth_string
'some_plugin
to map the
client user name to developer
. Local
connections match the ''@'localhost'
proxy user, which maps to the
'developer'@'localhost'
proxied user.
Remote connections match the ''@'%'
proxy
user, which maps to the 'developer'@'%'
proxied user.
Some authentication plugins implement proxy user mapping for
themselves (for example, the PAM and Windows authentication
plugins). Other authentication plugins do not support proxy
users by default. Of these, some can request that the MySQL
server itself map proxy users according to granted proxy
privileges: mysql_native_password
,
sha256_password
. If the
check_proxy_users
system
variable is enabled, the server performs proxy user mapping for
any authentication plugins that make such a request:
By default,
check_proxy_users
is
disabled, so the server performs no proxy user mapping even
for authentication plugins that request server support for
proxy users.
If check_proxy_users
is
enabled, it may also be necessary to enable a
plugin-specific system variable to take advantage of server
proxy user mapping support:
For the mysql_native_password
plugin,
enable
mysql_native_password_proxy_users
.
For the sha256_password
plugin,
enable
sha256_password_proxy_users
.
Proxy user mapping performed by the server is subject to these restrictions:
The server will not proxy to or from an anonymous user, even
if the associated PROXY
privilege is granted.
When a single account has been granted proxy privileges for more than one proxied account, server proxy user mapping is nondeterministic. Therefore, granting to a single account proxy privileges for multiple proxied accounts is discouraged.
Two system variables help trace the proxy login process:
proxy_user
: This value is
NULL
if proxying is not used. Otherwise,
it indicates the proxy user account. For example, if a
client authenticates through the ''@''
proxy account, this variable is set as follows:
mysql> SELECT @@proxy_user;
+--------------+
| @@proxy_user |
+--------------+
| ''@'' |
+--------------+
external_user
: Sometimes
the authentication plugin may use an external user to
authenticate to the MySQL server. For example, when using
Windows native authentication, a plugin that authenticates
using the windows API does not need the login ID passed to
it. However, it still uses a Windows user ID to
authenticate. The plugin may return this external user ID
(or the first 512 UTF-8 bytes of it) to the server using the
external_user
read-only session variable.
If the plugin does not set this variable, its value is
NULL
.
MySQL supports locking and unlocking user accounts using the
ACCOUNT LOCK
and ACCOUNT
UNLOCK
clauses for the CREATE
USER
and ALTER USER
statements:
When used with CREATE USER
,
these clauses specify the initial locking state for a new
account. In the absence of either clause, the account is
created in an unlocked state.
If the validate_password
plugin is enabled,
it will not permit creating an account without a password,
even if the account is locked. See
Section 6.4.3, “The Password Validation Plugin”.
When used with ALTER USER
,
these clauses specify the new locking state for an existing
account. In the absence of either clause, the account locking
state remains unchanged.
Account locking state is recorded in the
account_locked
column of the
mysql.user
system table. The output from
SHOW CREATE USER
indicates whether
an account is locked or unlocked.
If a client attempts to connect to a locked account, the attempt
fails. The server increments the
Locked_connects
status variable
that indicates the number of attempts to connect to a locked
account, returns an
ER_ACCOUNT_HAS_BEEN_LOCKED
error,
and writes a message to the error log:
Access denied for user 'user_name
'@'host_name
'. Account is locked.
Locking an account does not affect being able to connect using a
proxy user that assumes the identity of the locked account. It
also does not affect the ability to execute stored programs or
views that have a DEFINER
clause naming the
locked account. That is, the ability to use a proxied account or
stored programs or views is not affected by locking the account.
The account-locking capability depends on the presence of the
account_locked
column in the
mysql.user
system table. For upgrades from
MySQL versions older than 5.7.6, perform the MySQL upgrade
procedure to ensure that this column exists. See
Section 2.11, “Upgrading MySQL”. For nonupgraded installations that
have no account_locked
column, the server
treats all accounts as unlocked, and using the ACCOUNT
LOCK
or ACCOUNT UNLOCK
clauses
produces an error.
One means of restricting client use of MySQL server resources is
to set the global
max_user_connections
system
variable to a nonzero value. This limits the number of
simultaneous connections that can be made by any given account,
but places no limits on what a client can do once connected. In
addition, setting
max_user_connections
does not
enable management of individual accounts. Both types of control
are of interest to MySQL administrators.
To address such concerns, MySQL permits limits for individual accounts on use of these server resources:
The number of queries an account can issue per hour
The number of updates an account can issue per hour
The number of times an account can connect to the server per hour
The number of simultaneous connections to the server by an account
Any statement that a client can issue counts against the query limit, unless its results are served from the query cache. Only statements that modify databases or tables count against the update limit.
An “account” in this context corresponds to a row in
the mysql.user
system table. That is, a
connection is assessed against the User
and
Host
values in the user
table row that applies to the connection. For example, an account
'usera'@'%.example.com'
corresponds to a row in
the user
table that has User
and Host
values of usera
and
%.example.com
, to permit
usera
to connect from any host in the
example.com
domain. In this case, the server
applies resource limits in this row collectively to all
connections by usera
from any host in the
example.com
domain because all such connections
use the same account.
Before MySQL 5.0, an “account” was assessed against
the actual host from which a user connects. This older method of
accounting may be selected by starting the server with the
--old-style-user-limits
option. In
this case, if usera
connects simultaneously
from host1.example.com
and
host2.example.com
, the server applies the
account resource limits separately to each connection. If
usera
connects again from
host1.example.com
, the server applies the
limits for that connection together with the existing connection
from that host.
To establish resource limits for an account at account-creation
time, use the CREATE USER
statement. To modify the limits for an existing account, use
ALTER USER
. Provide a
WITH
clause that names each resource to be
limited. The default value for each limit is zero (no limit). For
example, to create a new account that can access the
customer
database, but only in a limited
fashion, issue these statements:
mysql>CREATE USER 'francis'@'localhost' IDENTIFIED BY 'frank'
->WITH MAX_QUERIES_PER_HOUR 20
->MAX_UPDATES_PER_HOUR 10
->MAX_CONNECTIONS_PER_HOUR 5
->MAX_USER_CONNECTIONS 2;
The limit types need not all be named in the
WITH
clause, but those named can be present in
any order. The value for each per-hour limit should be an integer
representing a count per hour. For
MAX_USER_CONNECTIONS
, the limit is an integer
representing the maximum number of simultaneous connections by the
account. If this limit is set to zero, the global
max_user_connections
system
variable value determines the number of simultaneous connections.
If max_user_connections
is also
zero, there is no limit for the account.
To modify limits for an existing account, use an
ALTER USER
statement. The following
statement changes the query limit for francis
to 100:
mysql> ALTER USER 'francis'@'localhost' WITH MAX_QUERIES_PER_HOUR 100;
The statement modifies only the limit value specified and leaves the account otherwise unchanged.
To remove a limit, set its value to zero. For example, to remove
the limit on how many times per hour francis
can connect, use this statement:
mysql> ALTER USER 'francis'@'localhost' WITH MAX_CONNECTIONS_PER_HOUR 0;
As mentioned previously, the simultaneous-connection limit for an
account is determined from the
MAX_USER_CONNECTIONS
limit and the
max_user_connections
system
variable. Suppose that the global
max_user_connections
value is 10
and three accounts have individual resource limits specified as
follows:
ALTER USER 'user1'@'localhost' WITH MAX_USER_CONNECTIONS 0; ALTER USER 'user2'@'localhost' WITH MAX_USER_CONNECTIONS 5; ALTER USER 'user3'@'localhost' WITH MAX_USER_CONNECTIONS 20;
user1
has a connection limit of 10 (the global
max_user_connections
value)
because it has a MAX_USER_CONNECTIONS
limit of
zero. user2
and user3
have
connection limits of 5 and 20, respectively, because they have
nonzero MAX_USER_CONNECTIONS
limits.
The server stores resource limits for an account in the
user
table row corresponding to the account.
The max_questions
,
max_updates
, and
max_connections
columns store the per-hour
limits, and the max_user_connections
column
stores the MAX_USER_CONNECTIONS
limit. (See
Section 6.2.3, “Grant Tables”.)
Resource-use counting takes place when any account has a nonzero limit placed on its use of any of the resources.
As the server runs, it counts the number of times each account uses resources. If an account reaches its limit on number of connections within the last hour, the server rejects further connections for the account until that hour is up. Similarly, if the account reaches its limit on the number of queries or updates, the server rejects further queries or updates until the hour is up. In all such cases, the server issues appropriate error messages.
Resource counting occurs per account, not per client. For example, if your account has a query limit of 50, you cannot increase your limit to 100 by making two simultaneous client connections to the server. Queries issued on both connections are counted together.
The current per-hour resource-use counts can be reset globally for all accounts, or individually for a given account:
To reset the current counts to zero for all accounts, issue a
FLUSH USER_RESOURCES
statement.
The counts also can be reset by reloading the grant tables
(for example, with a FLUSH
PRIVILEGES
statement or a mysqladmin
reload command).
The counts for an individual account can be reset to zero by setting any of its limits again. Specify a limit value equal to the value currently assigned to the account.
Per-hour counter resets do not affect the
MAX_USER_CONNECTIONS
limit.
All counts begin at zero when the server starts. Counts do not carry over through server restarts.
For the MAX_USER_CONNECTIONS
limit, an edge
case can occur if the account currently has open the maximum
number of connections permitted to it: A disconnect followed
quickly by a connect can result in an error
(ER_TOO_MANY_USER_CONNECTIONS
or
ER_USER_LIMIT_REACHED
) if the
server has not fully processed the disconnect by the time the
connect occurs. When the server finishes disconnect processing,
another connection will once more be permitted.
If you encounter problems when you try to connect to the MySQL server, the following items describe some courses of action you can take to correct the problem.
Make sure that the server is running. If it is not, clients cannot connect to it. For example, if an attempt to connect to the server fails with a message such as one of those following, one cause might be that the server is not running:
shell>mysql
ERROR 2003: Can't connect to MySQL server on 'host_name
' (111) shell>mysql
ERROR 2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (111)
It might be that the server is running, but you are trying to
connect using a TCP/IP port, named pipe, or Unix socket file
different from the one on which the server is listening. To
correct this when you invoke a client program, specify a
--port
option to indicate the
proper port number, or a
--socket
option to indicate
the proper named pipe or Unix socket file. To find out where
the socket file is, you can use this command:
shell> netstat -ln | grep mysql
Make sure that the server has not been configured to ignore
network connections or (if you are attempting to connect
remotely) that it has not been configured to listen only
locally on its network interfaces. If the server was started
with the skip_networking
system variable enabled, it will not accept TCP/IP connections
at all. If the server was started with the
bind_address
system variable
set to 127.0.0.1
, it will listen for TCP/IP
connections only locally on the loopback interface and will
not accept remote connections.
Check to make sure that there is no firewall blocking access to MySQL. Your firewall may be configured on the basis of the application being executed, or the port number used by MySQL for communication (3306 by default). Under Linux or Unix, check your IP tables (or similar) configuration to ensure that the port has not been blocked. Under Windows, applications such as ZoneAlarm or Windows Firewall may need to be configured not to block the MySQL port.
The grant tables must be properly set up so that the server
can use them for access control. For some distribution types
(such as binary distributions on Windows, or RPM distributions
on Linux), the installation process initializes the MySQL data
directory, including the mysql
system
database containing the grant tables. For distributions that
do not do this, you must initialize the data directory
manually. For details, see Section 2.10, “Postinstallation Setup and Testing”.
To determine whether you need to initialize the grant tables,
look for a mysql
directory under the data
directory. (The data directory normally is named
data
or var
and is
located under your MySQL installation directory.) Make sure
that you have a file named user.MYD
in
the mysql
database directory. If not,
initialize the
data directory. After doing so and starting the server,
you should be able to connect to the server.
After a fresh installation, if you try to log on to the server
as root
without using a password, you might
get the following error message.
shell> mysql -u root
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)
It means a root password has already been assigned during
installation and it has to be supplied. See
Section 2.10.4, “Securing the Initial MySQL Account” on the different ways the
password could have been assigned and, in some cases, how to
find it. If you need to reset the root password, see
instructions in Section B.4.3.2, “How to Reset the Root Password”. After
you have found or reset your password, log on again as
root
using the
--password
(or
-p
)
option:
shell> mysql -u root -p
Enter password:
However, the server is going to let you connect as
root
without using a password if you have
initialized MySQL using mysqld
--initialize-insecure (see
Section 2.10.1, “Initializing the Data Directory” for details).
That is a security risk, so you should set a password for the
root
account; see
Section 2.10.4, “Securing the Initial MySQL Account” for instructions.
If you have updated an existing MySQL installation to a newer version, did you perform the MySQL upgrade procedure? If not, do so. The structure of the grant tables changes occasionally when new capabilities are added, so after an upgrade you should always make sure that your tables have the current structure. For instructions, see Section 2.11, “Upgrading MySQL”.
If a client program receives the following error message when it tries to connect, it means that the server expects passwords in a newer format than the client is capable of generating:
shell> mysql
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
For information on how to deal with this, see Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password Plugin”.
Remember that client programs use connection parameters
specified in option files or environment variables. If a
client program seems to be sending incorrect default
connection parameters when you have not specified them on the
command line, check any applicable option files and your
environment. For example, if you get Access
denied
when you run a client without any options,
make sure that you have not specified an old password in any
of your option files!
You can suppress the use of option files by a client program
by invoking it with the
--no-defaults
option. For
example:
shell> mysqladmin --no-defaults -u root version
The option files that clients use are listed in Section 4.2.2.2, “Using Option Files”. Environment variables are listed in Section 4.9, “Environment Variables”.
If you get the following error, it means that you are using an
incorrect root
password:
shell> mysqladmin -u root -pxxxx
ver
Access denied for user 'root'@'localhost' (using password: YES)
If the preceding error occurs even when you have not specified
a password, it means that you have an incorrect password
listed in some option file. Try the
--no-defaults
option as
described in the previous item.
For information on changing passwords, see Section 6.2.10, “Assigning Account Passwords”.
If you have lost or forgotten the root
password, see Section B.4.3.2, “How to Reset the Root Password”.
localhost
is a synonym for your local host
name, and is also the default host to which clients try to
connect if you specify no host explicitly.
You can use a --host=127.0.0.1
option to name the server host explicitly. This will make a
TCP/IP connection to the local mysqld
server. You can also use TCP/IP by specifying a
--host
option that uses the
actual host name of the local host. In this case, the host
name must be specified in a user
table row
on the server host, even though you are running the client
program on the same host as the server.
The Access denied
error message tells you
who you are trying to log in as, the client host from which
you are trying to connect, and whether you were using a
password. Normally, you should have one row in the
user
table that exactly matches the host
name and user name that were given in the error message. For
example, if you get an error message that contains
using password: NO
, it means that you tried
to log in without a password.
If you get an Access denied
error when
trying to connect to the database with mysql -u
, you may have a
problem with the user_name
user
table. Check this by
executing mysql -u root mysql
and issuing
this SQL statement:
SELECT * FROM user;
The result should include a row with the
Host
and User
columns
matching your client's host name and your MySQL user name.
If the following error occurs when you try to connect from a
host other than the one on which the MySQL server is running,
it means that there is no row in the user
table with a Host
value that matches the
client host:
Host ... is not allowed to connect to this MySQL server
You can fix this by setting up an account for the combination of client host name and user name that you are using when trying to connect.
If you do not know the IP address or host name of the machine
from which you are connecting, you should put a row with
'%'
as the Host
column
value in the user
table. After trying to
connect from the client machine, use a SELECT
USER()
query to see how you really did connect. Then
change the '%'
in the
user
table row to the actual host name that
shows up in the log. Otherwise, your system is left insecure
because it permits connections from any host for the given
user name.
On Linux, another reason that this error might occur is that
you are using a binary MySQL version that is compiled with a
different version of the glibc
library than
the one you are using. In this case, you should either upgrade
your operating system or glibc
, or download
a source distribution of MySQL version and compile it
yourself. A source RPM is normally trivial to compile and
install, so this is not a big problem.
If you specify a host name when trying to connect, but get an error message where the host name is not shown or is an IP address, it means that the MySQL server got an error when trying to resolve the IP address of the client host to a name:
shell> mysqladmin -u root -pxxxx
-h some_hostname
ver
Access denied for user 'root'@'' (using password: YES)
If you try to connect as root
and get the
following error, it means that you do not have a row in the
user
table with a User
column value of 'root'
and that
mysqld cannot resolve the host name for
your client:
Access denied for user ''@'unknown'
These errors indicate a DNS problem. To fix it, execute mysqladmin flush-hosts to reset the internal DNS host cache. See Section 8.12.5.2, “DNS Lookup Optimization and the Host Cache”.
Some permanent solutions are:
Determine what is wrong with your DNS server and fix it.
Specify IP addresses rather than host names in the MySQL grant tables.
Put an entry for the client machine name in
/etc/hosts
on Unix or
\windows\hosts
on Windows.
Start mysqld with the
skip_name_resolve
system
variable enabled.
Start mysqld with the
--skip-host-cache
option.
On Unix, if you are running the server and the client on
the same machine, connect to localhost
.
For connections to localhost
, MySQL
programs attempt to connect to the local server by using a
Unix socket file, unless there are connection parameters
specified to ensure that the client makes a TCP/IP
connection. For more information, see
Section 4.2.4, “Connecting to the MySQL Server Using Command Options”.
On Windows, if you are running the server and the client
on the same machine and the server supports named pipe
connections, connect to the host name .
(period). Connections to .
use a named
pipe rather than TCP/IP.
If mysql -u root
works but mysql
-h
results in your_hostname
-u rootAccess denied
(where
your_hostname
is the actual host
name of the local host), you may not have the correct name for
your host in the user
table. A common
problem here is that the Host
value in the
user
table row specifies an unqualified
host name, but your system's name resolution routines return a
fully qualified domain name (or vice versa). For example, if
you have a row with host 'pluto'
in the
user
table, but your DNS tells MySQL that
your host name is 'pluto.example.com'
, the
row does not work. Try adding a row to the
user
table that contains the IP address of
your host as the Host
column value.
(Alternatively, you could add a row to the
user
table with a Host
value that contains a wildcard (for example,
'pluto.%'
). However, use of
Host
values ending with
%
is insecure and is
not recommended!)
If mysql -u
works but
user_name
mysql -u
does not, you
have not granted access to the given user for the database
named user_name
some_db
some_db
.
If mysql -u
works when
executed on the server host, but user_name
mysql -h
does not work
when executed on a remote client host, you have not enabled
access to the server for the given user name from the remote
host.
host_name
-u
user_name
If you cannot figure out why you get Access
denied
, remove from the user
table all rows that have Host
values
containing wildcards (rows that contain '%'
or '_'
characters). A very common error is
to insert a new row with
Host
='%'
and
User
='
,
thinking that this enables you to specify
some_user
'localhost
to connect from the same machine.
The reason that this does not work is that the default
privileges include a row with
Host
='localhost'
and
User
=''
. Because that
row has a Host
value
'localhost'
that is more specific than
'%'
, it is used in preference to the new
row when connecting from localhost
! The
correct procedure is to insert a second row with
Host
='localhost'
and
User
='
,
or to delete the row with
some_user
'Host
='localhost'
and
User
=''
. After deleting
the row, remember to issue a FLUSH
PRIVILEGES
statement to reload the grant tables. See
also Section 6.2.5, “Access Control, Stage 1: Connection Verification”.
If you are able to connect to the MySQL server, but get an
Access denied
message whenever you issue a
SELECT ... INTO
OUTFILE
or LOAD DATA
statement, your row in the user
table does
not have the FILE
privilege
enabled.
If you change the grant tables directly (for example, by using
INSERT
,
UPDATE
, or
DELETE
statements) and your
changes seem to be ignored, remember that you must execute a
FLUSH PRIVILEGES
statement or a
mysqladmin flush-privileges command to
cause the server to reload the privilege tables. Otherwise,
your changes have no effect until the next time the server is
restarted. Remember that after you change the
root
password with an
UPDATE
statement, you will not
need to specify the new password until after you flush the
privileges, because the server will not know you've changed
the password yet!
If your privileges seem to have changed in the middle of a session, it may be that a MySQL administrator has changed them. Reloading the grant tables affects new client connections, but it also affects existing connections as indicated in Section 6.2.9, “When Privilege Changes Take Effect”.
If you have access problems with a Perl, PHP, Python, or ODBC
program, try to connect to the server with mysql -u
or user_name
db_name
mysql
-u
. If you are able
to connect using the mysql client, the
problem lies with your program, not with the access
privileges. (There is no space between user_name
-ppassword
db_name
-p
and
the password; you can also use the
--password=
syntax to specify the password. If you use the
password
-p
or
--password
option with no
password value, MySQL prompts you for the password.)
For testing purposes, start the mysqld
server with the
--skip-grant-tables
option.
Then you can change the MySQL grant tables and use the
SHOW GRANTS
statement to check
whether your modifications have the desired effect. When you
are satisfied with your changes, execute mysqladmin
flush-privileges to tell the
mysqld server to reload the privileges.
This enables you to begin using the new grant table contents
without stopping and restarting the server.
If everything else fails, start the mysqld
server with a debugging option (for example,
--debug=d,general,query
). This
prints host and user information about attempted connections,
as well as information about each command issued. See
Section 28.5.3, “The DBUG Package”.
If you have any other problems with the MySQL grant tables and
ask on the
MySQL Community
Slack, always provide a dump of the MySQL grant
tables. You can dump the tables with the mysqldump
mysql command. To file a bug report, see the
instructions at Section 1.7, “How to Report Bugs or Problems”. In some cases,
you may need to restart mysqld with
--skip-grant-tables
to run
mysqldump.
Applications can use the following guidelines to perform SQL-based auditing that ties database activity to MySQL accounts.
MySQL accounts correspond to rows in the
mysql.user
system table. When a client connects
successfully, the server authenticates the client to a particular
row in this table. The User
and
Host
column values in this row uniquely
identify the account and correspond to the
'
format in which account names are written in SQL statements.
user_name
'@'host_name
'
The account used to authenticate a client determines which
privileges the client has. Normally, the
CURRENT_USER()
function can be
invoked to determine which account this is for the client user.
Its value is constructed from the User
and
Host
columns of the user
table row for the account.
However, there are circumstances under which the
CURRENT_USER()
value corresponds
not to the client user but to a different account. This occurs in
contexts when privilege checking is not based the client's
account:
Stored routines (procedures and functions) defined with the
SQL SECURITY DEFINER
characteristic
Views defined with the SQL SECURITY DEFINER
characteristic
Triggers and events
In those contexts, privilege checking is done against the
DEFINER
account and
CURRENT_USER()
refers to that
account, not to the account for the client who invoked the stored
routine or view or who caused the trigger to activate. To
determine the invoking user, you can call the
USER()
function, which returns a
value indicating the actual user name provided by the client and
the host from which the client connected. However, this value does
not necessarily correspond directly to an account in the
user
table, because the
USER()
value never contains
wildcards, whereas account values (as returned by
CURRENT_USER()
) may contain user
name and host name wildcards.
For example, a blank user name matches any user, so an account of
''@'localhost'
enables clients to connect as an
anonymous user from the local host with any user name. In this
case, if a client connects as user1
from the
local host, USER()
and
CURRENT_USER()
return different
values:
mysql> SELECT USER(), CURRENT_USER();
+-----------------+----------------+
| USER() | CURRENT_USER() |
+-----------------+----------------+
| user1@localhost | @localhost |
+-----------------+----------------+
The host name part of an account can contain wildcards, too. If
the host name contains a '%'
or
'_'
pattern character or uses netmask notation,
the account can be used for clients connecting from multiple hosts
and the CURRENT_USER()
value will
not indicate which one. For example, the account
'user2'@'%.example.com'
can be used by
user2
to connect from any host in the
example.com
domain. If user2
connects from remote.example.com
,
USER()
and
CURRENT_USER()
return different
values:
mysql> SELECT USER(), CURRENT_USER();
+--------------------------+---------------------+
| USER() | CURRENT_USER() |
+--------------------------+---------------------+
| user2@remote.example.com | user2@%.example.com |
+--------------------------+---------------------+
If an application must invoke
USER()
for user auditing (for
example, if it does auditing from within triggers) but must also
be able to associate the USER()
value with an account in the user
table, it is
necessary to avoid accounts that contain wildcards in the
User
or Host
column.
Specifically, do not permit User
to be empty
(which creates an anonymous-user account), and do not permit
pattern characters or netmask notation in Host
values. All accounts must have a nonempty User
value and literal Host
value.
With respect to the previous examples, the
''@'localhost'
and
'user2'@'%.example.com'
accounts should be
changed not to use wildcards:
RENAME USER ''@'localhost' TO 'user1'@'localhost'; RENAME USER 'user2'@'%.example.com' TO 'user2'@'remote.example.com';
If user2
must be able to connect from several
hosts in the example.com
domain, there should
be a separate account for each host.
To extract the user name or host name part from a
CURRENT_USER()
or
USER()
value, use the
SUBSTRING_INDEX()
function:
mysql>SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',1);
+---------------------------------------+ | SUBSTRING_INDEX(CURRENT_USER(),'@',1) | +---------------------------------------+ | user1 | +---------------------------------------+ mysql>SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',-1);
+----------------------------------------+ | SUBSTRING_INDEX(CURRENT_USER(),'@',-1) | +----------------------------------------+ | localhost | +----------------------------------------+
With an unencrypted connection between the MySQL client and the server, someone with access to the network could watch all your traffic and inspect the data being sent or received between client and server.
When you must move information over a network in a secure fashion, an unencrypted connection is unacceptable. To make any kind of data unreadable, use encryption. Encryption algorithms must include security elements to resist many kinds of known attacks such as changing the order of encrypted messages or replaying data twice.
MySQL supports encrypted connections between clients and the server using the TLS (Transport Layer Security) protocol. TLS is sometimes referred to as SSL (Secure Sockets Layer) but MySQL does not actually use the SSL protocol for encrypted connections because its encryption is weak (see Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”).
TLS uses encryption algorithms to ensure that data received over a public network can be trusted. It has mechanisms to detect data change, loss, or replay. TLS also incorporates algorithms that provide identity verification using the X.509 standard.
X.509 makes it possible to identify someone on the Internet. In basic terms, there should be some entity called a “Certificate Authority” (or CA) that assigns electronic certificates to anyone who needs them. Certificates rely on asymmetric encryption algorithms that have two encryption keys (a public key and a secret key). A certificate owner can present the certificate to another party as proof of identity. A certificate consists of its owner's public key. Any data encrypted using this public key can be decrypted only using the corresponding secret key, which is held by the owner of the certificate.
MySQL can be compiled for encrypted-connection support using OpenSSL or yaSSL. For a comparison of the two packages, see Section 6.3.4, “SSL Library-Dependent Capabilities” For information about the encryption protocols and ciphers each package supports, see Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”.
It is possible to compile MySQL using yaSSL as an alternative to OpenSSL only prior to MySQL 5.7.28. As of MySQL 5.7.28, support for yaSSL is removed and all MySQL builds use OpenSSL.
By default, MySQL programs attempt to connect using encryption if the server supports encrypted connections, falling back to an unencrypted connection if an encrypted connection cannot be established. For information about options that affect use of encrypted connections, see Section 6.3.1, “Configuring MySQL to Use Encrypted Connections” and Command Options for Encrypted Connections.
MySQL performs encryption on a per-connection basis, and use of
encryption for a given user can be optional or mandatory. This
enables you to choose an encrypted or unencrypted connection
according to the requirements of individual applications. For
information on how to require users to use encrypted connections,
see the discussion of the REQUIRE
clause of the
CREATE USER
statement in
Section 13.7.1.2, “CREATE USER Statement”. See also the description of the
require_secure_transport
system
variable at Section 5.1.7, “Server System Variables”
Encrypted connections can be used between master and slave replication servers. See Section 16.3.8, “Setting Up Replication to Use Encrypted Connections”.
For information about using encrypted connections from the MySQL C API, see Section 27.7.14, “C API Encrypted Connection Support”.
It is also possible to connect using encryption from within an SSH connection to the MySQL server host. For an example, see Section 6.3.5, “Connecting to MySQL Remotely from Windows with SSH”.
Several improvements were made to encrypted-connection support in MySQL 5.7. The following timeline summarizes the changes:
5.7.3: On the client side, an explicit
--ssl
option is no longer
advisory but prescriptive. Given a server enabled to support
encrypted connections, a client program can require an encrypted
connection by specifying only the
--ssl
option. (Previously, it
was necessary for the client to specify either the
--ssl-ca
option, or all three of
the --ssl-ca
,
--ssl-key
, and
--ssl-cert
options.) The
connection attempt fails if an encrypted connection cannot be
established. Other
--ssl-
options on
the client side are advisory in the absence of
xxx
--ssl
: The client attempts to
connect using encryption but falls back to an unencrypted
connection if an encrypted connection cannot be established.
5.7.5: The server-side --ssl
option value is enabled by default.
For servers compiled using OpenSSL, the
auto_generate_certs
and
sha256_password_auto_generate_rsa_keys
system variables are available to enable autogeneration and
autodiscovery of SSL/RSA certificate and key files at startup.
For certificate and key autodiscovery, if
--ssl
is enabled and other
--ssl-
options
are not given to configure encrypted
connections explicitly, the server attempts to enable support
for encrypted connections automatically at startup if it
discovers the requisite certificate and key files in the data
directory.
xxx
5.7.6: The mysql_ssl_rsa_setup utility is
available to make it easier to manually generate SSL/RSA
certificate and key files. Autodiscovery of SSL/RSA files at
startup is expanded to apply to all servers, whether compiled
using OpenSSL or yaSSL. (This means that
auto_generate_certs
need not be
enabled for autodiscovery to occur.)
If the server discovers at startup that the CA certificate is self-signed, it writes a warning to the error log. (The certificate is self-signed if created automatically by the server, or manually using mysql_ssl_rsa_setup.)
5.7.7: The C client library attempts to establish an encrypted connection by default if the server supports encrypted connections. This affects client programs as follows:
In the absence of an --ssl
option, clients attempt to connect using encryption, falling
back to an unencrypted connection if an encrypted connection
cannot be established.
The presence of an explicit
--ssl
option or a synonym
(--ssl=1
,
--enable-ssl
)
is prescriptive: Clients require an encrypted connection and
fail if one cannot be established.
With an --ssl=0
option or a
synonym
(--skip-ssl
,
--disable-ssl
),
clients use an unencrypted connection.
This change also affects subsequent releases of MySQL Connectors that are based on the C client library: Connector/C++ and Connector/ODBC.
5.7.8: The
require_secure_transport
system
variable is available to control whether client connections to
the server must use some form of secure transport.
5.7.10: TLS protocol support is extended from TLSv1 to also
include TLSv1.1 and TLSv1.2. The
tls_version
system variable on
the server side and
--tls-version
option on the
client side enable the level of support to be selected. See
Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”.
5.7.11: MySQL client programs support an
--ssl-mode
option that enables
you to specify the security state of the connection to the
server. The --ssl-mode
option
comprises the capabilities of the client-side
--ssl
and
--ssl-verify-server-cert
options. Consequently, --ssl
and
--ssl-verify-server-cert
are
deprecated, and are removed in MySQL 8.0.
5.7.28: Support for yaSSL was removed. All MySQL builds use OpenSSL.
Several options are available to indicate whether to use encrypted connections, and to specify the appropriate certificate and key files. This section provides general guidance about configuring the server and clients for encrypted connections:
For a complete list of options related to establishment of encrypted connections, see Command Options for Encrypted Connections. Instructions for creating any required certificate and key files are available in Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
Encrypted connections also can be used in these contexts:
Between master and slave replication servers. See Section 16.3.8, “Setting Up Replication to Use Encrypted Connections”.
Among Group Replication servers. See Section 17.5.2, “Group Replication Secure Socket Layer (SSL) Support”.
By client programs that are based on the MySQL C API. See Section 27.7.14, “C API Encrypted Connection Support”.
On the server side, the --ssl
option specifies that the server permits but does not require
encrypted connections. This option is enabled by default, so it
need not be specified explicitly.
To require that clients connect using encrypted connections,
enable the
require_secure_transport
system
variable. See Configuring Encrypted Connections as Mandatory.
These options on the server side specify the certificate and key files the server uses when permitting clients to establish encrypted connections:
--ssl-ca
: The path name of
the Certificate Authority (CA) certificate file.
(--ssl-capath
is similar but specifies the
path name of a directory of CA certificate files.)
--ssl-cert
: The path name of
the server public key certificate file. This certificate can
be sent to the client and authenticated against the CA
certificate that it has.
--ssl-key
: The path name of
the server private key file.
For example, to enable the server for encrypted connections,
start it with these lines in the my.cnf
file, changing the file names as necessary:
[mysqld] ssl-ca=ca.pem ssl-cert=server-cert.pem ssl-key=server-key.pem
To specify in addition that clients are required to use
encrypted connections, enable the
require_secure_transport
system
variable:
[mysqld] ssl-ca=ca.pem ssl-cert=server-cert.pem ssl-key=server-key.pem require_secure_transport=ON
Each certificate and key option names a file in PEM format.
Should you need to create the required certificate and key
files, see Section 6.3.3, “Creating SSL and RSA Certificates and Keys”. MySQL
servers compiled using OpenSSL can generate missing certificate
and key files automatically at startup. See
Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
Alternatively, if you have a MySQL source distribution, you can
test your setup using the demonstration certificate and key
files in its mysql-test/std_data
directory.
The server performs certificate and key file autodiscovery. If
--ssl
is enabled (possibly along
with --ssl-cipher
) and other
--ssl-
options
are not given to configure encrypted
connections explicitly, the server attempts to enable encrypted
connection support automatically at startup:
xxx
If the server discovers valid certificate and key files
named ca.pem
,
server-cert.pem
, and
server-key.pem
in the data directory,
it enables support for encrypted connections by clients.
(The files need not have been generated automatically; what
matters is that they have those names and are valid.)
If the server does not find valid certificate and key files in the data directory, it continues executing but without support for encrypted connections.
If the server automatically enables encrypted connection support, it writes a note to the error log. If the server discovers that the CA certificate is self-signed, it writes a warning to the error log. (The certificate is self-signed if created automatically by the server or manually using mysql_ssl_rsa_setup.)
MySQL also provides these options for server-side SSL control:
--ssl-cipher
: The list of
permissible ciphers for connection encryption.
--ssl-crl
: The path name of
the file containing certificate revocation lists.
(--ssl-crlpath
is similar but specifies the
path name of a directory of certificate revocation-list
files.)
The values of the
--ssl-
options
set the values of the corresponding system variables
(xxx
ssl_ca
,
ssl_cert
,
ssl_key
, and so forth).
To explicitly specify which encryption protocols the server
permits, use the tls_version
system variable; see
Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”. For
example, you can set this variable to prevent clients from using
less-secure protocols.
By default, MySQL client programs attempt to establish an
encrypted connection if the server supports encrypted
connections, with further control available through the
--ssl-mode
option:
In the absence of an
--ssl-mode
option, clients
attempt to connect using encryption, falling back to an
unencrypted connection if an encrypted connection cannot be
established. This is also the behavior with an explicit
--ssl-mode=PREFFERED
option.
With --ssl-mode=REQUIRED
,
clients require an encrypted connection and fail if one
cannot be established.
With --ssl-mode=DISABLED
,
clients use an unencrypted connection.
With --ssl-mode=VERIFY_CA
or
--ssl-mode=VERIFY_IDENTITY
,
clients require an encrypted connection, and also perform
verification against the server CA certificate and (with
VERIFY_IDENTITY
) against the server host
name in its certificate.
Attempts to establish an unencrypted connection fail if the
require_secure_transport
system
variable is enabled on the server side to cause the server to
require encrypted connections. See
Configuring Encrypted Connections as Mandatory.
The following options on the client side identify the
certificate and key files clients use when establishing
encrypted connections to the server. They are similar to the
options used on the server side, but
--ssl-cert
and
--ssl-key
identify the client
public and private key:
--ssl-ca
: The path name of
the Certificate Authority (CA) certificate file. This
option, if used, must specify the same certificate used by
the server. (--ssl-capath
is similar but
specifies the path name of a directory of CA certificate
files.)
--ssl-cert
: The path name of
the client public key certificate file.
--ssl-key
: The path name of
the client private key file.
For additional security relative to that provided by the default encryption, clients can supply a CA certificate matching the one used by the server and enable host name identity verification. In this way, the server and client place their trust in the same CA certificate and the client verifies that the host to which it connected is the one intended:
To specify the CA certificate, use
--ssl-ca
(or
--ssl-capath
), and specify
--ssl-mode=VERIFY_CA
.
To enable host name identity verification as well, use
--ssl-mode=VERIFY_IDENTITY
rather than
--ssl-mode=VERIFY_CA
.
Host name identity verification with
VERIFY_IDENTITY
does not work with
self-signed certificates that are created automatically by the
server or manually using
mysql_ssl_rsa_setup (see
Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”). Such
self-signed certificates do not contain the server name as the
Common Name value.
Host name identity verification also does not work with certificates that specify the Common Name using wildcards because that name is compared verbatim to the server name.
MySQL also provides these options for client-side SSL control:
--ssl-cipher
: The list of
permissible ciphers for connection encryption.
--ssl-crl
: The path name of
the file containing certificate revocation lists.
(--ssl-crlpath
is similar but specifies the
path name of a directory of certificate revocation-list
files.)
--tls-version
: The permitted
encryption protocols; see
Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”.
Depending on the encryption requirements of the MySQL account used by a client, the client may be required to specify certain options to connect using encryption to the MySQL server.
Suppose that you want to connect using an account that has no
special encryption requirements or that was created using a
CREATE USER
statement that
included the REQUIRE SSL
clause. Assuming
that the server supports encrypted connections, a client can
connect using encryption with no
--ssl-mode
option or with an
explicit --ssl-mode=PREFFERED
option:
mysql
Or:
mysql --ssl-mode=PREFERRED
For an account created with a REQUIRE SSL
clause, the connection attempt fails if an encrypted connection
cannot be established. For an account with no special encryption
requirements, the attempt falls back to an unencrypted
connection if an encrypted connection cannot be established. To
prevent fallback and fail if an encrypted connection cannot be
obtained, connect like this:
mysql --ssl-mode=REQUIRED
If the account has more stringent security requirements, other options must be specified to establish an encrypted connection:
For accounts created with a REQUIRE X509
clause, clients must specify at least
--ssl-cert
and
--ssl-key
. In addition,
--ssl-ca
(or
--ssl-capath
) is recommended
so that the public certificate provided by the server can be
verified. For example:
mysql --ssl-ca=ca.pem \ --ssl-cert=client-cert.pem \ --ssl-key=client-key.pem
For accounts created with a REQUIRE
ISSUER
or REQUIRE SUBJECT
clause, the encryption requirements are the same as for
REQUIRE X509
, but the certificate must
match the issue or subject, respectively, specified in the
account definition.
For additional information about the REQUIRE
clause, see Section 13.7.1.2, “CREATE USER Statement”.
To prevent use of encryption and override other
--ssl-
options,
invoke the client program with
xxx
--ssl-mode=DISABLED
:
mysql --ssl-mode=DISABLED
To determine whether the current connection with the server uses
encryption, check the session value of the
Ssl_cipher
status variable. If
the value is empty, the connection is not encrypted. Otherwise,
the connection is encrypted and the value indicates the
encryption cipher. For example:
mysql> SHOW SESSION STATUS LIKE 'Ssl_cipher';
+---------------+---------------------------+
| Variable_name | Value |
+---------------+---------------------------+
| Ssl_cipher | DHE-RSA-AES128-GCM-SHA256 |
+---------------+---------------------------+
For the mysql client, an alternative is to
use the STATUS
or \s
command and check the SSL
line:
mysql> \s
...
SSL: Not in use
...
Or:
mysql> \s
...
SSL: Cipher in use is DHE-RSA-AES128-GCM-SHA256
...
For some MySQL deployments it may be not only desirable but mandatory to use encrypted connections (for example, to satisfy regulatory requirements). This section discusses configuration settings that enable you to do this. These levels of control are available:
You can configure the server to require the clients connect using encrypted connections.
You can invoke individual client programs to require an encrypted connection, even if the server permits but does not require encryption.
You can configure individual MySQL accounts to be usable only over encrypted connections.
To require that clients connect using encrypted connections,
enable the
require_secure_transport
system
variable. For example, put these lines in the server
my.cnf
file:
[mysqld] require_secure_transport=ON
With require_secure_transport
enabled, client connections to the server are required to use
some form of secure transport, and the server permits only
TCP/IP connections that use SSL, or connections that use a
socket file (on Unix) or shared memory (on Windows). The server
rejects nonsecure connection attempts, which fail with an
ER_SECURE_TRANSPORT_REQUIRED
error.
To invoke a client program such that it requires an encrypted
connection whether or not the server requires encryption, use an
--ssl-mode
option value of
REQUIRED
, VERIFY_CA
, or
VERIFY_IDENTITY
. For example:
mysql --ssl-mode=REQUIRED mysqldump --ssl-mode=VERIFY_CA mysqladmin --ssl-mode=VERIFY_IDENTITY
To configure a MySQL account to be usable only over encrypted
connections, include a REQUIRE
clause in the
CREATE USER
statement that
creates the account, specifying in that clause the encryption
characteristics you require. For example, to require an
encrypted connection and the use of a valid X.509 certificate,
use REQUIRE X509
:
CREATE USER 'jeffrey'@'localhost' REQUIRE X509;
For additional information about the REQUIRE
clause, see Section 13.7.1.2, “CREATE USER Statement”.
To modify existing accounts that have no encryption
requirements, use the ALTER USER
statement.
MySQL supports multiple TLS protocols and ciphers, and enables configuring which protocols and ciphers to permit for encrypted connections. It is also possible to determine which protocol and cipher the current session uses.
MySQL supports encrypted connections using the TLSv1, TLSv1.1, and TLSv1.2 protocols, listed in order from less secure to more secure. The set of protocols actually permitted for connections is subject to multiple factors:
MySQL configuration. Permitted TLS protocols can be configured on both the server side and client side to include only a subset of the supported TLS protocols. The configuration on both sides must include at least one protocol in common or connection attempts cannot negotiate a protocol to use. For details, see Connection TLS Protocol Negotiation.
System-wide host configuration. The host system may permit only certain TLS protocols, which means that MySQL connections cannot use nonpermitted protocols even if MySQL itself permits them:
Suppose that MySQL configuration permits TLSv1, TLSv1.1, and TLSv1.2, but your host system configuration permits only connections that use TLSv1.2 or higher. In this case, you cannot establish MySQL connections that use TLSv1 or TLSv1.1, even though MySQL is configured to permit them, because the host system does not permit them.
If MySQL configuration permits TLSv1, TLSv1.1, and TLSv1.2, but your host system configuration permits only connections that use TLSv1.3 or higher, you cannot establish MySQL connections at all, because no protocol permitted by MySQL is permitted by the host system.
Workarounds for this issue include:
Change the system-wide host configuration to permit
additional TLS protocols. Consult your operating system
documentation for instructions. For example, your system
may have an /etc/ssl/openssl.cnf
file
that contains these lines to restrict TLS protocols to
TLSv1.2 or higher:
[system_default_sect] MinProtocol = TLSv1.2
Changing the value to a lower protocol version or
None
makes the system more
permissive. This workaround has the disadvantage that
permitting lower (less secure) protocols may have
adverse security consequences.
If you cannot or prefer not to change the host system TLS configuration, change MySQL applications to use higher (more secure) TLS protocols that are permitted by the host system. This may not be possible for older versions of MySQL that support only lower protocol versions. For example, TLSv1 is the only supported protocol prior to MySQL 5.6.46, so attempts to connect to a pre-5.6.46 server fail even if the client is from a newer MySQL version that supports higher protocol versions. In such cases, an upgrade to a version of MySQL that supports additional TLS versions may be required.
The SSL library. If the SSL library does not support a particular protocol, neither does MySQL, and any parts of the following discussion that specify that protocol do not apply.
When compiled using OpenSSL 1.0.1 or higher, MySQL supports the TLSv1, TLSv1.1, and TLSv1.2 protocols.
When compiled using yaSSL, MySQL supports the TLSv1 and TLSv1.1 protocols.
It is possible to compile MySQL using yaSSL as an alternative to OpenSSL only prior to MySQL 5.7.28. As of MySQL 5.7.28, support for yaSSL is removed and all MySQL builds use OpenSSL.
On the server side, the value of the
tls_version
system variable
determines which TLS protocols a MySQL server permits for
encrypted connections. The
tls_version
value applies to
connections from clients and from slave servers using regular
master/slave replication. The variable value is a list of one or
more comma-separated protocol versions from this list (not
case-sensitive): TLSv1, TLSv1.1, TLSv1.2. By default, this
variable lists all protocols supported by the SSL library used
to compile MySQL (TLSv1,TLSv1.1,TLSv1.2
for
OpenSSL, TLSv1,TLSv1.1
for yaSSL). To
determine the value of
tls_version
at runtime, use
this statement:
mysql> SHOW GLOBAL VARIABLES LIKE 'tls_version';
+---------------+-----------------------+
| Variable_name | Value |
+---------------+-----------------------+
| tls_version | TLSv1,TLSv1.1,TLSv1.2 |
+---------------+-----------------------+
To change the value of
tls_version
, set it at server
startup. For example, to permit connections that use the TLSv1.1
or TLSv1.2 protocol, but prohibit connections that use the
less-secure TLSv1 protocol, use these lines in the server
my.cnf
file:
[mysqld] tls_version=TLSv1.1,TLSv1.2
To be even more restrictive and permit only TLSv1.2 connections,
set tls_version
like this
(assuming that your server is compiled using OpenSSL because
yaSSL does not support TLSv1.2):
[mysqld] tls_version=TLSv1.2
On the client side, the
--tls-version
option specifies
which TLS protocols a client program permits for connections to
the server. The format of the option value is the same as for
the tls_version
system variable
described previously (a list of one or more comma-separated
protocol versions).
For master/slave replication, the
MASTER_TLS_VERSION
option for the
CHANGE MASTER TO
statement
specifies which TLS protocols a slave server permits for
connections to the master. The format of the option value is the
same as for the tls_version
system variable described previously. See
Section 16.3.8, “Setting Up Replication to Use Encrypted Connections”.
The protocols that can be specified for
MASTER_TLS_VERSION
depend on the SSL library.
This option is independent of and not affected by the server
tls_version
value. For example,
a server that acts as a replication slave can be configured with
tls_version
set to TLSv1.2 to
permit only incoming connections that use TLSv1.2, but also
configured with MASTER_TLS_VERSION
set to
TLSv1.1 to permit only TLSv1.1 for outgoing slave connections to
the master.
TLS protocol configuration affects which protocol a given connection uses, as described in Connection TLS Protocol Negotiation.
Permitted protocols should be chosen such as not to leave “holes” in the list. For example, these server configuration values do not have holes:
tls_version=TLSv1,TLSv1.1,TLSv1.2 tls_version=TLSv1.1,TLSv1.2 tls_version=TLSv1.2
This value does have a hole and should not be used:
tls_version=TLSv1,TLSv1.2 (TLSv1.1 is missing)
The prohibition on holes also applies in other configuration contexts, such as for clients or replication slaves.
The list of permitted protocols should not be empty. If you set a TLS version parameter to the empty string, encrypted connections cannot be established:
tls_version
: The server
does not permit encrypted incoming connections.
--tls-version
: The client
does not permit encrypted outgoing connections to the
server.
MASTER_TLS_VERSION
: The replication slave
does not permit encrypted outgoing connections to the
master.
A default set of ciphers applies to encrypted connections, which can be overridden by explicitly configuring the permitted ciphers. During connection establishment, both sides of a connection must permit some cipher in common or the connection fails. Of the permitted ciphers common to both sides, the SSL library chooses the one supported by the provided certificate that has the highest priority.
To specify a cipher or ciphers for encrypted connections, use
the --ssl-cipher
option, which
is available for the server and for client programs.
For master/slave replication, the
MASTER_SSL_CIPHER
option for the
CHANGE MASTER TO
statement
specifies which ciphers a slave server permits for connections
to the master. See
Section 16.3.8, “Setting Up Replication to Use Encrypted Connections”.
A given cipher may work only with particular TLS protocols, which affects the TLS protocol negotiation process. See Connection TLS Protocol Negotiation.
To determine which ciphers a given server supports, check the
session value of the
Ssl_cipher_list
status
variable:
SHOW SESSION STATUS LIKE 'Ssl_cipher_list';
The Ssl_cipher_list
status
variable lists the possible SSL ciphers (empty for non-SSL
connections). The set of available ciphers depends on your MySQL
version and whether MySQL was compiled using OpenSSL or yaSSL,
and (for OpenSSL) the library version used to compile MySQL.
MySQL passes a default cipher list to the SSL library.
MySQL passes this default cipher list to OpenSSL:
ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES128-SHA256 ECDHE-RSA-AES128-SHA256 ECDHE-ECDSA-AES256-SHA384 ECDHE-RSA-AES256-SHA384 DHE-RSA-AES128-GCM-SHA256 DHE-DSS-AES128-GCM-SHA256 DHE-RSA-AES128-SHA256 DHE-DSS-AES128-SHA256 DHE-DSS-AES256-GCM-SHA384 DHE-RSA-AES256-SHA256 DHE-DSS-AES256-SHA256 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-GCM-SHA256 DH-DSS-AES128-GCM-SHA256 ECDH-ECDSA-AES128-GCM-SHA256 AES256-GCM-SHA384 DH-DSS-AES256-GCM-SHA384 ECDH-ECDSA-AES256-GCM-SHA384 AES128-SHA256 DH-DSS-AES128-SHA256 ECDH-ECDSA-AES128-SHA256 AES256-SHA256 DH-DSS-AES256-SHA256 ECDH-ECDSA-AES256-SHA384 AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DHE-RSA-AES256-GCM-SHA384 DH-RSA-AES128-GCM-SHA256 ECDH-RSA-AES128-GCM-SHA256 DH-RSA-AES256-GCM-SHA384 ECDH-RSA-AES256-GCM-SHA384 DH-RSA-AES128-SHA256 ECDH-RSA-AES128-SHA256 DH-RSA-AES256-SHA256 ECDH-RSA-AES256-SHA384 ECDHE-RSA-AES128-SHA ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES256-SHA ECDHE-ECDSA-AES256-SHA DHE-DSS-AES128-SHA DHE-RSA-AES128-SHA TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA AES128-SHA DH-DSS-AES128-SHA ECDH-ECDSA-AES128-SHA AES256-SHA DH-DSS-AES256-SHA ECDH-ECDSA-AES256-SHA DH-RSA-AES128-SHA ECDH-RSA-AES128-SHA DH-RSA-AES256-SHA ECDH-RSA-AES256-SHA DES-CBC3-SHA
MySQL passes this default cipher list to yaSSL:
DHE-RSA-AES256-SHA DHE-RSA-AES128-SHA AES128-RMD DES-CBC3-RMD DHE-RSA-AES256-RMD DHE-RSA-AES128-RMD DHE-RSA-DES-CBC3-RMD AES256-SHA RC4-SHA RC4-MD5 DES-CBC3-SHA DES-CBC-SHA EDH-RSA-DES-CBC3-SHA EDH-RSA-DES-CBC-SHA AES128-SHA:AES256-RMD
As of MySQL 5.7.10, these cipher restrictions are in place:
The following ciphers are permanently restricted:
!DHE-DSS-DES-CBC3-SHA !DHE-RSA-DES-CBC3-SHA !ECDH-RSA-DES-CBC3-SHA !ECDH-ECDSA-DES-CBC3-SHA !ECDHE-RSA-DES-CBC3-SHA !ECDHE-ECDSA-DES-CBC3-SHA
The following categories of ciphers are permanently restricted:
!aNULL !eNULL !EXPORT !LOW !MD5 !DES !RC2 !RC4 !PSK !SSLv3
If the server is started with an
--ssl-cert
option specifying a
certificate that uses any of the preceding restricted ciphers or
cipher categories, the server starts with support for encrypted
connections disabled.
Connection attempts in MySQL negotiate use of the highest TLS protocol version available on both sides for which a protocol-compatible encryption cipher is available on both sides. The negotiation process depends on factors such as the SSL library used to compile the server and client, the TLS protocol and encryption cipher configuration, and which key size is used:
For a connection attempt to succeed, the server and client TLS protocol configuration must permit some protocol in common.
Similarly, the server and client encryption cipher configuration must permit some cipher in common. A given cipher may work only with particular TLS protocols, so a protocol available to the negotiation process is not chosen unless there is also a compatible cipher.
If the server and client are compiled using OpenSSL, TLSv1.2
is used if possible. If either or both the server and client
are compiled using yaSSL, TLSv1.1 is used if possible.
(“Possible” means that server and client
configuration both must permit the indicated protocol, and
both must also permit some protocol-compatible encryption
cipher.) Otherwise, MySQL continues through the list of
available protocols, proceeding from more secure protocols
to less secure. Negotiation order is independent of the
order in which protocols are configured. For example,
negotiation order is the same regardless of whether
tls_version
has a value of
TLSv1,TLSv1.1,TLSv1.2
or
TLSv1.2,TLSv1.1,TLSv1
.
Prior to MySQL 5.7.10, MySQL supports only TLSv1, for both OpenSSL and yaSSL, and no system variable or client option exist for specifying which TLS protocols to permit.
TLSv1.2 does not work with all ciphers that have a key size
of 512 bits or less. To use this protocol with such a key,
use --ssl-cipher
to specify
the cipher name explicitly:
AES128-SHA AES128-SHA256 AES256-SHA AES256-SHA256 CAMELLIA128-SHA CAMELLIA256-SHA DES-CBC3-SHA DHE-RSA-AES256-SHA RC4-MD5 RC4-SHA SEED-SHA
For better security, use a certificate with an RSA key size of at least 2048 bits.
If the server and client do not have a permitted protocol in common, and a protocol-compatible cipher in common, the server terminates the connection request. Examples:
If the server is configured with
tls_version=TLSv1.1,TLSv1.2
:
Connection attempts fail for clients invoked with
--tls-version=TLSv1
, and
for older clients that support only TLSv1.
Similarly, connection attempts fail for replication
slaves configured with MASTER_TLS_VERSION =
'TLSv1'
, and for older slaves that support
only TLSv1.
If the server is configured with
tls_version=TLSv1
or is an
older server that supports only TLSv1:
Connection attempts fail for clients invoked with
--tls-version=TLSv1.1,TLSv1.2
.
Similarly, connection attempts fail for replication
slaves configured with MASTER_TLS_VERSION =
'TLSv1.1,TLSv1.2'
.
MySQL permits specifying a list of protocols to support. This
list is passed directly down to the underlying SSL library and
is ultimately up to that library what protocols it actually
enables from the supplied list. Please refer to the MySQL source
code and the OpenSSL
SSL_CTX_new()
documentation for information about how the SSL library handles
this.
To determine which encryption TLS protocol and cipher the
current session uses, check the session values of the
Ssl_version
and
Ssl_cipher
status variables:
mysql>SELECT * FROM performance_schema.session_status
WHERE VARIABLE_NAME IN ('Ssl_version','Ssl_cipher');
+---------------+---------------------------+ | VARIABLE_NAME | VARIABLE_VALUE | +---------------+---------------------------+ | Ssl_cipher | DHE-RSA-AES128-GCM-SHA256 | | Ssl_version | TLSv1.2 | +---------------+---------------------------+
If the connection is not encrypted, both variables have an empty value.
The following discussion describes how to create the files required for SSL and RSA support in MySQL. File creation can be performed using facilities provided by MySQL itself, or by invoking the openssl command directly.
SSL certificate and key files enable MySQL to support encrypted connections using SSL. See Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
RSA key files enable MySQL to support secure password exchange
over unencrypted connections for accounts authenticated by the
sha256_password
plugin. See
Section 6.4.1.5, “SHA-256 Pluggable Authentication”.
MySQL provides these ways to create the SSL certificate and key files and RSA key-pair files required to support encrypted connections using SSL and secure password exchange using RSA over unencrypted connections, if those files are missing:
The server can autogenerate these files at startup, for MySQL distributions compiled using OpenSSL.
Users can invoke the mysql_ssl_rsa_setup utility manually.
For some distribution types, such as RPM packages, mysql_ssl_rsa_setup invocation occurs during data directory initialization. In this case, the MySQL distribution need not have been compiled using OpenSSL as long as the openssl command is available.
Server autogeneration and mysql_ssl_rsa_setup help lower the barrier to using SSL by making it easier to generate the required files. However, certificates generated by these methods are self-signed, which may not be very secure. After you gain experience using such files, consider obtaining certificate/key material from a registered certificate authority.
For MySQL distributions compiled using OpenSSL, the MySQL
server has the capability of automatically generating missing
SSL and RSA files at startup. The
auto_generate_certs
and
sha256_password_auto_generate_rsa_keys
system variables control automatic generation of these files.
These variables are enabled by default. They can be enabled at
startup and inspected but not set at runtime.
At startup, the server automatically generates server-side and
client-side SSL certificate and key files in the data
directory if the
auto_generate_certs
system
variable is enabled, no SSL options other than
--ssl
are specified, and the
server-side SSL files are missing from the data directory.
These files enable encrypted client connections using SSL; see
Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
The server checks the data directory for SSL files with the following names:
ca.pem server-cert.pem server-key.pem
If any of those files are present, the server creates no SSL files. Otherwise, it creates them, plus some additional files:
ca.pem Self-signed CA certificate ca-key.pem CA private key server-cert.pem Server certificate server-key.pem Server private key client-cert.pem Client certificate client-key.pem Client private key
If the server autogenerates SSL files, it uses the names
of the ca.pem
,
server-cert.pem
, and
server-key.pem
files to set the
corresponding system variables
(ssl_ca
,
ssl_cert
,
ssl_key
).
At startup, the server automatically generates RSA
private/public key-pair files in the data directory if all of
these conditions are true: The
sha256_password_auto_generate_rsa_keys
system variable is enabled; no RSA options are specified; the
RSA files are missing from the data directory. These key-pair
files enable secure password exchange using RSA over
unencrypted connections for accounts authenticated by the
sha256_password
plugin; see
Section 6.4.1.5, “SHA-256 Pluggable Authentication”.
The server checks the data directory for RSA files with the following names:
private_key.pem Private member of private/public key pair public_key.pem Public member of private/public key pair
If any of these files are present, the server creates no RSA files. Otherwise, it creates them.
If the server autogenerates the RSA files, it uses their
names to set the corresponding system variables
(sha256_password_private_key_path
,
sha256_password_public_key_path
).
MySQL distributions include a mysql_ssl_rsa_setup utility that can be invoked manually to generate SSL and RSA files. This utility is included with all MySQL distributions, but it does require that the openssl command be available. For usage instructions, see Section 4.4.5, “mysql_ssl_rsa_setup — Create SSL/RSA Files”.
SSL and RSA files created automatically by the server or by invoking mysql_ssl_rsa_setup have these characteristics:
SSL and RSA keys are have a size of 2048 bits.
The SSL CA certificate is self signed.
The SSL server and client certificates are signed with the
CA certificate and key, using the
sha256WithRSAEncryption
signature
algorithm.
SSL certificates use these Common Name (CN) values, with the appropriate certificate type (CA, Server, Client):
ca.pem: MySQL_Server_suffix
_Auto_Generated_CA_Certificate server-cert.pm: MySQL_Server_suffix
_Auto_Generated_Server_Certificate client-cert.pm: MySQL_Server_suffix
_Auto_Generated_Client_Certificate
The suffix
value is based on
the MySQL version number. For files generated by
mysql_ssl_rsa_setup, the suffix can be
specified explicitly using the
--suffix
option.
For files generated by the server, if the resulting CN
values exceed 64 characters, the
_
portion of the name is omitted.
suffix
SSL files have blank values for Country (C), State or Province (ST), Organization (O), Organization Unit Name (OU) and email address.
SSL files created by the server or by mysql_ssl_rsa_setup are valid for ten years from the time of generation.
RSA files do not expire.
SSL files have different serial numbers for each certificate/key pair (1 for CA, 2 for Server, 3 for Client).
Files created automatically by the server are owned by the
account that runs the server. Files created using
mysql_ssl_rsa_setup are owned by the
user who invoked that program. This can be changed on
systems that support the chown()
system
call if the program is invoked by root
and the --uid
option is given to specify the user who should own the
files.
On Unix and Unix-like systems, the file access mode is 644 for certificate files (that is, world readable) and 600 for key files (that is, accessible only by the account that runs the server).
To see the contents of an SSL certificate (for example, to check the range of dates over which it is valid), invoke openssl directly:
openssl x509 -text -in ca.pem openssl x509 -text -in server-cert.pem openssl x509 -text -in client-cert.pem
It is also possible to check SSL certificate expiration information using this SQL statement:
mysql> SHOW STATUS LIKE 'Ssl_server_not%';
+-----------------------+--------------------------+
| Variable_name | Value |
+-----------------------+--------------------------+
| Ssl_server_not_after | Apr 28 14:16:39 2027 GMT |
| Ssl_server_not_before | May 1 14:16:39 2017 GMT |
+-----------------------+--------------------------+
This section describes how to use the openssl command to set up SSL certificate and key files for use by MySQL servers and clients. The first example shows a simplified procedure such as you might use from the command line. The second shows a script that contains more detail. The first two examples are intended for use on Unix and both use the openssl command that is part of OpenSSL. The third example describes how to set up SSL files on Windows.
There are easier alternatives to generating the files required for SSL than the procedure described here: Let the server autogenerate them or use the mysql_ssl_rsa_setup program. See Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
Whatever method you use to generate the certificate and key files, the Common Name value used for the server and client certificates/keys must each differ from the Common Name value used for the CA certificate. Otherwise, the certificate and key files will not work for servers compiled using OpenSSL. A typical error in this case is:
ERROR 2026 (HY000): SSL connection error: error:00000001:lib(0):func(0):reason(1)
The following example shows a set of commands to create MySQL server and client certificate and key files. You will need to respond to several prompts by the openssl commands. To generate test files, you can press Enter to all prompts. To generate files for production use, you should provide nonempty responses.
# Create clean environment rm -rf newcerts mkdir newcerts && cd newcerts # Create CA certificate openssl genrsa 2048 > ca-key.pem openssl req -new -x509 -nodes -days 3600 \ -key ca-key.pem -out ca.pem # Create server certificate, remove passphrase, and sign it # server-cert.pem = public key, server-key.pem = private key openssl req -newkey rsa:2048 -days 3600 \ -nodes -keyout server-key.pem -out server-req.pem openssl rsa -in server-key.pem -out server-key.pem openssl x509 -req -in server-req.pem -days 3600 \ -CA ca.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem # Create client certificate, remove passphrase, and sign it # client-cert.pem = public key, client-key.pem = private key openssl req -newkey rsa:2048 -days 3600 \ -nodes -keyout client-key.pem -out client-req.pem openssl rsa -in client-key.pem -out client-key.pem openssl x509 -req -in client-req.pem -days 3600 \ -CA ca.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem
After generating the certificates, verify them:
openssl verify -CAfile ca.pem server-cert.pem client-cert.pem
You should see a response like this:
server-cert.pem: OK client-cert.pem: OK
To see the contents of a certificate (for example, to check the range of dates over which a certificate is valid), invoke openssl like this:
openssl x509 -text -in ca.pem openssl x509 -text -in server-cert.pem openssl x509 -text -in client-cert.pem
Now you have a set of files that can be used as follows:
ca.pem
: Use this as the argument to
--ssl-ca
on the server and
client sides. (The CA certificate, if used, must be the
same on both sides.)
server-cert.pem
,
server-key.pem
: Use these as the
arguments to --ssl-cert
and --ssl-key
on the
server side.
client-cert.pem
,
client-key.pem
: Use these as the
arguments to --ssl-cert
and --ssl-key
on the
client side.
For additional usage instructions, see Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
Here is an example script that shows how to set up SSL certificate and key files for MySQL. After executing the script, use the files for SSL connections as described in Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
DIR=`pwd`/openssl PRIV=$DIR/private mkdir $DIR $PRIV $DIR/newcerts cp /usr/share/ssl/openssl.cnf $DIR replace ./demoCA $DIR -- $DIR/openssl.cnf # Create necessary files: $database, $serial and $new_certs_dir # directory (optional) touch $DIR/index.txt echo "01" > $DIR/serial # # Generation of Certificate Authority(CA) # openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/ca.pem \ -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/finley/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ................++++++ # .........++++++ # writing new private key to '/home/finley/openssl/private/cakey.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL admin # Email Address []: # # Create server request and key # openssl req -new -keyout $DIR/server-key.pem -out \ $DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/finley/openssl/openssl.cnf # Generating a 1024 bit RSA private key # ..++++++ # ..........++++++ # writing new private key to '/home/finley/openssl/server-key.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL server # Email Address []: # # Please enter the following 'extra' attributes # to be sent with your certificate request # A challenge password []: # An optional company name []: # # Remove the passphrase from the key # openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem # # Sign server cert # openssl ca -cert $DIR/ca.pem -policy policy_anything \ -out $DIR/server-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/server-req.pem # Sample output: # Using configuration from /home/finley/openssl/openssl.cnf # Enter PEM pass phrase: # Check that the request matches the signature # Signature ok # The Subjects Distinguished Name is as follows # countryName :PRINTABLE:'FI' # organizationName :PRINTABLE:'MySQL AB' # commonName :PRINTABLE:'MySQL admin' # Certificate is to be certified until Sep 13 14:22:46 2003 GMT # (365 days) # Sign the certificate? [y/n]:y # # # 1 out of 1 certificate requests certified, commit? [y/n]y # Write out database with 1 new entries # Data Base Updated # # Create client request and key # openssl req -new -keyout $DIR/client-key.pem -out \ $DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf # Sample output: # Using configuration from /home/finley/openssl/openssl.cnf # Generating a 1024 bit RSA private key # .....................................++++++ # .............................................++++++ # writing new private key to '/home/finley/openssl/client-key.pem' # Enter PEM pass phrase: # Verifying password - Enter PEM pass phrase: # ----- # You are about to be asked to enter information that will be # incorporated into your certificate request. # What you are about to enter is what is called a Distinguished Name # or a DN. # There are quite a few fields but you can leave some blank # For some fields there will be a default value, # If you enter '.', the field will be left blank. # ----- # Country Name (2 letter code) [AU]:FI # State or Province Name (full name) [Some-State]:. # Locality Name (eg, city) []: # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB # Organizational Unit Name (eg, section) []: # Common Name (eg, YOUR name) []:MySQL user # Email Address []: # # Please enter the following 'extra' attributes # to be sent with your certificate request # A challenge password []: # An optional company name []: # # Remove the passphrase from the key # openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem # # Sign client cert # openssl ca -cert $DIR/ca.pem -policy policy_anything \ -out $DIR/client-cert.pem -config $DIR/openssl.cnf \ -infiles $DIR/client-req.pem # Sample output: # Using configuration from /home/finley/openssl/openssl.cnf # Enter PEM pass phrase: # Check that the request matches the signature # Signature ok # The Subjects Distinguished Name is as follows # countryName :PRINTABLE:'FI' # organizationName :PRINTABLE:'MySQL AB' # commonName :PRINTABLE:'MySQL user' # Certificate is to be certified until Sep 13 16:45:17 2003 GMT # (365 days) # Sign the certificate? [y/n]:y # # # 1 out of 1 certificate requests certified, commit? [y/n]y # Write out database with 1 new entries # Data Base Updated # # Create a my.cnf file that you can use to test the certificates # cat <<EOF > $DIR/my.cnf [client] ssl-ca=$DIR/ca.pem ssl-cert=$DIR/client-cert.pem ssl-key=$DIR/client-key.pem [mysqld] ssl-ca=$DIR/ca.pem ssl-cert=$DIR/server-cert.pem ssl-key=$DIR/server-key.pem EOF
Download OpenSSL for Windows if it is not installed on your system. An overview of available packages can be seen here:
http://www.slproweb.com/products/Win32OpenSSL.html
Choose the Win32 OpenSSL Light or Win64 OpenSSL Light package,
depending on your architecture (32-bit or 64-bit). The default
installation location will be
C:\OpenSSL-Win32
or
C:\OpenSSL-Win64
, depending on which
package you downloaded. The following instructions assume a
default location of C:\OpenSSL-Win32
.
Modify this as necessary if you are using the 64-bit package.
If a message occurs during setup indicating
'...critical component is missing: Microsoft Visual
C++ 2008 Redistributables'
, cancel the setup and
download one of the following packages as well, again
depending on your architecture (32-bit or 64-bit):
Visual C++ 2008 Redistributables (x86), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF
Visual C++ 2008 Redistributables (x64), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6
After installing the additional package, restart the OpenSSL setup procedure.
During installation, leave the default
C:\OpenSSL-Win32
as the install path, and
also leave the default option 'Copy OpenSSL DLL files
to the Windows system directory'
selected.
When the installation has finished, add
C:\OpenSSL-Win32\bin
to the Windows
System Path variable of your server (depending on your version
of Windows, the following path-setting instructions might
differ slightly):
On the Windows desktop, right-click the My Computer icon, and select .
Select the
tab from the menu that appears, and click the button.Under System Variables, select , then click the button. The dialogue should appear.
Add ';C:\OpenSSL-Win32\bin'
to the end
(notice the semicolon).
Press OK 3 times.
Check that OpenSSL was correctly integrated into the Path variable by opening a new command console (Start>Run>cmd.exe) and verifying that OpenSSL is available:
Microsoft Windows [Version ...] Copyright (c) 2006 Microsoft Corporation. All rights reserved. C:\Windows\system32>cd \
C:\>openssl
OpenSSL>exit
<<< If you see the OpenSSL prompt, installation was successful. C:\>
After OpenSSL has been installed, use instructions similar to those from Example 1 (shown earlier in this section), with the following changes:
Change the following Unix commands:
# Create clean environment rm -rf newcerts mkdir newcerts && cd newcerts
On Windows, use these commands instead:
# Create clean environment md c:\newcerts cd c:\newcerts
When a '\'
character is shown at the
end of a command line, this '\'
character must be removed and the command lines entered
all on a single line.
After generating the certificate and key files, to use them for SSL connections, see Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
This section describes how to use the openssl
command to set up the RSA key files that enable MySQL to support
secure password exchange over unencrypted connections for
accounts authenticated by the sha256_password
plugin.
There are easier alternatives to generating the files required for RSA than the procedure described here: Let the server autogenerate them or use the mysql_ssl_rsa_setup program. See Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
To create the RSA private and public key-pair files, run these commands while logged into the system account used to run the MySQL server so the files will be owned by that account:
openssl genrsa -out private_key.pem 2048 openssl rsa -in private_key.pem -pubout -out public_key.pem
Those commands create 2,048-bit keys. To create stronger keys, use a larger value.
Then set the access modes for the key files. The private key should be readable only by the server, whereas the public key can be freely distributed to client users:
chmod 400 private_key.pem chmod 444 public_key.pem
MySQL can be compiled using OpenSSL or yaSSL, both of which enable encrypted connections based on the OpenSSL API:
MySQL Enterprise Edition binary distributions are compiled using OpenSSL. It is not possible to use yaSSL with MySQL Enterprise Edition.
MySQL Community Edition binary distributions are compiled using yaSSL.
MySQL Community Edition source distributions can be compiled using either OpenSSL or yaSSL (see Section 2.9.6, “Configuring SSL Library Support”).
It is possible to compile MySQL using yaSSL as an alternative to OpenSSL only prior to MySQL 5.7.28. As of MySQL 5.7.28, support for yaSSL is removed and all MySQL builds use OpenSSL.
OpenSSL and yaSSL offer the same basic functionality, but MySQL distributions compiled using OpenSSL have additional features:
OpenSSL supports TLSv1, TLSv1.1, and TLSv1.2 protocols. yaSSL supports only TLSv1 and TLSv1.1 protocols.
OpenSSL supports a more flexible syntax for specifying ciphers
for the --ssl-cipher
option,
and supports a wider range of encryption ciphers from which to
choose. See Command Options for Encrypted Connections,
and Section 6.3.2, “Encrypted Connection TLS Protocols and Ciphers”.
OpenSSL supports the
--ssl-capath
. MySQL
distributions compiled using yaSSL do not because yaSSL does
not look in any directory and do not follow a chained
certificate tree. yaSSL requires that all components of the CA
certificate tree be contained within a single CA certificate
tree and that each certificate in the file has a unique
SubjectName value. To work around this limitation, concatenate
the individual certificate files comprising the certificate
tree into a new file and specify that file as the value of the
--ssl-ca
option.
OpenSSL supports the
--ssl-crl
, and
--ssl-crlpath
options.
Distributions compiled using yaSSL do not because revocation
lists do not work with yaSSL. (yaSSL accepts these options but
silently ignores them.)
Accounts that authenticate using the
sha256_password
plugin can use RSA key
files for secure password exchange over unencrypted
connections. See
Section 6.4.1.5, “SHA-256 Pluggable Authentication”.
The server can automatically generate missing SSL and RSA certificate and key files at startup. See Section 6.3.3.1, “Creating SSL and RSA Certificates and Keys using MySQL”.
OpenSSL supports more encryption modes for the
AES_ENCRYPT()
and
AES_DECRYPT()
functions. See
Section 12.13, “Encryption and Compression Functions”
Certain OpenSSL-related system and status variables are present only if MySQL was compiled using OpenSSL:
To determine whether a server was compiled using OpenSSL, test the existence of any of those variables. For example, this statement returns a row if OpenSSL was used and an empty result if yaSSL was used:
SHOW STATUS LIKE 'Rsa_public_key';
This section describes how to get an encrypted connection to a
remote MySQL server with SSH. The information was provided by
David Carlson <dcarlson@mplcomm.com>
.
Install an SSH client on your Windows machine. For a comparison of SSH clients, see http://en.wikipedia.org/wiki/Comparison_of_SSH_clients.
Start your Windows SSH client. Set Host_Name =
.
Set
yourmysqlserver_URL_or_IP
userid=
to log in to your server. This your_userid
userid
value
might not be the same as the user name of your MySQL account.
Set up port forwarding. Either do a remote forward (Set
local_port: 3306
, remote_host:
,
yourmysqlservername_or_ip
remote_port: 3306
) or a local forward (Set
port: 3306
, host:
localhost
, remote port: 3306
).
Save everything, otherwise you will have to redo it the next time.
Log in to your server with the SSH session you just created.
On your Windows machine, start some ODBC application (such as Access).
Create a new file in Windows and link to MySQL using the ODBC
driver the same way you normally do, except type in
localhost
for the MySQL host server, not
yourmysqlservername
.
At this point, you should have an ODBC connection to MySQL, encrypted using SSH.
MySQL includes several plugins that implement security features:
Plugins for authenticating attempts by clients to connect to MySQL Server. Plugins are available for several authentication protocols. For general discussion of the authentication process, see Section 6.2.13, “Pluggable Authentication”. For characteristics of specific authentication plugins, see Section 6.4.1, “Authentication Plugins”.
A password-validation plugin for implementing password strength policies and assessing the strength of potential passwords. See Section 6.4.3, “The Password Validation Plugin”.
Keyring plugins that provide secure storage for sensitive information. See Section 6.4.4, “The MySQL Keyring”.
(MySQL Enterprise Edition only) MySQL Enterprise Audit, implemented using a server plugin, uses the open MySQL Audit API to enable standard, policy-based monitoring and logging of connection and query activity executed on specific MySQL servers. Designed to meet the Oracle audit specification, MySQL Enterprise Audit provides an out of box, easy to use auditing and compliance solution for applications that are governed by both internal and external regulatory guidelines. See Section 6.4.5, “MySQL Enterprise Audit”.
(MySQL Enterprise Edition only) MySQL Enterprise Firewall, an application-level firewall that enables database administrators to permit or deny SQL statement execution based on matching against whitelists of accepted statement patterns. This helps harden MySQL Server against attacks such as SQL injection or attempts to exploit applications by using them outside of their legitimate query workload characteristics. See Section 6.4.6, “MySQL Enterprise Firewall”.
(MySQL Enterprise Edition only) MySQL Enterprise Data Masking and De-Identification, implemented as a plugin library containing a plugin and a set of user-defined functions. Data masking hides sensitive information by replacing real values with substitutes. MySQL Enterprise Data Masking and De-Identification functions enable masking existing data using several methods such as obfuscation (removing identifying characteristics), generation of formatted random data, and data replacement or substitution. See Section 6.4.7, “MySQL Enterprise Data Masking and De-Identification”.
The following sections describe pluggable authentication methods available in MySQL and the plugins that implement these methods. For general discussion of the authentication process, see Section 6.2.13, “Pluggable Authentication”.
The default plugin is indicated by the value of the
default_authentication_plugin
system variable.
MySQL includes two plugins that implement native authentication;
that is, authentication based on the password hashing methods in
use from before the introduction of pluggable authentication.
This section describes mysql_native_password
,
which implements authentication against the
mysql.user
system table using the native
password hashing method. For information about
mysql_old_password
, which implements
authentication using the older (pre-4.1) native password hashing
method, see
Section 6.4.1.2, “Old Native Pluggable Authentication”. For
information about these password hashing methods, see
Section 6.1.2.4, “Password Hashing in MySQL”.
The following table shows the plugin names on the server and client sides.
Table 6.8 Plugin and Library Names for Native Password Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | mysql_native_password |
Client-side plugin | mysql_native_password |
Library file | None (plugins are built in) |
The following sections provide installation and usage information specific to native pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
The mysql_native_password
plugin exists in
server and client forms:
The server-side plugin is built into the server, need not be loaded explicitly, and cannot be disabled by unloading it.
The client-side plugin is built into the
libmysqlclient
client library and is
available to any program linked against
libmysqlclient
.
MySQL client programs use
mysql_native_password
by default. The
--default-auth
option can be
used as a hint about which client-side plugin the program can
expect to use:
shell> mysql --default-auth=mysql_native_password ...
MySQL includes two plugins that implement native authentication;
that is, authentication based on the password hashing methods in
use from before the introduction of pluggable authentication.
This section describes mysql_old_password
,
which implements authentication against the
mysql.user
system table using the older
(pre-4.1) native password hashing method. For information about
mysql_native_password
, which implements
authentication using the native password hashing method, see
Section 6.4.1.1, “Native Pluggable Authentication”. For
information about these password hashing methods, see
Section 6.1.2.4, “Password Hashing in MySQL”.
Passwords that use the pre-4.1 hashing method are less secure
than passwords that use the native password hashing method and
should be avoided. Pre-4.1 passwords are deprecated and
support for them (including the
mysql_old_password
plugin) was removed in
MySQL 5.7.5. For account upgrade instructions, see
Section 6.4.1.3, “Migrating Away from Pre-4.1 Password Hashing and the mysql_old_password
Plugin”.
The following table shows the plugin names on the server and client sides.
Table 6.9 Plugin and Library Names for Old Native Password Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | mysql_old_password |
Client-side plugin | mysql_old_password |
Library file | None (plugins are built in) |
The following sections provide installation and usage information specific to old native pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
The mysql_old_password
plugin exists in
server and client forms:
The server-side plugin is built into the server, need not be loaded explicitly, and cannot be disabled by unloading it.
The client-side plugin is built into the
libmysqlclient
client library and is
available to any program linked against
libmysqlclient
.
MySQL client programs can use the
--default-auth
option to specify
the mysql_old_password
plugin as a hint
about which client-side plugin the program can expect to use:
shell> mysql --default-auth=mysql_old_password ...
The MySQL server authenticates connection attempts for each
account listed in the mysql.user
system table
using the authentication plugin named in the
plugin
column. If the
plugin
column is empty, the server
authenticates the account as follows:
Before MySQL 5.7, the server uses the
mysql_native_password
or
mysql_old_password
plugin implicitly,
depending on the format of the password hash in the
Password
column. If the
Password
value is empty or a 4.1 password
hash (41 characters), the server uses
mysql_native_password
. If the password
value is a pre-4.1 password hash (16 characters), the server
uses mysql_old_password
. (For additional
information about these hash formats, see
Section 6.1.2.4, “Password Hashing in MySQL”.)
As of MySQL 5.7, the server requires the
plugin
column to be nonempty and disables
accounts that have an empty plugin
value.
Pre-4.1 password hashes and the
mysql_old_password
plugin are deprecated in
MySQL 5.6 and support for them is removed in MySQL 5.7. They
provide a level of security inferior to that offered by 4.1
password hashing and the
mysql_native_password
plugin.
Given the requirement in MySQL 5.7 that the
plugin
column must be nonempty, coupled with
removal of mysql_old_password
support, DBAs
are advised to upgrade accounts as follows:
Upgrade accounts that use
mysql_native_password
implicitly to use
it explicitly
Upgrade accounts that use
mysql_old_password
(either implicitly or
explicitly) to use mysql_native_password
explicitly
The instructions in this section describe how to perform those
upgrades. The result is that no account has an empty
plugin
value and no account uses pre-4.1
password hashing or the mysql_old_password
plugin.
As a variant on these instructions, DBAs might offer users the
choice to upgrade to the sha256_password
plugin, which authenticates using SHA-256 password hashes. For
information about this plugin, see
Section 6.4.1.5, “SHA-256 Pluggable Authentication”.
The following table lists the types of
mysql.user
accounts considered in this
discussion.
plugin Column |
Password Column |
Authentication Result | Upgrade Action |
---|---|---|---|
Empty | Empty | Implicitly uses mysql_native_password |
Assign plugin |
Empty | 4.1 hash | Implicitly uses mysql_native_password |
Assign plugin |
Empty | Pre-4.1 hash | Implicitly uses mysql_old_password |
Assign plugin, rehash password |
mysql_native_password |
Empty | Explicitly uses mysql_native_password |
None |
mysql_native_password |
4.1 hash | Explicitly uses mysql_native_password |
None |
mysql_old_password |
Empty | Explicitly uses mysql_old_password |
Upgrade plugin |
mysql_old_password |
Pre-4.1 hash | Explicitly uses mysql_old_password |
Upgrade plugin, rehash password |
Accounts corresponding to lines for the
mysql_native_password
plugin require no
upgrade action (because no change of plugin or hash format is
required). For accounts corresponding to lines for which the
password is empty, consider asking the account owners to choose
a password (or require it by using ALTER
USER
to expire empty account passwords).
Accounts that have an empty plugin and a 4.1 password hash use
mysql_native_password
implicitly. To upgrade
these accounts to use mysql_native_password
explicitly, execute these statements:
UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41); FLUSH PRIVILEGES;
Before MySQL 5.7, you can execute those statements to uprade accounts proactively. As of MySQL 5.7, you can run mysql_upgrade, which performs the same operation among its upgrade actions.
Notes:
The upgrade operation just described is safe to execute at
any time because it makes the
mysql_native_password
plugin explicit
only for accounts that already use it implicitly.
This operation requires no password changes, so it can be performed without affecting users or requiring their involvement in the upgrade process.
Accounts that use mysql_old_password
(either
implicitly or explicitly) should be upgraded to use
mysql_native_password
explicitly. This
requires changing the plugin and changing
the password from pre-4.1 to 4.1 hash format.
For the accounts covered in this step that must be upgraded, one of these conditions is true:
The account uses mysql_old_password
implicitly because the plugin
column is
empty and the password has the pre-4.1 hash format (16
characters).
The account uses mysql_old_password
explicitly.
To identify such accounts, use this query:
SELECT User, Host, Password FROM mysql.user WHERE (plugin = '' AND LENGTH(Password) = 16) OR plugin = 'mysql_old_password';
The following discussion provides two methods for updating that set of accounts. They have differing characteristics, so read both and decide which is most suitable for a given MySQL installation.
Method 1.
Characteristics of this method:
It requires that server and clients be run with
secure_auth=0
until all users have been
upgraded to mysql_native_password
.
(Otherwise, users cannot connect to the server using their
old-format password hashes for the purpose of upgrading to a
new-format hash.)
It works for MySQL 5.5 and 5.6. In 5.7, it does not work because the server requires accounts to have a nonempty plugin and disables them otherwise. Therefore, if you have already upgraded to 5.7, choose Method 2, described later.
You should ensure that the server is running with
secure_auth=0
.
For all accounts that use mysql_old_password
explicitly, set them to the empty plugin:
UPDATE mysql.user SET plugin = '' WHERE plugin = 'mysql_old_password'; FLUSH PRIVILEGES;
To also expire the password for affected accounts, use these statements instead:
UPDATE mysql.user SET plugin = '', password_expired = 'Y' WHERE plugin = 'mysql_old_password'; FLUSH PRIVILEGES;
Now affected users can reset their password to use 4.1 hashing. Ask each user who now has an empty plugin to connect to the server and execute these statements:
SET old_passwords = 0;
SET PASSWORD = PASSWORD('user-chosen-password
');
The client-side --secure-auth
option is enabled by default, so remind users to disable it or
they will be unable to connect:
shell> mysql -u user_name
-p --secure-auth=0
After an affected user has executed those statements, you can
set the corresponding account plugin to
mysql_native_password
to make the plugin
explicit. Or you can periodically run these statements to find
and fix any accounts for which affected users have reset their
password:
UPDATE mysql.user SET plugin = 'mysql_native_password' WHERE plugin = '' AND (Password = '' OR LENGTH(Password) = 41); FLUSH PRIVILEGES;
When there are no more accounts with an empty plugin, this query returns an empty result:
SELECT User, Host, Password FROM mysql.user WHERE plugin = '' AND LENGTH(Password) = 16;
At that point, all accounts have been migrated away from pre-4.1
password hashing and the server no longer need be run with
secure_auth=0
.
Method 2.
Characteristics of this method:
It assigns each affected account a new password, so you must tell each such user the new password and ask the user to choose a new one. Communication of passwords to users is outside the scope of MySQL, but should be done carefully.
It does not require server or clients to be run with
secure_auth=0
.
It works for any version of MySQL 5.5 or later (and for 5.7 has an easier variant).
With this method, you update each account separately due to the need to set passwords individually. Choose a different password for each account.
Suppose that 'user1'@'localhost'
is one of
the accounts to be upgraded. Modify it as follows:
In MySQL 5.7, ALTER USER
provides the
capability of modifying both the account password and its
authentication plugin, so you need not modify the
mysql.user
system table directly:
ALTER USER 'user1'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'DBA-chosen-password
';
To also expire the account password, use this statement instead:
ALTER USER 'user1'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'DBA-chosen-password
'
PASSWORD EXPIRE;
Then tell the user the new password and ask the user to connect to the server with that password and execute this statement to choose a new password:
ALTER USER USER() IDENTIFIED BY 'user-chosen-password
';
Before MySQL 5.7, you must modify the
mysql.user
system table directly using
these statements:
SET old_passwords = 0;
UPDATE mysql.user SET plugin = 'mysql_native_password',
Password = PASSWORD('DBA-chosen-password
')
WHERE (User, Host) = ('user1', 'localhost');
FLUSH PRIVILEGES;
To also expire the account password, use these statements instead:
SET old_passwords = 0;
UPDATE mysql.user SET plugin = 'mysql_native_password',
Password = PASSWORD('DBA-chosen-password
'), password_expired = 'Y'
WHERE (User, Host) = ('user1', 'localhost');
FLUSH PRIVILEGES;
Then tell the user the new password and ask the user to connect to the server with that password and execute these statements to choose a new password:
SET old_passwords = 0;
SET PASSWORD = PASSWORD('user-chosen-password
');
Repeat for each account to be upgraded.
MySQL provides two authentication plugins that implement SHA-256 hashing for user account passwords:
sha256_password
: Implements basic SHA-256
authentication.
caching_sha2_password
: Implements SHA-256
authentication (like sha256_password
),
but uses caching on the server side for better performance
and has additional features for wider applicability. (In
MySQL 5.7, caching_sha2_password
is
implemented only on the client side, as described later in
this section.)
This section describes the caching SHA-2 authentication plugin, available as of MySQL 5.7.23. For information about the original basic (noncaching) plugin, see Section 6.4.1.5, “SHA-256 Pluggable Authentication”.
In MySQL 5.7, the default authentication plugin is
mysql_native_password
. As of MySQL 8.0, the
default authentication plugin is changed to
caching_sha2_password
. To enable MySQL 5.7
clients to connect to 8.0 and higher servers using accounts
that authenticate with
caching_sha2_password
, the MySQL 5.7 client
library and client programs support the
caching_sha2_password
client-side
authentication plugin. This improves MySQL 5.7 client
connect-capability compatibility with respect to MySQL 8.0 and
higher servers, despite the differences in default
authentication plugin.
Limiting caching_sha2_password
support in
MySQL 5.7 to the client-side plugin in the client library has
these implications compared to MySQL 8.0:
The caching_sha2_password
server-side
plugin is not implemented in MySQL 5.7.
MySQL 5.7 servers do not support creating accounts that
authenticate with
caching_sha2_password
.
MySQL 5.7 servers do not implement system and status
variables specific to
caching_sha2_password
server-side
support:
caching_sha2_password_auto_generate_rsa_keys
,
caching_sha2_password_private_key_path
,
caching_sha2_password_public_key_path
,
Caching_sha2_password_rsa_public_key
.
In addition, there is no support for MySQL 5.7 replication
slaves to connect to MySQL 8.0 replication masters using
accounts that authenticate with
caching_sha2_password
. That would involve a
master replicating to a slave with a version number lower than
the master version, whereas masters normally replicate to
slaves having a version equal to or higher than the master
version.
To connect to a MySQL 8.0 or higher server using an account
that authenticates with the
caching_sha2_password
plugin, you must use
either a secure connection or an unencrypted connection that
supports password exchange using an RSA key pair, as described
later in this section. Either way, the
caching_sha2_password
plugin uses MySQL's
encryption capabilities. See
Section 6.3, “Using Encrypted Connections”.
In the name sha256_password
,
“sha256” refers to the 256-bit digest length the
plugin uses for encryption. In the name
caching_sha2_password
, “sha2”
refers more generally to the SHA-2 class of encryption
algorithms, of which 256-bit encryption is one instance. The
latter name choice leaves room for future expansion of
possible digest lengths without changing the plugin name.
The caching_sha2_password
plugin has these
advantages, compared to sha256_password
:
On the server side, an in-memory cache enables faster reauthentication of users who have connected previously when they connect again. (This server-side behavior is implemented only in MySQL 8.0 and higher.)
Support is provided for client connections that use the Unix socket-file and shared-memory protocols.
The following table shows the plugin name on the client side.
Table 6.10 Plugin and Library Names for SHA-2 Authentication
Plugin or File | Plugin or File Name |
---|---|
Client-side plugin | caching_sha2_password |
Library file | None (plugin is built in) |
The following sections provide installation and usage information specific to caching SHA-2 pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
In MySQL 5.7, the caching_sha2_password
plugin exists in client form. The client-side plugin is built
into the libmysqlclient
client library and
is available to any program linked against
libmysqlclient
.
In MySQL 5.7, the caching_sha2_password
client-side plugin enables connecting to MySQL 8.0 or higher
servers using accounts that authenticate with the
caching_sha2_password
server-side plugin.
The discussion here assumes that an account named
'sha2user'@'localhost'
exists on the MySQL
8.0 or higher server. For example, the following statement
creates such an account, where
password
is the desired account
password:
CREATE USER 'sha2user'@'localhost'
IDENTIFIED WITH caching_sha2_password BY 'password
';
caching_sha2_password
supports connections
over secure transport.
caching_sha2_password
also supports
encrypted password exchange using RSA over unencrypted
connections if these conditions are satisfied:
The MySQL 5.7 client library and client programs are
compiled using OpenSSL, not yaSSL.
caching_sha2_password
works with
distributions compiled using either package, but RSA
support requires OpenSSL.
It is possible to compile MySQL using yaSSL as an alternative to OpenSSL only prior to MySQL 5.7.28. As of MySQL 5.7.28, support for yaSSL is removed and all MySQL builds use OpenSSL.
The MySQL 8.0 or higher server to which you wish to connect is configured to support RSA (using the RSA configuration procedure given later in this section).
RSA support has these characteristics, where all aspects that pertain to the server side require a MySQL 8.0 or higher server:
On the server side, two system variables name the RSA
private and public key-pair files:
caching_sha2_password_private_key_path
and
caching_sha2_password_public_key_path
.
The database administrator must set these variables at
server startup if the key files to use have names that
differ from the system variable default values.
The server uses the
caching_sha2_password_auto_generate_rsa_keys
system variable to determine whether to automatically
generate the RSA key-pair files. See
Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
The
Caching_sha2_password_rsa_public_key
status variable displays the RSA public key value used by
the caching_sha2_password
authentication plugin.
Clients that are in possession of the RSA public key can perform RSA key pair-based password exchange with the server during the connection process, as described later.
For connections by accounts that authenticate with
caching_sha2_password
and RSA key
pair-based password exchange, the server does not send the
RSA public key to clients by default. Clients can use a
client-side copy of the required public key, or request
the public key from the server.
Use of a trusted local copy of the public key enables the client to avoid a round trip in the client/server protocol, and is more secure than requesting the public key from the server. On the other hand, requesting the public key from the server is more convenient (it requires no management of a client-side file) and may be acceptable in secure network environments.
For command-line clients, use the
--server-public-key-path
option to specify the RSA public key file. Use the
--get-server-public-key
option to request the public key from the server. The
following programs support the two options:
mysql,
mysqladmin,
mysqlbinlog,
mysqlcheck,
mysqldump,
mysqlimport,
mysqlpump,
mysqlshow,
mysqlslap,
mysqltest.
For programs that use the C API, call
mysql_options()
to
specify the RSA public key file by passing the
MYSQL_SERVER_PUBLIC_KEY
option and
the name of the file, or request the public key from
the server by passing the
MYSQL_OPT_GET_SERVER_PUBLIC_KEY
option.
In all cases, if the option is given to specify a valid public key file, it takes precedence over the option to request the public key from the server.
For clients that use the
caching_sha2_password
plugin, passwords are
never exposed as cleartext when connecting to the MySQL 8.0 or
higher server. How password transmission occurs depends on
whether a secure connection or RSA encryption is used:
If the connection is secure, an RSA key pair is unnecessary and is not used. This applies to encrypted TCP connections that use TLS, as well as Unix socket-file and shared-memory connections. The password is sent as cleartext but cannot be snooped because the connection is secure.
If the connection is not secure, an RSA key pair is used. This applies to unencrypted TCP connections without TLS and named-pipe connections. RSA is used only for password exchange between client and server, to prevent password snooping. When the server receives the encrypted password, it decrypts it. A scramble is used in the encryption to prevent repeat attacks.
If a secure connection is not used and RSA encryption is not available, the connection attempt fails because the password cannot be sent without being exposed as cleartext.
As mentioned previously, RSA password encryption is available only if MySQL 5.7 was compiled using OpenSSL. The implication for clients from MySQL 5.7 distributions compiled using yaSSL is that, to use SHA-2 passwords, clients must use an encrypted connection to access the server. See Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
Assuming that MySQL 5.7 has been compiled using OpenSSL, use the following procedure to enable use of an RSA key pair for password exchange during the client connection process.
Aspects of this procedure that pertain to server configuration must be done on the MySQL 8.0 or higher server to which you wish to connect using MySQL 5.7 clients, not on your MySQL 5.7 server.
Create the RSA private and public key-pair files using the instructions in Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
If the private and public key files are located in the
data directory and are named
private_key.pem
and
public_key.pem
(the default values of
the
caching_sha2_password_private_key_path
and
caching_sha2_password_public_key_path
system variables), the server uses them automatically at
startup.
Otherwise, to name the key files explicitly, set the system variables to the key file names in the server option file. If the files are located in the server data directory, you need not specify their full path names:
[mysqld] caching_sha2_password_private_key_path=myprivkey.pem caching_sha2_password_public_key_path=mypubkey.pem
If the key files are not located in the data directory, or to make their locations explicit in the system variable values, use full path names:
[mysqld] caching_sha2_password_private_key_path=/usr/local/mysql/myprivkey.pem caching_sha2_password_public_key_path=/usr/local/mysql/mypubkey.pem
Restart the server, then connect to it and check the
Caching_sha2_password_rsa_public_key
status variable value. The value will differ from that
shown here, but should be nonempty:
mysql> SHOW STATUS LIKE 'Caching_sha2_password_rsa_public_key'\G
*************************** 1. row ***************************
Variable_name: Caching_sha2_password_rsa_public_key
Value: -----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO9nRUDd+KvSZgY7cNBZMNpwX6
MvE1PbJFXO7u18nJ9lwc99Du/E7lw6CVXw7VKrXPeHbVQUzGyUNkf45Nz/ckaaJa
aLgJOBCIDmNVnyU54OT/1lcs2xiyfaDMe8fCJ64ZwTnKbY2gkt1IMjUAB5Ogd5kJ
g8aV7EtKwyhHb0c30QIDAQAB
-----END PUBLIC KEY-----
If the value is empty, the server found some problem with the key files. Check the error log for diagnostic information.
After the server has been configured with the RSA key files,
accounts that authenticate with the
caching_sha2_password
plugin have the
option of using those key files to connect to the server. As
mentioned previously, such accounts can use either a secure
connection (in which case RSA is not used) or an unencrypted
connection that performs password exchange using RSA. Suppose
that an unencrypted connection is used. For example:
shell>mysql --ssl-mode=DISABLED -u sha2user -p
Enter password:password
For this connection attempt by sha2user
,
the server determines that
caching_sha2_password
is the appropriate
authentication plugin and invokes it (because that was the
plugin specified at CREATE USER
time). The plugin finds that the connection is not encrypted
and thus requires the password to be transmitted using RSA
encryption. However, the server does not send the public key
to the client, and the client provided no public key, so it
cannot encrypt the password and the connection fails:
ERROR 2061 (HY000): Authentication plugin 'caching_sha2_password' reported error: Authentication requires secure connection.
To request the RSA public key from the server, specify the
--get-server-public-key
option:
shell>mysql --ssl-mode=DISABLED -u sha2user -p --get-server-public-key
Enter password:password
In this case, the server sends the RSA public key to the client, which uses it to encrypt the password and returns the result to the server. The plugin uses the RSA private key on the server side to decrypt the password and accepts or rejects the connection based on whether the password is correct.
Alternatively, if the client has a file containing a local
copy of the RSA public key required by the server, it can
specify the file using the
--server-public-key-path
option:
shell>mysql --ssl-mode=DISABLED -u sha2user -p --server-public-key-path=
Enter password:file_name
password
In this case, the client uses the public key to encrypt the password and returns the result to the server. The plugin uses the RSA private key on the server side to decrypt the password and accepts or rejects the connection based on whether the password is correct.
The public key value in the file named by the
--server-public-key-path
option
should be the same as the key value in the server-side file
named by the
caching_sha2_password_public_key_path
system variable. If the key file contains a valid public key
value but the value is incorrect, an access-denied error
occurs. If the key file does not contain a valid public key,
the client program cannot use it.
Client users can obtain the RSA public key two ways:
The database administrator can provide a copy of the public key file.
A client user who can connect to the server some other way
can use a SHOW STATUS LIKE
'Caching_sha2_password_rsa_public_key'
statement
and save the returned key value in a file.
On the server side, the
caching_sha2_password
plugin uses an
in-memory cache for faster authentication of clients who have
connected previously. For MySQL 5.7, which supports only the
caching_sha2_password
client-side plugin,
this server-side caching thus takes place on the MySQL 8.0 or
higher server to which you connect using MySQL 5.7 clients.
For information about cache operation, see
Cache Operation for SHA-2 Pluggable Authentication,
in MySQL 8.0 Reference Manual.
MySQL provides two authentication plugins that implement SHA-256 hashing for user account passwords:
sha256_password
: Implements basic SHA-256
authentication.
caching_sha2_password
: Implements SHA-256
authentication (like sha256_password
),
but uses caching on the server side for better performance
and has additional features for wider applicability.
This section describes the original noncaching SHA-2 authentication plugin. For information about the caching plugin, see Section 6.4.1.4, “Caching SHA-2 Pluggable Authentication”.
To connect to the server using an account that authenticates
with the sha256_password
plugin, you must
use either a TLS connection or an unencrypted connection that
supports password exchange using an RSA key pair, as described
later in this section. Either way, the
sha256_password
plugin uses MySQL's
encryption capabilities. See
Section 6.3, “Using Encrypted Connections”.
In the name sha256_password
,
“sha256” refers to the 256-bit digest length the
plugin uses for encryption. In the name
caching_sha2_password
, “sha2”
refers more generally to the SHA-2 class of encryption
algorithms, of which 256-bit encryption is one instance. The
latter name choice leaves room for future expansion of
possible digest lengths without changing the plugin name.
The following table shows the plugin names on the server and client sides.
Table 6.11 Plugin and Library Names for SHA-256 Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | sha256_password |
Client-side plugin | sha256_password |
Library file | None (plugins are built in) |
The following sections provide installation and usage information specific to SHA-256 pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
The sha256_password
plugin exists in server
and client forms:
The server-side plugin is built into the server, need not be loaded explicitly, and cannot be disabled by unloading it.
The client-side plugin is built into the
libmysqlclient
client library and is
available to any program linked against
libmysqlclient
.
To set up an account that uses the
sha256_password
plugin for SHA-256 password
hashing, use the following statement, where
password
is the desired account
password:
CREATE USER 'sha256user'@'localhost'
IDENTIFIED WITH sha256_password BY 'password
';
The server assigns the sha256_password
plugin to the account and uses it to encrypt the password
using SHA-256, storing those values in the
plugin
and
authentication_string
columns of the
mysql.user
system table.
The preceding instructions do not assume that
sha256_password
is the default
authentication plugin. If sha256_password
is the default authentication plugin, a simpler
CREATE USER
syntax can be used.
To start the server with the default authentication plugin set
to sha256_password
, put these lines in the
server option file:
[mysqld] default_authentication_plugin=sha256_password
That causes the sha256_password
plugin to
be used by default for new accounts. As a result, it is
possible to create the account and set its password without
naming the plugin explicitly:
CREATE USER 'sha256user'@'localhost' IDENTIFIED BY 'password
';
Another consequence of setting
default_authentication_plugin
to sha256_password
is that, to use some
other plugin for account creation, you must specify that
plugin explicitly. For example, to use the
mysql_native_password
plugin, use this
statement:
CREATE USER 'nativeuser'@'localhost'
IDENTIFIED WITH mysql_native_password BY 'password
';
sha256_password
supports connections over
secure transport. sha256_password
also
supports encrypted password exchange using RSA over
unencrypted connections if these conditions are satisfied:
MySQL is compiled using OpenSSL, not yaSSL.
sha256_password
works with
distributions compiled using either package, but RSA
support requires OpenSSL.
It is possible to compile MySQL using yaSSL as an alternative to OpenSSL only prior to MySQL 5.7.28. As of MySQL 5.7.28, support for yaSSL is removed and all MySQL builds use OpenSSL.
The MySQL server to which you wish to connect is configured to support RSA (using the RSA configuration procedure given later in this section).
RSA support has these characteristics:
On the server side, two system variables name the RSA
private and public key-pair files:
sha256_password_private_key_path
and
sha256_password_public_key_path
.
The database administrator must set these variables at
server startup if the key files to use have names that
differ from the system variable default values.
The server uses the
sha256_password_auto_generate_rsa_keys
system variable to determine whether to automatically
generate the RSA key-pair files. See
Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
The Rsa_public_key
status variable displays the RSA public key value used by
the sha256_password
authentication
plugin.
Clients that are in possession of the RSA public key can perform RSA key pair-based password exchange with the server during the connection process, as described later.
For connections by accounts that authenticate using
sha256_password
and RSA public key
pair-based password exchange, the server sends the RSA
public key to the client as needed. However, if a copy of
the public key is available on the client host, the client
can use it to save a round trip in the client/server
protocol:
For these command-line clients, use the
--server-public-key-path
option to specify the RSA public key file:
mysql,
mysqltest, and (as of MySQL 5.7.23)
mysqladmin,
mysqlbinlog,
mysqlcheck,
mysqldump,
mysqlimport,
mysqlpump,
mysqlshow,
mysqlslap,
mysqltest.
For programs that use the C API, call
mysql_options()
to
specify the RSA public key file by passing the
MYSQL_SERVER_PUBLIC_KEY
option and
the name of the file.
For replication slaves, RSA key pair-based password
exchange cannot be used to connect to master servers
for accounts that authenticate with the
sha256_password
plugin. For such
accounts, only secure connections can be used.
For clients that use the sha256_password
plugin, passwords are never exposed as cleartext when
connecting to the server. How password transmission occurs
depends on whether a secure connection or RSA encryption is
used:
If the connection is secure, an RSA key pair is unnecessary and is not used. This applies to encrypted connections that use TLS. The password is sent as cleartext but cannot be snooped because the connection is secure.
If the connection is not secure, and an RSA key pair is available, the connection remains unencrypted. This applies to unencrypted connections without TLS. RSA is used only for password exchange between client and server, to prevent password snooping. When the server receives the encrypted password, it decrypts it. A scramble is used in the encryption to prevent repeat attacks.
If a secure connection is not used and RSA encryption is not available, the connection attempt fails because the password cannot be sent without being exposed as cleartext.
As mentioned previously, RSA password encryption is available only if MySQL was compiled using OpenSSL. The implication for MySQL distributions compiled using yaSSL is that, to use SHA-256 passwords, clients must use an encrypted connection to access the server. See Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
To use RSA password encryption with
sha256_password
, the client and server
both must be compiled using OpenSSL, not just one of them.
Assuming that MySQL has been compiled using OpenSSL, use the following procedure to enable use of an RSA key pair for password exchange during the client connection process:
Create the RSA private and public key-pair files using the instructions in Section 6.3.3, “Creating SSL and RSA Certificates and Keys”.
If the private and public key files are located in the
data directory and are named
private_key.pem
and
public_key.pem
(the default values of
the
sha256_password_private_key_path
and
sha256_password_public_key_path
system variables), the server uses them automatically at
startup.
Otherwise, to name the key files explicitly, set the system variables to the key file names in the server option file. If the files are located in the server data directory, you need not specify their full path names:
[mysqld] sha256_password_private_key_path=myprivkey.pem sha256_password_public_key_path=mypubkey.pem
If the key files are not located in the data directory, or to make their locations explicit in the system variable values, use full path names:
[mysqld] sha256_password_private_key_path=/usr/local/mysql/myprivkey.pem sha256_password_public_key_path=/usr/local/mysql/mypubkey.pem
Restart the server, then connect to it and check the
Rsa_public_key
status
variable value. The value will differ from that shown
here, but should be nonempty:
mysql> SHOW STATUS LIKE 'Rsa_public_key'\G
*************************** 1. row ***************************
Variable_name: Rsa_public_key
Value: -----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDO9nRUDd+KvSZgY7cNBZMNpwX6
MvE1PbJFXO7u18nJ9lwc99Du/E7lw6CVXw7VKrXPeHbVQUzGyUNkf45Nz/ckaaJa
aLgJOBCIDmNVnyU54OT/1lcs2xiyfaDMe8fCJ64ZwTnKbY2gkt1IMjUAB5Ogd5kJ
g8aV7EtKwyhHb0c30QIDAQAB
-----END PUBLIC KEY-----
If the value is empty, the server found some problem with the key files. Check the error log for diagnostic information.
After the server has been configured with the RSA key files,
accounts that authenticate with the
sha256_password
plugin have the option of
using those key files to connect to the server. As mentioned
previously, such accounts can use either a secure connection
(in which case RSA is not used) or an unencrypted connection
that performs password exchange using RSA. Suppose that an
unencrypted connection is used. For example:
shell>mysql --ssl-mode=DISABLED -u sha256user -p
Enter password:password
For this connection attempt by sha256user
,
the server determines that sha256_password
is the appropriate authentication plugin and invokes it
(because that was the plugin specified at
CREATE USER
time). The plugin
finds that the connection is not encrypted and thus requires
the password to be transmitted using RSA encryption. In this
case, the plugin sends the RSA public key to the client, which
uses it to encrypt the password and returns the result to the
server. The plugin uses the RSA private key on the server side
to decrypt the password and accepts or rejects the connection
based on whether the password is correct.
The server sends the RSA public key to the client as needed.
However, if the client has a file containing a local copy of
the RSA public key required by the server, it can specify the
file using the
--server-public-key-path
option:
shell>mysql --ssl-mode=DISABLED -u sha256user -p --server-public-key-path=
Enter password:file_name
password
The public key value in the file named by the
--server-public-key-path
option
should be the same as the key value in the server-side file
named by the
sha256_password_public_key_path
system variable. If the key file contains a valid public key
value but the value is incorrect, an access-denied error
occurs. If the key file does not contain a valid public key,
the client program cannot use it. In this case, the
sha256_password
plugin sends the public key
to the client as if no
--server-public-key-path
option
had been specified.
Client users can obtain the RSA public key two ways:
The database administrator can provide a copy of the public key file.
A client user who can connect to the server some other way
can use a SHOW STATUS LIKE
'Rsa_public_key'
statement and save the returned
key value in a file.
A client-side authentication plugin is available that enables clients to send passwords to the server as cleartext, without hashing or encryption. This plugin is built into the MySQL client library.
The following table shows the plugin name.
Table 6.12 Plugin and Library Names for Cleartext Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | None, see discussion |
Client-side plugin | mysql_clear_password |
Library file | None (plugin is built in) |
Many client-side authentication plugins perform hashing or encryption of a password before the client sends it to the server. This enables clients to avoid sending passwords as cleartext.
Hashing or encryption cannot be done for authentication schemes
that require the server to receive the password as entered on
the client side. In such cases, the client-side
mysql_clear_password
plugin is used, which
enables the client to send the password to the server as
cleartext. There is no corresponding server-side plugin. Rather,
mysql_clear_password
can be used on the
client side in concert with any server-side plugin that needs a
cleartext password. (Examples are the PAM and simple LDAP
authentication plugins; see
Section 6.4.1.7, “PAM Pluggable Authentication”, and
Section 6.4.1.9, “LDAP Pluggable Authentication”.)
The following discussion provides usage information specific to cleartext pluggable authentication. For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
Sending passwords as cleartext may be a security problem in some configurations. To avoid problems if there is any possibility that the password would be intercepted, clients should connect to MySQL Server using a method that protects the password. Possibilities include SSL (see Section 6.3, “Using Encrypted Connections”), IPsec, or a private network.
To make inadvertent use of the
mysql_clear_password
plugin less likely,
MySQL clients must explicitly enable it. This can be done in
several ways:
Set the LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN
environment variable to a value that begins with
1
, Y
, or
y
. This enables the plugin for all client
connections.
The mysql, mysqladmin,
and mysqlslap client programs (also
mysqlcheck, mysqldump,
and mysqlshow for MySQL 5.7.10 and later)
support an --enable-cleartext-plugin
option
that enables the plugin on a per-invocation basis.
The mysql_options()
C API
function supports a
MYSQL_ENABLE_CLEARTEXT_PLUGIN
option that
enables the plugin on a per-connection basis. Also, any
program that uses libmysqlclient
and
reads option files can enable the plugin by including an
enable-cleartext-plugin
option in an
option group read by the client library.
PAM pluggable authentication is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.
MySQL Enterprise Edition supports an authentication method that enables MySQL Server to use PAM (Pluggable Authentication Modules) to authenticate MySQL users. PAM enables a system to use a standard interface to access various kinds of authentication methods, such as traditional Unix passwords or an LDAP directory.
PAM pluggable authentication provides these capabilities:
External authentication: PAM authentication enables MySQL Server to accept connections from users defined outside the MySQL grant tables and that authenticate using methods supported by PAM.
Proxy user support: PAM authentication can return to MySQL a
user name different from the external user name passed by
the client program, based on the PAM groups the external
user is a member of and the authentication string provided.
This means that the plugin can return the MySQL user that
defines the privileges the external PAM-authenticated user
should have. For example, an operating sytem user named
joe
can connect and have the privileges
of a MySQL user named developer
.
PAM pluggable authentication has been tested on Linux and macOS.
The following table shows the plugin and library file names. The
file name suffix might differ on your system. The file must be
located in the directory named by the
plugin_dir
system variable. For
installation information, see
Installing PAM Pluggable Authentication.
Table 6.13 Plugin and Library Names for PAM Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | authentication_pam |
Client-side plugin | mysql_clear_password |
Library file | authentication_pam.so |
The client-side mysql_clear_password
cleartext plugin that communicates with the server-side PAM
plugin is built into the libmysqlclient
client library and is included in all distributions, including
community distributions. Inclusion of the client-side cleartext
plugin in all MySQL distributions enables clients from any
distribution to connect to a server that has the server-side PAM
plugin loaded.
The following sections provide installation and usage information specific to PAM pluggable authentication:
For general information about pluggable authentication in MySQL,
see Section 6.2.13, “Pluggable Authentication”. For information
about the mysql_clear_password
plugin, see
Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”. For proxy
user information, see Section 6.2.14, “Proxy Users”.
This section provides a general overview of how MySQL and PAM work together to authenticate MySQL users. For examples showing how to set up MySQL accounts to use specific PAM services, see Using PAM Pluggable Authentication.
The client program and the server communicate, with the client sending to the server the client user name (the operating system user name by default) and password:
The client user name is the external user name.
For accounts that use the PAM server-side
authentication plugin, the corresponding client-side
plugin is mysql_clear_password
.
This client-side plugin performs no password hashing,
with the result that the client sends the password to
the server as cleartext.
The server finds a matching MySQL account based on the external user name and the host from which the client connects. The PAM plugin uses the information passed to it by MySQL Server (such as user name, host name, password, and authentication string). When you define a MySQL account that authenticates using PAM, the authentication string contains:
A PAM service name, which is a name that the system administrator can use to refer to an authentication method for a particular application. There can be multiple applications associated with a single database server instance, so the choice of service name is left to the SQL application developer.
Optionally, if proxying is to be used, a mapping from PAM groups to MySQL user names.
The plugin uses the PAM service named in the
authentication string to check the user credentials and
returns 'Authentication succeeded, Username is
or
user_name
''Authentication failed'
. The password
must be appropriate for the password store used by the PAM
service. Examples:
For traditional Unix passwords, the service looks up
passwords stored in the
/etc/shadow
file.
For LDAP, the service looks up passwords stored in an LDAP directory.
If the credentials check fails, the server refuses the connection.
Otherwise, the authentication string indicates whether proxying occurs. If the string contains no PAM group mapping, proxying does not occur. In this case, the MySQL user name is the same as the external user name.
Otherwise, proxying is indicated based on the PAM group mapping, with the MySQL user name determined based on the first matching group in the mapping list. The meaning of “PAM group” depends on the PAM service. Examples:
For traditional Unix passwords, groups are Unix groups
defined in the /etc/group
file,
possibly supplemented with additional PAM information
in a file such as
/etc/security/group.conf
.
For LDAP, groups are LDAP groups defined in an LDAP directory.
If the proxy user (the external user) has the
PROXY
privilege for the
proxied MySQL user name, proxying occurs, with the proxy
user assuming the privileges of the proxied user.
This section describes how to install the PAM authentication plugin. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
The plugin library file base name is
authentication_pam
. The file name suffix
differs per platform (for example, .so
for Unix and Unix-like systems, .dll
for
Windows).
To load the plugin at server startup, use the
--plugin-load-add
option to
name the library file that contains it. With this
plugin-loading method, the option must be given each time the
server starts. For example, put these lines in the server
my.cnf
file (adjust the
.so
suffix for your platform as
necessary):
[mysqld] plugin-load-add=authentication_pam.so
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this
statement (adjust the .so
suffix for your
platform as necessary):
INSTALL PLUGIN authentication_pam SONAME 'authentication_pam.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%pam%';
+--------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------------+---------------+ | authentication_pam | ACTIVE | +--------------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with the PAM plugin, see Using PAM Pluggable Authentication.
The method used to uninstall the PAM authentication plugin depends on how you installed it:
If you installed the plugin at server startup using a
--plugin-load-add
option,
restart the server without the option.
If you installed the plugin at runtime using an
INSTALL PLUGIN
statement,
it remains installed across server restarts. To uninstall
it, use UNINSTALL PLUGIN
:
UNINSTALL PLUGIN authentication_pam;
This section describes in general terms how to use the PAM authentication plugin to connect from MySQL client programs to the server. The following sections provide instructions for using PAM authentication in specific ways. It is assumed that the server is running with the server-side PAM plugin enabled, as described in Installing PAM Pluggable Authentication.
To refer to the PAM authentication plugin in the
IDENTIFIED WITH
clause of a
CREATE USER
statement, use the
name authentication_pam
. For example:
CREATE USERuser
IDENTIFIED WITH authentication_pam AS 'auth_string
';
The authentication string specifies the following types of information:
The PAM service name (see
How PAM Authentication of MySQL Users Works).
Examples in the following discussion use a service name of
mysql-unix
for authentication using
traditional Unix passwords, and
mysql-ldap
for authentication using
LDAP.
For proxy support, PAM provides a way for a PAM module to return to the server a MySQL user name other than the external user name passed by the client program when it connects to the server. Use the authentication string to control the mapping from external user names to MySQL user names. If you want to take advantage of proxy user capabilities, the authentication string must include this kind of mapping.
For example, if an account uses the
mysql-unix
PAM service name and should map
operating system users in the root
and
users
PAM groups to the
developer
and data_entry
MySQL users, respectively, use a statement like this:
CREATE USER user
IDENTIFIED WITH authentication_pam
AS 'mysql-unix, root=developer, users=data_entry';
Authentication string syntax for the PAM authentication plugin follows these rules:
The string consists of a PAM service name, optionally followed by a PAM group mapping list consisting of one or more keyword/value pairs each specifying a PAM group name and a MySQL user name:
pam_service_name
[,pam_group_name
=mysql_user_name
]...
The plugin parses the authentication string for each connection attempt that uses the account. To minimize overhead, keep the string as short as possible.
Each
pair must be preceded by a comma.
pam_group_name
=mysql_user_name
Leading and trailing spaces not inside double quotation marks are ignored.
Unquoted pam_service_name
,
pam_group_name
, and
mysql_user_name
values can
contain anything except equal sign, comma, or space.
If a pam_service_name
,
pam_group_name
, or
mysql_user_name
value is quoted
with double quotation marks, everything between the
quotation marks is part of the value. This is necessary,
for example, if the value contains space characters. All
characters are legal except double quotation mark and
backslash (\
). To include either
character, escape it with a backslash.
If the plugin successfully authenticates the external user name (the name passed by the client), it looks for a PAM group mapping list in the authentication string and, if present, uses it to return a different MySQL user name to the MySQL server based on which PAM groups the external user is a member of:
If the authentication string contains no PAM group mapping list, the plugin returns the external name.
If the authentication string does contain a PAM group
mapping list, the plugin examines each
pair in the list from left to right and tries to find a
match for the pam_group_name
=mysql_user_name
pam_group_name
value in a non-MySQL directory of the groups assigned to
the authenticated user and returns
mysql_user_name
for the first
match it finds. If the plugin finds no match for any PAM
group, it returns the external name. If the plugin is not
capable of looking up a group in a directory, it ignores
the PAM group mapping list and returns the external name.
The following sections describe how to set up several authentication scenarios that use the PAM authentication plugin:
No proxy users. This uses PAM only to check login names
and passwords. Every external user permitted to connect to
MySQL Server should have a matching MySQL account that is
defined to use PAM authentication. (For a MySQL account of
'
to match the external user,
user_name
'@'host_name
'user_name
must be the external
user name and host_name
must
match the host from which the client connects.)
Authentication can be performed by various PAM-supported
methods. Later discussion shows how to authenticate client
credentials using traditional Unix passwords, and
passwords in LDAP.
PAM authentication, when not done through proxy users or PAM groups, requires the MySQL user name to be same as the operating system user name. MySQL user names are limited to 32 characters (see Section 6.2.3, “Grant Tables”), which limits PAM nonproxy authentication to Unix accounts with names of at most 32 characters.
Proxy users only, with PAM group mapping. For this scenario, create one or more MySQL accounts that define different sets of privileges. (Ideally, nobody should connect using those accounts directly.) Then define a default user authenticating through PAM that uses some mapping scheme (usually based on the external PAM groups the users are members of) to map all the external user names to the few MySQL accounts holding the privilege sets. Any client who connects and specifies an external user name as the client user name is mapped to one of the MySQL accounts and uses its privileges. The discussion shows how to set this up using traditional Unix passwords, but other PAM methods such as LDAP could be used instead.
Variations on these scenarios are possible:
You can permit some users to log in directly (without proxying) but require others to connect through proxy accounts.
You can use one PAM authentication method for some users,
and another method for other users, by using differing PAM
service names among your PAM-authenticated accounts. For
example, you can use the mysql-unix
PAM
service for some users, and mysql-ldap
for others.
The examples make the following assumptions. You might need to make some adjustments if your system is set up differently.
The login name and password are antonio
and antonio_password
,
respectively. Change these to correspond to the user you
want to authenticate.
The PAM configuration directory is
/etc/pam.d
.
The PAM service name corresponds to the authentication
method (mysql-unix
or
mysql-ldap
in this discussion). To use
a given PAM service, you must set up a PAM file with the
same name in the PAM configuration directory (creating the
file if it does not exist). In addition, you must name the
PAM service in the authentication string of the
CREATE USER
statement for
any account that authenticates using that PAM service.
The PAM authentication plugin checks at initialization time
whether the AUTHENTICATION_PAM_LOG
environment value is set in the server's startup environment.
If so, the plugin enables logging of diagnostic messages to
the standard output. Depending on how your server is started,
the message might appear on the console or in the error log.
These messages can be helpful for debugging PAM-related issues
that occur when the plugin performs authentication. For more
information, see
PAM Authentication Debugging.
This authentication scenario uses PAM to check external users defined in terms of operating system user names and Unix passwords, without proxying. Every such external user permitted to connect to MySQL Server should have a matching MySQL account that is defined to use PAM authentication through traditional Unix password store.
Traditional Unix passwords are checked using the
/etc/shadow
file. For information
regarding possible issues related to this file, see
PAM Authentication Access to Unix Password Store.
Verify that Unix authentication permits logins to the
operating system with the user name
antonio
and password
antonio_password
.
Set up PAM to authenticate MySQL connections using
traditional Unix passwords by creating a
mysql-unix
PAM service file named
/etc/pam.d/mysql-unix
. The file
contents are system dependent, so check existing
login-related files in the /etc/pam.d
directory to see what they look like. On Linux, the
mysql-unix
file might look like this:
#%PAM-1.0 auth include password-auth account include password-auth
For macOS, use login
rather than
password-auth
.
The PAM file format might differ on some systems. For example, on Ubuntu and other Debian-based systems, use these file contents instead:
@include common-auth @include common-account @include common-session-noninteractive
Create a MySQL account with the same user name as the
operating system user name and define it to authenticate
using the PAM plugin and the mysql-unix
PAM service:
CREATE USER 'antonio'@'localhost' IDENTIFIED WITH authentication_pam AS 'mysql-unix'; GRANT ALL PRIVILEGES ON mydb.* TO 'antonio'@'localhost';
Here, the authentication string contains only the PAM
service name, mysql-unix
, which
authenticates Unix passwords.
Use the mysql command-line client to
connect to the MySQL server as antonio
.
For example:
shell>mysql --user=antonio --password --enable-cleartext-plugin
Enter password:
antonio_password
The server should permit the connection and the following query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+-------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+-------------------+--------------+
| antonio@localhost | antonio@localhost | NULL |
+-------------------+-------------------+--------------+
This demonstrates that the antonio
operating system user is authenticated to have the
privileges granted to the antonio
MySQL
user, and that no proxying has occurred.
The client-side mysql_clear_password
authentication plugin leaves the password untouched, so
client programs send it to the MySQL server as cleartext.
This enables the password to be passed as is to PAM. A
cleartext password is necessary to use the server-side PAM
library, but may be a security problem in some
configurations. These measures minimize the risk:
To make inadvertent use of the
mysql_clear_password
plugin less
likely, MySQL clients must explicitly enable it (for
example, with the
--enable-cleartext-plugin
option). See
Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”.
To avoid password exposure with the
mysql_clear_password
plugin enabled,
MySQL clients should connect to the MySQL server using
an encrypted connection. See
Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
This authentication scenario uses PAM to check external users defined in terms of operating system user names and LDAP passwords, without proxying. Every such external user permitted to connect to MySQL Server should have a matching MySQL account that is defined to use PAM authentication through LDAP.
To use PAM LDAP pluggable authentication for MySQL, these prerequisites must be satisfied:
An LDAP server must be available for the PAM LDAP service to communicate with.
LDAP users to be authenticated by MySQL must be present in the directory managed by the LDAP server.
Another way to use LDAP for MySQL user authentication is to use the LDAP-specific authentication plugins. See Section 6.4.1.9, “LDAP Pluggable Authentication”.
Configure MySQL for PAM LDAP authentication as follows:
Verify that Unix authentication permits logins to the
operating system with the user name
antonio
and password
antonio_password
.
Set up PAM to authenticate MySQL connections using LDAP by
creating a mysql-ldap
PAM service file
named /etc/pam.d/mysql-ldap
. The file
contents are system dependent, so check existing
login-related files in the /etc/pam.d
directory to see what they look like. On Linux, the
mysql-ldap
file might look like this:
#%PAM-1.0 auth required pam_ldap.so account required pam_ldap.so
If PAM object files have a suffix different from
.so
on your system, substitute the
correct suffix.
The PAM file format might differ on some systems.
Create a MySQL account with the same user name as the
operating system user name and define it to authenticate
using the PAM plugin and the mysql-ldap
PAM service:
CREATE USER 'antonio'@'localhost' IDENTIFIED WITH authentication_pam AS 'mysql-ldap'; GRANT ALL PRIVILEGES ON mydb.* TO 'antonio'@'localhost';
Here, the authentication string contains only the PAM
service name, mysql-ldap
, which
authenticates using LDAP.
Connecting to the server is the same as described in PAM Unix Password Authentication without Proxy Users.
The authentication scheme described here uses proxying and PAM group mapping to map connecting MySQL users who authenticate using PAM onto other MySQL accounts that define different sets of privileges. Users do not connect directly through the accounts that define the privileges. Instead, they connect through a default proxy account authenticated using PAM, such that all the external users are mapped to the MySQL accounts that hold the privileges. Any user who connects using the proxy account is mapped to one of those MySQL accounts, the privileges for which determine the database operations permitted to the external user.
The procedure shown here uses Unix password authentication. To use LDAP instead, see the early steps of PAM LDAP Authentication without Proxy Users.
Traditional Unix passwords are checked using the
/etc/shadow
file. For information
regarding possible issues related to this file, see
PAM Authentication Access to Unix Password Store.
Verify that Unix authentication permits logins to the
operating system with the user name
antonio
and password
antonio_password
.
Verify that antonio
is a member of the
root
or users
PAM
group.
Set up PAM to authenticate the
mysql-unix
PAM service through
operating system users by creating a file named
/etc/pam.d/mysql-unix
. The file
contents are system dependent, so check existing
login-related files in the /etc/pam.d
directory to see what they look like. On Linux, the
mysql-unix
file might look like this:
#%PAM-1.0 auth include password-auth account include password-auth
For macOS, use login
rather than
password-auth
.
The PAM file format might differ on some systems. For example, on Ubuntu and other Debian-based systems, use these file contents instead:
@include common-auth @include common-account @include common-session-noninteractive
Create a default proxy user (''@''
)
that maps external PAM users to the proxied accounts:
CREATE USER ''@'' IDENTIFIED WITH authentication_pam AS 'mysql-unix, root=developer, users=data_entry';
Here, the authentication string contains the PAM service
name, mysql-unix
, which authenticates
Unix passwords. The authentication string also maps
external users in the root
and
users
PAM groups to the
developer
and
data_entry
MySQL user names,
respectively.
The PAM group mapping list following the PAM service name is required when you set up proxy users. Otherwise, the plugin cannot tell how to perform mapping from external user names to the proper proxied MySQL user names.
If your MySQL installation has anonymous users, they might conflict with the default proxy user. For more information about this issue, and ways of dealing with it, see Default Proxy User and Anonymous User Conflicts.
Create the proxied accounts and grant to them the privileges required for MySQL access:
CREATE USER 'developer'@'localhost' IDENTIFIED WITH mysql_no_login; CREATE USER 'data_entry'@'localhost' IDENTIFIED WITH mysql_no_login; GRANT ALL PRIVILEGES ON mydevdb.* TO 'developer'@'localhost'; GRANT ALL PRIVILEGES ON mydb.* TO 'data_entry'@'localhost';
The proxied accounts use the
mysql_no_login
authentication plugin to
prevent clients from using the accounts to log in directly
to the MySQL server. Instead, it is expected that users
who authenticate using PAM will use the
developer
or
data_entry
account by proxy based on
their PAM group. (This assumes that the plugin is
installed. For instructions, see
Section 6.4.1.10, “No-Login Pluggable Authentication”.) For
alternative methods of protecting proxied accounts against
direct use, see
Preventing Direct Login to Proxied Accounts.
Grant to the proxy account the
PROXY
privilege for each
proxied account:
GRANT PROXY ON 'developer'@'localhost' TO ''@''; GRANT PROXY ON 'data_entry'@'localhost' TO ''@'';
Use the mysql command-line client to
connect to the MySQL server as antonio
.
shell>mysql --user=antonio --password --enable-cleartext-plugin
Enter password:
antonio_password
The server authenticates the connection using the default
''@''
proxy account. The resulting
privileges for antonio
depend on which
PAM groups antonio
is a member of. If
antonio
is a member of the
root
PAM group, the PAM plugin maps
root
to the
developer
MySQL user name and returns
that name to the server. The server verifies that
''@''
has the
PROXY
privilege for
developer
and permits the connection.
The following query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+---------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+---------------------+--------------+
| antonio@localhost | developer@localhost | ''@'' |
+-------------------+---------------------+--------------+
This demonstrates that the antonio
operating system user is authenticated to have the
privileges granted to the developer
MySQL user, and that proxying occurs through the default
proxy account.
If antonio
is not a member of the
root
PAM group but is a member of the
users
PAM group, a similar process
occurs, but the plugin maps user
PAM
group membership to the data_entry
MySQL user name and returns that name to the server:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-------------------+----------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-------------------+----------------------+--------------+
| antonio@localhost | data_entry@localhost | ''@'' |
+-------------------+----------------------+--------------+
This demonstrates that the antonio
operating system user is authenticated to have the
privileges of the data_entry
MySQL
user, and that proxying occurs through the default proxy
account.
The client-side mysql_clear_password
authentication plugin leaves the password untouched, so
client programs send it to the MySQL server as cleartext.
This enables the password to be passed as is to PAM. A
cleartext password is necessary to use the server-side PAM
library, but may be a security problem in some
configurations. These measures minimize the risk:
To make inadvertent use of the
mysql_clear_password
plugin less
likely, MySQL clients must explicitly enable it (for
example, with the
--enable-cleartext-plugin
option). See
Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”.
To avoid password exposure with the
mysql_clear_password
plugin enabled,
MySQL clients should connect to the MySQL server using
an encrypted connection. See
Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
On some systems, Unix authentication uses a password store
such as /etc/shadow
, a file that
typically has restricted access permissions. This can cause
MySQL PAM-based authentication to fail. Unfortunately, the PAM
implementation does not permit distinguishing “password
could not be checked” (due, for example, to inability
to read /etc/shadow
) from “password
does not match.” If you are using Unix password store
for PAM authentication, you may be able to enable access to it
from MySQL using one of the following methods:
Assuming that the MySQL server is run from the
mysql
operating system account, put
that account in the shadow
group that
has /etc/shadow
access:
Create a shadow
group in
/etc/group
.
Add the mysql
operating system user
to the shadow
group in
/etc/group
.
Assign /etc/group
to the
shadow
group and enable the group
read permission:
chgrp shadow /etc/shadow chmod g+r /etc/shadow
Restart the MySQL server.
If you are using the pam_unix
module
and the unix_chkpwd utility, enable
password store access as follows:
chmod u-s /usr/sbin/unix_chkpwd setcap cap_dac_read_search+ep /usr/sbin/unix_chkpwd
Adjust the path to unix_chkpwd as necessary for your platform.
The PAM authentication plugin checks at initialization time
whether the AUTHENTICATION_PAM_LOG
environment value is set (the value does not matter). If so,
the plugin enables logging of diagnostic messages to the
standard output. These messages may be helpful for debugging
PAM-related issues that occur when the plugin performs
authentication.
Some messages include reference to PAM plugin source files and line numbers, which enables plugin actions to be tied more closely to the location in the code where they occur.
Another technique for debugging connection failures and determining what is happening during connection attempts is to configure PAM authentication to permit all connections, then check the system log files. This technique should be used only on a temporary basis, and not on a production server.
Configure a PAM service file named
/etc/pam.d/mysql-any-password
with these
contents (the format may differ on some systems):
#%PAM-1.0 auth required pam_permit.so account required pam_permit.so
Create an account that uses the PAM plugin and names the
mysql-any-password
PAM service:
CREATE USER 'testuser'@'localhost' IDENTIFIED WITH authentication_pam AS 'mysql-any-password';
The mysql-any-password
service file causes
any authentication attempt to return true, even for incorrect
passwords. If an authentication attempt fails, that tells you
the configuration problem is on the MySQL side. Otherwise, the
problem is on the operating system/PAM side. To see what might
be happening, check system log files such as
/var/log/secure
,
/var/log/audit.log
,
/var/log/syslog
, or
/var/log/messages
.
After determining what the problem is, remove the
mysql-any-password
PAM service file to
disable any-password access.
Windows pluggable authentication is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.
MySQL Enterprise Edition for Windows supports an authentication method that performs external authentication on Windows, enabling MySQL Server to use native Windows services to authenticate client connections. Users who have logged in to Windows can connect from MySQL client programs to the server based on the information in their environment without specifying an additional password.
The client and server exchange data packets in the authentication handshake. As a result of this exchange, the server creates a security context object that represents the identity of the client in the Windows OS. This identity includes the name of the client account. Windows pluggable authentication uses the identity of the client to check whether it is a given account or a member of a group. By default, negotiation uses Kerberos to authenticate, then NTLM if Kerberos is unavailable.
Windows pluggable authentication provides these capabilities:
External authentication: Windows authentication enables MySQL Server to accept connections from users defined outside the MySQL grant tables who have logged in to Windows.
Proxy user support: Windows authentication can return to
MySQL a user name different from the external user name
passed by the client program. This means that the plugin can
return the MySQL user that defines the privileges the
external Windows-authenticated user should have. For
example, a Windows user named joe
can
connect and have the privileges of a MySQL user named
developer
.
The following table shows the plugin and library file names. The
file must be located in the directory named by the
plugin_dir
system variable.
Table 6.14 Plugin and Library Names for Windows Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | authentication_windows |
Client-side plugin | authentication_windows_client |
Library file | authentication_windows.dll |
The library file includes only the server-side plugin. The
client-side plugin is built into the
libmysqlclient
client library.
The server-side Windows authentication plugin is included only in MySQL Enterprise Edition. It is not included in MySQL community distributions. The client-side plugin is included in all distributions, including community distributions. This permits clients from any distribution to connect to a server that has the server-side plugin loaded.
The Windows authentication plugin is supported on any version of Windows supported by MySQL 5.7 (see https://www.mysql.com/support/supportedplatforms/database.html).
The following sections provide installation and usage information specific to Windows pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”. For proxy user information, see Section 6.2.14, “Proxy Users”.
This section describes how to install the Windows authentication plugin. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
To load the plugin at server startup, use the
--plugin-load-add
option to
name the library file that contains it. With this
plugin-loading method, the option must be given each time the
server starts. For example, put these lines in the server
my.cnf
file:
[mysqld] plugin-load-add=authentication_windows.dll
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this statement:
INSTALL PLUGIN authentication_windows SONAME 'authentication_windows.dll';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%windows%';
+------------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +------------------------+---------------+ | authentication_windows | ACTIVE | +------------------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with the Windows authentication
plugin, see
Using Windows Pluggable Authentication.
Additional plugin control is provided by the
authentication_windows_use_principal_name
and
authentication_windows_log_level
system variables. See
Section 5.1.7, “Server System Variables”.
The method used to uninstall the Windows authentication plugin depends on how you installed it:
If you installed the plugin at server startup using a
--plugin-load-add
option,
restart the server without the option.
If you installed the plugin at runtime using an
INSTALL PLUGIN
statement,
it remains installed across server restarts. To uninstall
it, use UNINSTALL PLUGIN
:
UNINSTALL PLUGIN authentication_windows;
In addition, remove any startup options that set Windows plugin-related system variables.
The Windows authentication plugin supports the use of MySQL accounts such that users who have logged in to Windows can connect to the MySQL server without having to specify an additional password. It is assumed that the server is running with the server-side plugin enabled, as described in Installing Windows Pluggable Authentication. Once the DBA has enabled the server-side plugin and set up accounts to use it, clients can connect using those accounts with no other setup required on their part.
To refer to the Windows authentication plugin in the
IDENTIFIED WITH
clause of a
CREATE USER
statement, use the
name authentication_windows
. Suppose that
the Windows users Rafal
and
Tasha
should be permitted to connect to
MySQL, as well as any users in the
Administrators
or Power
Users
group. To set this up, create a MySQL account
named sql_admin
that uses the Windows
plugin for authentication:
CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal, Tasha, Administrators, "Power Users"';
The plugin name is authentication_windows
.
The string following the AS
keyword is the
authentication string. It specifies that the Windows users
named Rafal
or Tasha
are
permitted to authenticate to the server as the MySQL user
sql_admin
, as are any Windows users in the
Administrators
or Power
Users
group. The latter group name contains a space,
so it must be quoted with double quote characters.
After you create the sql_admin
account, a
user who has logged in to Windows can attempt to connect to
the server using that account:
C:\> mysql --user=sql_admin
No password is required here. The
authentication_windows
plugin uses the
Windows security API to check which Windows user is
connecting. If that user is named Rafal
or
Tasha
, or is a member of the
Administrators
or Power
Users
group, the server grants access and the client
is authenticated as sql_admin
and has
whatever privileges are granted to the
sql_admin
account. Otherwise, the server
denies access.
Authentication string syntax for the Windows authentication plugin follows these rules:
The string consists of one or more user mappings separated by commas.
Each user mapping associates a Windows user or group name with a MySQL user name:
win_user_or_group_name=mysql_user_name
win_user_or_group_name
For the latter syntax, with no
mysql_user_name
value given,
the implicit value is the MySQL user created by the
CREATE USER
statement.
Thus, these statements are equivalent:
CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal, Tasha, Administrators, "Power Users"'; CREATE USER sql_admin IDENTIFIED WITH authentication_windows AS 'Rafal=sql_admin, Tasha=sql_admin, Administrators=sql_admin, "Power Users"=sql_admin';
Each backslash character (\
) in a value
must be doubled because backslash is the escape character
in MySQL strings.
Leading and trailing spaces not inside double quotation marks are ignored.
Unquoted win_user_or_group_name
and mysql_user_name
values can
contain anything except equal sign, comma, or space.
If a win_user_or_group_name
and
or mysql_user_name
value is
quoted with double quotation marks, everything between the
quotation marks is part of the value. This is necessary,
for example, if the name contains space characters. All
characters within double quotes are legal except double
quotation mark and backslash. To include either character,
escape it with a backslash.
win_user_or_group_name
values
use conventional syntax for Windows principals, either
local or in a domain. Examples (note the doubling of
backslashes):
domain\\user .\\user domain\\group .\\group BUILTIN\\WellKnownGroup
When invoked by the server to authenticate a client, the
plugin scans the authentication string left to right for a
user or group match to the Windows user. If there is a match,
the plugin returns the corresponding
mysql_user_name
to the MySQL
server. If there is no match, authentication fails.
A user name match takes preference over a group name match.
Suppose that the Windows user named
win_user
is a member of
win_group
and the authentication string
looks like this:
'win_group = sql_user1, win_user = sql_user2'
When win_user
connects to the MySQL server,
there is a match both to win_group
and to
win_user
. The plugin authenticates the user
as sql_user2
because the more-specific user
match takes precedence over the group match, even though the
group is listed first in the authentication string.
Windows authentication always works for connections from the same computer on which the server is running. For cross-computer connections, both computers must be registered with Windows Active Directory. If they are in the same Windows domain, it is unnecessary to specify a domain name. It is also possible to permit connections from a different domain, as in this example:
CREATE USER sql_accounting IDENTIFIED WITH authentication_windows AS 'SomeDomain\\Accounting';
Here SomeDomain
is the name of the other
domain. The backslash character is doubled because it is the
MySQL escape character within strings.
MySQL supports the concept of proxy users whereby a client can connect and authenticate to the MySQL server using one account but while connected has the privileges of another account (see Section 6.2.14, “Proxy Users”). Suppose that you want Windows users to connect using a single user name but be mapped based on their Windows user and group names onto specific MySQL accounts as follows:
The local_user
and
MyDomain\domain_user
local and domain
Windows users should map to the
local_wlad
MySQL account.
Users in the MyDomain\Developers
domain
group should map to the local_dev
MySQL
account.
Local machine administrators should map to the
local_admin
MySQL account.
To set this up, create a proxy account for Windows users to
connect to, and configure this account so that users and
groups map to the appropriate MySQL accounts
(local_wlad
, local_dev
,
local_admin
). In addition, grant the MySQL
accounts the privileges appropriate to the operations they
need to perform. The following instructions use
win_proxy
as the proxy account, and
local_wlad
, local_dev
,
and local_admin
as the proxied accounts.
Create the proxy MySQL account:
CREATE USER win_proxy IDENTIFIED WITH authentication_windows AS 'local_user = local_wlad, MyDomain\\domain_user = local_wlad, MyDomain\\Developers = local_dev, BUILTIN\\Administrators = local_admin';
For proxying to work, the proxied accounts must exist, so create them:
CREATE USER local_wlad IDENTIFIED WITH mysql_no_login; CREATE USER local_dev IDENTIFIED WITH mysql_no_login; CREATE USER local_admin IDENTIFIED WITH mysql_no_login;
The proxied accounts use the
mysql_no_login
authentication plugin to
prevent clients from using the accounts to log in directly
to the MySQL server. Instead, it is expected that users
who authenticate using Windows will use the
win_proxy
proxy account. (This assumes
that the plugin is installed. For instructions, see
Section 6.4.1.10, “No-Login Pluggable Authentication”.) For
alternative methods of protecting proxied accounts against
direct use, see
Preventing Direct Login to Proxied Accounts.
You should also execute
GRANT
statements (not
shown) that grant each proxied account the privileges
required for MySQL access.
Grant to the proxy account the
PROXY
privilege for each
proxied account:
GRANT PROXY ON local_wlad TO win_proxy; GRANT PROXY ON local_dev TO win_proxy; GRANT PROXY ON local_admin TO win_proxy;
Now the Windows users local_user
and
MyDomain\domain_user
can connect to the
MySQL server as win_proxy
and when
authenticated have the privileges of the account given in the
authentication string (in this case,
local_wlad
). A user in the
MyDomain\Developers
group who connects as
win_proxy
has the privileges of the
local_dev
account. A user in the
BUILTIN\Administrators
group has the
privileges of the local_admin
account.
To configure authentication so that all Windows users who do
not have their own MySQL account go through a proxy account,
substitute the default proxy account
(''@''
) for win_proxy
in
the preceding instructions. For information about default
proxy accounts, see Section 6.2.14, “Proxy Users”.
If your MySQL installation has anonymous users, they might conflict with the default proxy user. For more information about this issue, and ways of dealing with it, see Default Proxy User and Anonymous User Conflicts.
To use the Windows authentication plugin with Connector/NET connection strings in Connector/NET 6.4.4 and higher, see Using the Windows Native Authentication Plugin.
LDAP pluggable authentication is an extension included in MySQL Enterprise Edition, a commercial product. To learn more about commercial products, see https://www.mysql.com/products/.
As of MySQL 5.7.19, MySQL Enterprise Edition supports an authentication method that enables MySQL Server to use LDAP (Lightweight Directory Access Protocol) to authenticate MySQL users by accessing directory services such as X.500. MySQL uses LDAP to fetch user, credential, and group information.
LDAP pluggable authentication provides these capabilities:
External authentication: LDAP authentication enables MySQL Server to accept connections from users defined outside the MySQL grant tables in LDAP directories.
Proxy user support: LDAP authentication can return to MySQL
a user name different from the external user name passed by
the client program, based on the LDAP groups the external
user is a member of. This means that an LDAP plugin can
return the MySQL user that defines the privileges the
external LDAP-authenticated user should have. For example,
an LDAP user named joe
can connect and
have the privileges of a MySQL user named
developer
, if the LDAP group for
joe
is developer
.
Security: Using TLS, connections to the LDAP server can be secure.
The following tables show the plugin and library file names for
simple and SASL-based LDAP authentication. The file name suffix
might differ on your system. The files must be located in the
directory named by the
plugin_dir
system variable.
Table 6.15 Plugin and Library Names for Simple LDAP Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin name | authentication_ldap_simple |
Client-side plugin name | mysql_clear_password |
Library file name | authentication_ldap_simple.so |
Table 6.16 Plugin and Library Names for SASL-Based LDAP Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin name | authentication_ldap_sasl |
Client-side plugin name | authentication_ldap_sasl_client |
Library file names | authentication_ldap_sasl.so ,
authentication_ldap_sasl_client.so |
The library files include only the
authentication_ldap_
authentication plugins. The client-side
XXX
mysql_clear_password
plugin is built into the
libmysqlclient
client library.
Each server-side LDAP plugin works with a specific client-side plugin:
The server-side
authentication_ldap_simple
plugin
performs simple LDAP authentication. For connections by
accounts that use this plugin, client programs use the
client-side mysql_clear_password
plugin,
which sends the password to the server as cleartext. No
password hashing or encryption is used, so a secure
connection between the MySQL client and server is
recommended to prevent password exposure.
The server-side authentication_ldap_sasl
plugin performs SASL-based LDAP authentication. For
connections by accounts that use this plugin, client
programs use the client-side
authentication_ldap_sasl_client
plugin.
The client-side and server-side SASL LDAP plugins use SASL
messages for secure transmission of credentials within the
LDAP protocol, to avoid sending the cleartext password
between the MySQL client and server.
The following sections provide installation and usage information specific to LDAP pluggable authentication:
For general information about pluggable authentication in MySQL,
see Section 6.2.13, “Pluggable Authentication”. For information
about the mysql_clear_password
plugin, see
Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”. For proxy
user information, see Section 6.2.14, “Proxy Users”.
If your system supports PAM and permits LDAP as a PAM
authentication method, another way to use LDAP for MySQL user
authentication is to use the server-side
authentication_pam
plugin. See
Section 6.4.1.7, “PAM Pluggable Authentication”.
To use LDAP pluggable authentication for MySQL, these prerequisites must be satisfied:
An LDAP server must be available for the LDAP authentication plugins to communicate with.
LDAP users to be authenticated by MySQL must be present in the directory managed by the LDAP server.
An LDAP client library must be available on systems where
the server-side
authentication_ldap_sasl
or
authentication_ldap_simple
plugin is
used. Currently, supported libraries are the Windows
native LDAP library, or the OpenLDAP library on
non-Windows systems.
To use SASL-based LDAP authentication:
The LDAP server must be configured to communicate with a SASL server.
A SASL client library must be is available on systems
where the client-side
authentication_ldap_sasl_client
plugin is used. Currently, the only supported library
is the Cyrus SASL library.
This section provides a general overview of how MySQL and LDAP work together to authenticate MySQL users. For examples showing how to set up MySQL accounts to use specific LDAP authentication plugins, see Using LDAP Pluggable Authentication.
The client connects to the MySQL server, providing the MySQL client user name and the LDAP password:
For simple LDAP authentication, the client-side and server-side plugins communicate the password as cleartext.
For SASL-based LDAP authentication, the client-side and server-side plugins use SASL messages for secure transmission of credentials within the LDAP protocol, to avoid sending the cleartext password between the MySQL client and server.
If the client user name and host name match no MySQL account, the connection is rejected.
If there is a matching MySQL account, authentication against LDAP occurs. The LDAP server looks for an entry matching the user and authenticates the entry against the LDAP password:
If the MySQL account names an the LDAP user distinguished
name (DN), LDAP authentication uses that value and the
LDAP password provided by the client. (To associate an
LDAP user DN with a MySQL account, include a
BY
clause that specifies an
authentication string in the CREATE
USER
statement that creates the account.)
If the MySQL account names no LDAP user DN, LDAP authentication uses the user name and LDAP password provided by the client. In this case, the authentication plugin first binds to the LDAP server using the root DN and password as credentials to find the user DN based on the client user name, then authenticates that user DN against the LDAP password. This bind using the root credentials fails if the root DN and password are set to incorrect values, or are empty (not set) and the LDAP server does not permit anonymous connections.
If the LDAP server finds no match or multiple matches, authentication fails and the client connection is rejected.
If the LDAP server finds a single match, LDAP authentication succeeds (assuming that the password is correct), the LDAP server returns the LDAP entry, and the authentication plugin determines the name of the authenticated user based on that entry:
If the LDAP entry has a group attribute (by default, the
cn
attribute), the plugin returns its
value as the authenticated user name.
If the LDAP entry has no group attribute, the authentication plugin returns the client user name as the authenticated user name.
The MySQL server compares the client user name with the authenticated user name to determine whether proxying occurs for the client session:
If the names are the same, no proxying occurs: The MySQL account matching the client user name is used for privilege checking.
If the names differ, proxying occurs: MySQL looks for an account matching the authenticated user name. That account becomes the proxied user, which is used for privilege checking. The MySQL account that matched the client user name is treated as the external proxy user.
This section describes how to install the LDAP authentication plugins. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library files must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
The server-side plugin library file base names are
authentication_ldap_simple
and
authentication_ldap_sasl
. The file name
suffix differs per platform (for example,
.so
for Unix and Unix-like systems,
.dll
for Windows).
To load the plugins at server startup, use
--plugin-load-add
options to
name the library files that contain them. With this
plugin-loading method, the options must be given each time the
server starts. Also, specify values for any plugin-provided
system variables you wish to configure.
Each server-side LDAP plugin exposes a set of system variables that enable its operation to be configured. Setting most of these is optional, but you must set the variables that specify the LDAP server host (so the plugin knows where to connect) and base distinguished name for LDAP bind operations (to limit the scope of searches and obtain faster searches). For details about all LDAP system variables, see Section 6.4.1.13, “Pluggable Authentication System Variables”.
To load the plugins and set the LDAP server host and base
distinguished name for LDAP bind operations, put lines such as
these in your my.cnf
file (adjust the
.so
suffix for your platform as
necessary):
[mysqld] plugin-load-add=authentication_ldap_simple.so authentication_ldap_simple_server_host=127.0.0.1 authentication_ldap_simple_bind_base_dn="dc=example,dc=com" plugin-load-add=authentication_ldap_sasl.so authentication_ldap_sasl_server_host=127.0.0.1 authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugins at runtime, use these
statements (adjust the .so
suffix for
your platform as necessary):
INSTALL PLUGIN authentication_ldap_simple SONAME 'authentication_ldap_simple.so'; INSTALL PLUGIN authentication_ldap_sasl SONAME 'authentication_ldap_sasl.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
After installing the plugins at runtime, their system
variables become available and you can add settings for them
to your my.cnf
file to configure the
plugins for subsequent restarts. For example:
[mysqld] authentication_ldap_simple_server_host=127.0.0.1 authentication_ldap_simple_bind_base_dn="dc=example,dc=com" authentication_ldap_sasl_server_host=127.0.0.1 authentication_ldap_sasl_bind_base_dn="dc=example,dc=com"
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%ldap%';
+----------------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +----------------------------+---------------+ | authentication_ldap_sasl | ACTIVE | | authentication_ldap_simple | ACTIVE | +----------------------------+---------------+
If a plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with an LDAP plugin, see Using LDAP Pluggable Authentication.
On systems running EL6 or EL that have SELinux enabled, changes to the SELinux policy are required to enable the MySQL LDAP plugins to communicate with the LDAP service:
Create a file mysqlldap.te
with
these contents:
module mysqlldap 1.0; require { type ldap_port_t; type mysqld_t; class tcp_socket name_connect; } #============= mysqld_t ============== allow mysqld_t ldap_port_t:tcp_socket name_connect;
Compile the security policy module into a binary representation:
checkmodule -M -m mysqlldap.te -o mysqlldap.mod
Create an SELinux policy module package:
semodule_package -m mysqlldap.mod -o mysqlldap.pp
Install the module package:
semodule -i mysqlldap.pp
When the SELinux policy changes have been made, restart the MySQL server:
service mysqld restart
The method used to uninstall the LDAP authentication plugins depends on how you installed them:
If you installed the plugins at server startup using
--plugin-load-add
options,
restart the server without those options.
If you installed the plugins at runtime using
INSTALL PLUGIN
, they remain
installed across server restarts. To uninstall them, use
UNINSTALL PLUGIN
:
UNINSTALL PLUGIN authentication_ldap_simple; UNINSTALL PLUGIN authentication_ldap_sasl;
In addition, remove from your my.cnf
file
any startup options that set LDAP plugin-related system
variables.
This section describes how to enable MySQL accounts to connect to the MySQL server using LDAP pluggable authentication. It is assumed that the server is running with the appropriate server-side plugins enabled, as described in Installing LDAP Pluggable Authentication, and that the appropriate client-side plugins are available on the client host.
This section does not describe LDAP configuration or administration. It is assumed that you are familiar with those topics.
The two server-side LDAP plugins each work with a specific client-side plugin:
The server-side
authentication_ldap_simple
plugin
performs simple LDAP authentication. For connections by
accounts that use this plugin, client programs use the
client-side mysql_clear_password
plugin, which sends the password to the server as
cleartext. No password hashing or encryption is used, so a
secure connection between the MySQL client and server is
recommended to prevent password exposure.
The server-side
authentication_ldap_sasl
plugin
performs SASL-based LDAP authentication. For connections
by accounts that use this plugin, client programs use the
client-side
authentication_ldap_sasl_client
plugin.
The client-side and server-side SASL LDAP plugins use SASL
messages for secure transmission of credentials within the
LDAP protocol, to avoid sending the cleartext password
between the MySQL client and server.
Overall requirements for LDAP authentication of MySQL users:
There must be an LDAP directory entry for each user to be authenticated.
There must be a MySQL user account that specifies a
server-side LDAP authentication plugin and optionally
names the associated LDAP user distinguished name (DN).
(To associate an LDAP user DN with a MySQL account,
include a BY
clause in the
CREATE USER
statement that
creates the account.) If an account names no LDAP string,
LDAP authentication uses the user name specified by the
client to find the LDAP entry.
Client programs connect using the connection method
appropriate for the server-side authentication plugin the
MySQL account uses. For LDAP authentication, connections
require the MySQL user name and LDAP password. In
addition, for accounts that use the server-side
authentication_ldap_simple
plugin,
invoke client programs with the
--enable-cleartext-plugin
option to
enable the client-side
mysql_clear_password
plugin.
The instructions here assume the following scenario:
MySQL users betsy
and
boris
authenticate to the LDAP entries
for betsy_ldap
and
boris_ldap
, respectively. (It is not
necessary that the MySQL and LDAP user names differ. The
use of different names in this discussion helps clarify
whether an operation context is MySQL or LDAP.)
LDAP entries use the uid
attribute to
specify user names. This may vary depending on LDAP
server. Some LDAP servers use the cn
attribute for user names rather than
uid
. To change the attribute, modify
the
authentication_ldap_simple_user_search_attr
or
authentication_ldap_sasl_user_search_attr
system variable appropriately.
These LDAP entries are available in the directory managed by the LDAP server, to provide distinguished name values that uniquely identify each user:
uid=betsy_ldap,ou=People,dc=example,dc=com uid=boris_ldap,ou=People,dc=example,dc=com
CREATE USER
statements that
create MySQL accounts name an LDAP user in the
BY
clause, to indicate which LDAP entry
the MySQL account authenticates against.
The instructions for setting up an account that uses LDAP authentication depend on which server-side LDAP plugin is used. The following sections describe several usage scenarios.
To configure a MySQL account for simple LDAP authentication,
the CREATE USER
statement
specifies the authentication_ldap_simple
plugin, and optionally names the LDAP user distinguished name
(DN):
CREATE USERuser
IDENTIFIED WITH authentication_ldap_simple [BY 'LDAP user DN
'];
Suppose that MySQL user betsy
has this
entry in the LDAP directory:
uid=betsy_ldap,ou=People,dc=example,dc=com
Then the statement to create the MySQL account for
betsy
looks like this:
CREATE USER 'betsy'@'localhost' IDENTIFIED WITH authentication_ldap_simple AS 'uid=betsy_ldap,ou=People,dc=example,dc=com';
The authentication string specified in the
BY
clause does not include the LDAP
password. That must be provided by the client user at connect
time.
Clients connect to the MySQL server by providing the MySQL
user name and LDAP password, and by enabling the client-side
mysql_clear_password
plugin:
shell>mysql --user=betsy --password --enable-cleartext-plugin
Enter password:
betsy_password
(betsy_ldap LDAP password)
The client-side mysql_clear_password
authentication plugin leaves the password untouched, so
client programs send it to the MySQL server as cleartext.
This enables the password to be passed as is to the LDAP
server. A cleartext password is necessary to use the
server-side LDAP library without SASL, but may be a security
problem in some configurations. These measures minimize the
risk:
To make inadvertent use of the
mysql_clear_password
plugin less
likely, MySQL clients must explicitly enable it (for
example, with the
--enable-cleartext-plugin
option). See
Section 6.4.1.6, “Client-Side Cleartext Pluggable Authentication”.
To avoid password exposure with the
mysql_clear_password
plugin enabled,
MySQL clients should connect to the MySQL server using
an encrypted connection. See
Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.
The authentication process occurs as follows:
The client-side plugin sends betsy
and
betsy_password
as the client
user name and LDAP password to the MySQL server.
The connection attempt matches the
'betsy'@'localhost'
account. The
server-side LDAP plugin finds that this account has an
authentication string of
'uid=betsy_ldap,ou=People,dc=example,dc=com'
to name the LDAP user DN. The plugin sends this string and
the LDAP password to the LDAP server.
The LDAP server finds the LDAP entry for
betsy_ldap
and the password matches, so
LDAP authentication succeeds.
The LDAP entry has no group attribute, so the server-side
plugin returns the client user name
(betsy
) as the authenticated user. This
is the same user name supplied by the client, so no
proxying occurs and the client session uses the
'betsy'@'localhost'
account for
privilege checking.
Had the matching LDAP entry contained a group attribute, that
attribute value would have been the authenticated user name
and, if the value differed from betsy
,
proxying would have occurred. For examples that use the group
attribute, see
LDAP Authentication with Proxying.
Had the CREATE USER
statement
contained no BY
clause to specify the
betsy_ldap
LDAP distinguished name,
authentication attempts would use the user name provided by
the client (in this case, betsy
). In the
absence of an LDAP entry for betsy
,
authentication would fail.
To configure a MySQL account for SASL LDAP authentication, the
CREATE USER
statement specifies
the authentication_ldap_sasl
plugin, and
optionally names the LDAP user distinguished name (DN):
CREATE USERuser
IDENTIFIED WITH authentication_ldap_sasl [BY 'LDAP user DN
'];
Suppose that MySQL user boris
has this
entry in the LDAP directory:
uid=boris_ldap,ou=People,dc=example,dc=com
Then the statement to create the MySQL account for
boris
looks like this:
CREATE USER 'boris'@'localhost' IDENTIFIED WITH authentication_ldap_sasl AS 'uid=boris_ldap,ou=People,dc=example,dc=com';
The authentication string specified in the
BY
clause does not include the LDAP
password. That must be provided by the client user at connect
time.
Clients connect to the MySQL server by providing the MySQL user name and LDAP password:
shell>mysql --user=boris --password
Enter password:
boris_password
(boris_ldap LDAP password)
For the server-side
authentication_ldap_sasl
plugin, clients
use the client-side
authentication_ldap_sasl_client
plugin. If
a client program does not find the client-side plugin, specify
a --plugin-dir
option that names the
directory where the plugin library file is installed.
The authentication process for boris
is
similar to that previously described for
betsy
with simple LDAP authentication,
except that the client-side and server-side SASL LDAP plugins
use SASL messages for secure transmission of credentials
within the LDAP protocol, to avoid sending the cleartext
password between the MySQL client and server.
As of MySQL 5.7.21, LDAP authentication plugins permit the
authentication string that provides user DN information to
begin with a +
prefix character:
In the absence of a +
character, the
authentication string value is treated as is without
modification.
If the authentication string begins with
+
, the plugin constructs the full user
DN value from the user name sent by the client, together
with the DN specified in the authentication string (with
the +
removed). In the constructed DN,
the client user name becomes the value of the attribute
that specifies LDAP user names. This is
uid
by default; to change the
attribute, modify the
authentication_ldap_simple_user_search_attr
or
authentication_ldap_sasl_user_search_attr
system variable appropriately. The authentication string
is stored as given in the mysql.user
system table, with the full user DN constructed on the fly
before authentication.
This account authentication string does not have
+
at the beginning, so it is taken as the
full user DN:
CREATE USER 'baldwin' IDENTIFIED WITH authentication_ldap_simple AS 'uid=admin,ou=People,dc=example,dc=com';
The client connects with the user name specified in the
account (baldwin
). In this case, that name
is not used because the authentication string has no prefix
and thus fully specifies the user DN.
This account authentication string does have
+
at the beginning, so it is taken as just
part of the user DN:
CREATE USER 'accounting' IDENTIFIED WITH authentication_ldap_simple AS '+ou=People,dc=example,dc=com';
The client connects with the user name specified in the
account (accounting
), which in this case is
used as the uid
attribute together with the
authentication string to construct the user DN:
uid=accounting,ou=People,dc=example,dc=com
The accounts in the preceding examples have a nonempty user
name, so the client always connects to the MySQL server using
the same name as specified in the account definition. If an
account has an empty user name, such as the default anonymous
''@'%'
proxy account described in
LDAP Authentication with Proxying,
clients might connect to the MySQL server with varying user
names. But the principle is the same: If the authentication
string begins with +
, the plugin uses the
user name sent by the client together with the authentication
string to construct the user DN.
LDAP authentication plugins support proxying, enabling a user to connect to the MySQL server as one user but assume the privileges of a different user. This section describes basic LDAP plugin proxy support. The LDAP plugins also support specification of group preference and proxy user mapping; see LDAP Authentication Group Preference and Mapping Specification.
The authentication scheme described here uses proxying based on mapping LDAP group attribute values to connecting MySQL users who authenticate using LDAP onto other MySQL accounts that define different sets of privileges. Users do not connect directly through the accounts that define the privileges. Instead, they connect through a default proxy account authenticated with LDAP, such that all the external logins are mapped to the MySQL accounts that hold the privileges. Any user who connects using the proxy account is mapped to one of those MySQL accounts, the privileges for which determine the database operations permitted to the external user.
The instructions here assume the following scenario:
LDAP entries use the uid
and
cn
attributes to specify user name and
group values, respectively. To use different user and
group attribute names, set the appropriate system
variables to configure the plugin:
For authentication_ldap_simple
: Set
authentication_ldap_simple_user_search_attr
and
authentication_ldap_simple_group_search_attr
.
For authentication_ldap_sasl
: Set
authentication_ldap_sasl_user_search_attr
and
authentication_ldap_sasl_group_search_attr
.
These LDAP entries are available in the directory managed by the LDAP server, to provide distinguished name values that uniquely identify each user:
uid=basha,ou=People,dc=example,dc=com,cn=accounting uid=basil,ou=People,dc=example,dc=com,cn=front_office
The group attribute values will become the authenticated
user names, so they name the accounting
and front_office
proxied accounts.
The examples assume use of SASL LDAP authentication. Make the appropriate adjustments for simple LDAP authentication.
Create the default proxy MySQL account:
CREATE USER ''@'%' IDENTIFIED WITH authentication_ldap_simple;
The proxy account definition has no AS
'
clause to
name an LDAP user DN. Thus:
auth_string
'
When a client connects, the client user name is used as the LDAP user name to search for.
The matching LDAP entry is expected to include a group attribute naming the proxied MySQL account that defines the privileges the client should have.
If your MySQL installation has anonymous users, they might conflict with the default proxy user. For more information about this issue, and ways of dealing with it, see Default Proxy User and Anonymous User Conflicts.
Create the proxied accounts and grant to them the privileges required for MySQL access:
CREATE USER 'accounting'@'localhost' IDENTIFIED WITH mysql_no_login; CREATE USER 'front_office'@'localhost' IDENTIFIED WITH mysql_no_login; GRANT ALL PRIVILEGES ON accountingdb.* TO 'accounting'@'localhost'; GRANT ALL PRIVILEGES ON frontdb.* TO 'front_office'@'localhost';
The proxied accounts use the mysql_no_login
authentication plugin to prevent clients from using the
accounts to log in directly to the MySQL server. Instead, it
is expected that users who authenticate using LDAP will use
the default ''@'%'
proxy account. (This
assumes that the mysql_no_login
plugin is
installed. For instructions, see
Section 6.4.1.10, “No-Login Pluggable Authentication”.) For
alternative methods of protecting proxied accounts against
direct use, see
Preventing Direct Login to Proxied Accounts.
Grant to the proxy account the
PROXY
privilege for each
proxied account:
GRANT PROXY ON 'accounting'@'localhost' TO ''@'%'; GRANT PROXY ON 'front_office'@'localhost' TO ''@'%';
Use the mysql command-line client to
connect to the MySQL server as basha
.
shell>mysql --user=basha --password
Enter password:
basha_password
(basha LDAP password)
Authentication occurs as follows:
The server authenticates the connection using the default
''@'%'
proxy account, for client user
basha
.
The matching LDAP entry is:
uid=basha,ou=People,dc=example,dc=com,cn=accounting
The matching LDAP entry has group attribute
cn=accounting
, so
accounting
becomes the authenticated
user.
The authenticated user differs from the client user name
basha
, with the result that
basha
is treated as a proxy for
accounting
, and
basha
assumes the privileges of the
accounting
account. The following query
returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-----------------+----------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-----------------+----------------------+--------------+
| basha@localhost | accounting@localhost | ''@'%' |
+-----------------+----------------------+--------------+
This demonstrates that basha
uses the
privileges granted to the accounting
MySQL
account, and that proxying occurs through the default proxy
user account.
Now connect as basil
instead:
shell>mysql --user=basil --password
Enter password:
basil_password
(basil LDAP password)
The authentication process for basil
is
similar to that previously described for
basha
:
The server authenticates the connection using the default
''@'%'
proxy account, for client user
basil
.
The matching LDAP entry is:
uid=basil,ou=People,dc=example,dc=com,cn=front_office
The matching LDAP entry has group attribute
cn=front_office
, so
front_office
becomes the authenticated
user.
The authenticated user differs from the client user name
basil
, with the result that
basil
is treated as a proxy for
front_office
, and
basil
assumes the privileges of the
front_office
account. The following
query returns output as shown:
mysql> SELECT USER(), CURRENT_USER(), @@proxy_user;
+-----------------+------------------------+--------------+
| USER() | CURRENT_USER() | @@proxy_user |
+-----------------+------------------------+--------------+
| basil@localhost | front_office@localhost | ''@'%' |
+-----------------+------------------------+--------------+
This demonstrates that basil
uses the
privileges granted to the front_office
MySQL account, and that proxying occurs through the default
proxy user account.
As described in LDAP Authentication with Proxying, basic LDAP authentication proxying works by the principle that the plugin uses the first group name returned by the LDAP server as the MySQL proxy user account name. This simple capability does not enable specifying any preference about which group name to use if the LDAP server returns multiple group names, or specifying any name other than the group name as the proxy user name.
As of MySQL 5.7.25, for MySQL accounts that use LDAP authentication, the authentication string can specify the following information to enable greater proxying flexibility:
A list of groups in preference order, such that the plugin uses the first group name in the list that matches a group returned by the LDAP server.
A mapping from group names to proxy user names, such that a group name when matched can provide a specified name to use as the proxy user. This provides an alternative to using the group name as the proxy user.
Consider the following MySQL proxy account definition:
CREATE USER ''@'%' IDENTIFIED WITH authentication_ldap_sasl AS '+ou=People,dc=example,dc=com#grp1=usera,grp2,grp3=userc';
The authentication string has a user DN suffix
ou=People,dc=example,dc=com
prefixed by the
+
character. Thus, as described in
LDAP Authentication User DN Suffixes,
the full user DN is constructed from the user DN suffix as
specified, plus the client user name as the
uid
attribute.
The remaining part of the authentication string begins with
#
, which signifies the beginning of group
preference and mapping information. This part of the
authentication string lists group names in the order
grp1
, grp2
,
grp3
. The LDAP plugin compares that list
with the set of group names returned by the LDAP server,
looking in list order for a match against the returned names.
The plugin uses the first match, or if there is no match,
authentication fails.
Suppose that the LDAP server returns groups
grp3
, grp2
, and
grp7
. The LDAP plugin uses
grp2
because it is the first group in the
authentication string that matches, even though it is not the
first group returned by the LDAP server. If the LDAP server
returns grp4
, grp2
, and
grp1
, the plugin uses
grp1
even though grp2
also matches. grp1
has a precedence higher
than grp2
because it is listed earlier in
the authentication string.
Assuming that the plugin finds a group name match, it performs mapping from that group name to the MySQL proxy user name, if there is one. For the example proxy account, mapping occurs as follows:
If the matching group name is grp1
or
grp3
, those are associated in the
authentication string with user names
usera
and userc
,
respectively. The plugin uses the corresponding associated
user name as the proxy user name.
If the matching group name is grp2
,
there is no associated user name in the authentication
string. The plugin uses grp2
as the
proxy user name.
If the LDAP server returns a group in DN format, the LDAP plugin parses the group DN to extract the group name from it.
To specify LDAP group preference and mapping information, these principles apply:
Begin the group preference and mapping part of the
authentication string with a #
prefix
character.
The group preference and mapping specification is a list
of one or more items, separated by commas. Each item has
the form
or group_name
=user_name
group_name
. Items should be
listed in group name preference order. For a group name
selected by the plugin as a match from set of group names
returned by the LDAP server, the two syntaxes differ in
effect as follows:
For an item specified as
(with a user name), the group name maps to the user
name, which is used as the MySQL proxy user name.
group_name
=user_name
For an item specified as
group_name
(with no user
name), the group name is used as the MySQL proxy user
name.
To quote a group or user name that contains special
characters such as space, surround it by double quote
("
) characters. For example, if an item
has group and user names of my group
name
and my user name
, it
must be written in a group mapping using quotes:
"my group name"="my user name"
If an item has group and user names of
my_group_name
and
my_user_name
(which contain no special
characters), it may but need not be written using quotes.
Any of the following are valid:
my_group_name=my_user_name my_group_name="my_user_name" "my_group_name"=my_user_name "my_group_name"="my_user_name"
To escape a character, precede it by a backslash
(\
). This is useful particularly to
include a literal double quote or backslash, which are
otherwise not included literally.
A user DN need not be present in the authentication
string, but if present, it must precede the group
preference and mapping part. A user DN can be given as a
full user DN, or as a user DN suffix with a
+
prefix character.
The mysql_no_login
server-side authentication
plugin prevents all client connections to any account that uses
it. Use cases for this plugin include:
Accounts that must be able to execute stored programs and views with elevated privileges without exposing those privileges to ordinary users.
Proxied accounts that should never permit direct login but are intended to be accessed only through proxy accounts.
The following table shows the plugin and library file names. The
file name suffix might differ on your system. The file must be
located in the directory named by the
plugin_dir
system variable.
Table 6.17 Plugin and Library Names for No-Login Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | mysql_no_login |
Client-side plugin | None |
Library file | mysql_no_login.so |
The following sections provide installation and usage information specific to no-login pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”. For proxy user information, see Section 6.2.14, “Proxy Users”.
This section describes how to install the no-login authentication plugin. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
The plugin library file base name is
mysql_no_login
. The file name suffix
differs per platform (for example, .so
for Unix and Unix-like systems, .dll
for
Windows).
To load the plugin at server startup, use the
--plugin-load-add
option to
name the library file that contains it. With this
plugin-loading method, the option must be given each time the
server starts. For example, put these lines in the server
my.cnf
file (adjust the
.so
suffix for your platform as
necessary):
[mysqld] plugin-load-add=mysql_no_login.so
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this
statement (adjust the .so
suffix for your
platform as necessary):
INSTALL PLUGIN mysql_no_login SONAME 'mysql_no_login.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%login%';
+----------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +----------------+---------------+ | mysql_no_login | ACTIVE | +----------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with the no-login plugin, see Using No-Login Pluggable Authentication.
The method used to uninstall the no-login authentication plugin depends on how you installed it:
If you installed the plugin at server startup using a
--plugin-load-add
option,
restart the server without the option.
If you installed the plugin at runtime using an
INSTALL PLUGIN
statement,
it remains installed across server restarts. To uninstall
it, use UNINSTALL PLUGIN
:
UNINSTALL PLUGIN mysql_no_login;
This section describes how to use the no-login authentication plugin to prevent accounts from being used for connecting from MySQL client programs to the server. It is assumed that the server is running with the no-login plugin enabled, as described in Installing No-Login Pluggable Authentication.
To refer to the no-login authentication plugin in the
IDENTIFIED WITH
clause of a
CREATE USER
statement, use the
name mysql_no_login
.
An account that authenticates using
mysql_no_login
may be used as the
DEFINER
for stored program and view
objects. If such an object definition also includes
SQL SECURITY DEFINER
, it executes with that
account's privileges. DBAs can use this behavior to provide
access to confidential or sensitive data that is exposed only
through well-controlled interfaces.
The following example illustrates these principles. It defines
an account that does not permit client connections, and
associates with it a view that exposes only certain columns of
the mysql.user
system table:
CREATE DATABASE nologindb; CREATE USER 'nologin'@'localhost' IDENTIFIED WITH mysql_no_login; GRANT ALL ON nologindb.* TO 'nologin'@'localhost'; GRANT SELECT ON mysql.user TO 'nologin'@'localhost'; CREATE DEFINER = 'nologin'@'localhost' SQL SECURITY DEFINER VIEW nologindb.myview AS SELECT User, Host FROM mysql.user;
To provide protected access to the view to an ordinary user, do this:
GRANT SELECT ON nologindb.myview TO 'ordinaryuser'@'localhost';
Now the ordinary user can use the view to access the limited information it presents:
SELECT * FROM nologindb.myview;
Attempts by the user to access columns other than those exposed by the view result in an error, as do attempts to select from the view by users not granted access to it.
Because the nologin
account cannot be
used directly, the operations required to set up objects
that it uses must be performed by root
or
similar account that has the privileges required to create
the objects and set DEFINER
values.
The mysql_no_login
plugin is also useful in
proxying scenarios. (For a discussion of concepts involved in
proxying, see Section 6.2.14, “Proxy Users”.) An account that
authenticates using mysql_no_login
may be
used as a proxied user for proxy accounts:
-- create proxied account CREATE USER 'proxied_user'@'localhost' IDENTIFIED WITH mysql_no_login; -- grant privileges to proxied account GRANT ... ON ... TO 'proxied_user'@'localhost'; -- permit proxy_user to be a proxy account for proxied account GRANT PROXY ON 'proxied_user'@'localhost' TO 'proxy_user'@'localhost';
This enables clients to access MySQL through the proxy account
(proxy_user
) but not to bypass the proxy
mechanism by connecting directly as the proxied user
(proxied_user
). A client who connects using
the proxy_user
account has the privileges
of the proxied_user
account, but
proxied_user
itself cannot be used to
connect.
For alternative methods of protecting proxied accounts against direct use, see Preventing Direct Login to Proxied Accounts.
The server-side auth_socket
authentication
plugin authenticates clients that connect from the local host
through the Unix socket file. The plugin uses the
SO_PEERCRED
socket option to obtain
information about the user running the client program. Thus, the
plugin can be used only on systems that support the
SO_PEERCRED
option, such as Linux.
The source code for this plugin can be examined as a relatively simple example demonstrating how to write a loadable authentication plugin.
The following table shows the plugin and library file names. The
file must be located in the directory named by the
plugin_dir
system variable.
Table 6.18 Plugin and Library Names for Socket Peer-Credential Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | auth_socket |
Client-side plugin | None, see discussion |
Library file | auth_socket.so |
The following sections provide installation and usage information specific to socket pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
This section describes how to install the socket authentication plugin. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
To load the plugin at server startup, use the
--plugin-load-add
option to
name the library file that contains it. With this
plugin-loading method, the option must be given each time the
server starts. For example, put these lines in the server
my.cnf
file:
[mysqld] plugin-load-add=auth_socket.so
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this statement:
INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%socket%';
+-------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +-------------+---------------+ | auth_socket | ACTIVE | +-------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with the socket plugin, see Using Socket Pluggable Authentication.
The method used to uninstall the socket authentication plugin depends on how you installed it:
If you installed the plugin at server startup using a
--plugin-load-add
option,
restart the server without the option.
If you installed the plugin at runtime using an
INSTALL PLUGIN
statement,
it remains installed across server restarts. To uninstall
it, use UNINSTALL PLUGIN
:
UNINSTALL PLUGIN auth_socket;
The socket plugin checks whether the socket user name (the
operating system user name) matches the MySQL user name
specified by the client program to the server. If the names do
not match, the plugin checks whether the socket user name
matches the name specified in the
authentication_string
column of the
mysql.user
system table row. If a match is
found, the plugin permits the connection. The
authentication_string
value can be
specified using an IDENTIFIED ...AS
clause
with CREATE USER
or
ALTER USER
.
Suppose that a MySQL account is created for an operating
system user named valerie
who is to be
authenticated by the auth_socket
plugin for
connections from the local host through the socket file:
CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket;
If a user on the local host with a login name of
stefanie
invokes mysql
with the option --user=valerie
to connect
through the socket file, the server uses
auth_socket
to authenticate the client. The
plugin determines that the --user
option
value (valerie
) differs from the client
user's name (stephanie
) and refuses the
connection. If a user named valerie
tries
the same thing, the plugin finds that the user name and the
MySQL user name are both valerie
and
permits the connection. However, the plugin refuses the
connection even for valerie
if the
connection is made using a different protocol, such as TCP/IP.
To permit both the valerie
and
stephanie
operating system users to access
MySQL through socket file connections that use the account,
this can be done two ways:
Name both users at account-creation time, one following
CREATE USER
, and the other
in the authentication string:
CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket AS 'stephanie';
If you have already used CREATE
USER
to create the account for a single user,
use ALTER USER
to add the
second user:
CREATE USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket; ALTER USER 'valerie'@'localhost' IDENTIFIED WITH auth_socket AS 'stephanie';
To access the account, both valerie
and
stephanie
specify
--user=valerie
at connect time.
MySQL includes a test plugin that checks account credentials and logs success or failure to the server error log. This is a loadable plugin (not built in) and must be installed prior to use.
The test plugin source code is separate from the server source, unlike the built-in native plugin, so it can be examined as a relatively simple example demonstrating how to write a loadable authentication plugin.
This plugin is intended for testing and development purposes, and is not for use in production environments or on servers that are exposed to public networks.
The following table shows the plugin and library file names. The
file name suffix might differ on your system. The file must be
located in the directory named by the
plugin_dir
system variable.
Table 6.19 Plugin and Library Names for Test Authentication
Plugin or File | Plugin or File Name |
---|---|
Server-side plugin | test_plugin_server |
Client-side plugin | auth_test_plugin |
Library file | auth_test_plugin.so |
The following sections provide installation and usage information specific to test pluggable authentication:
For general information about pluggable authentication in MySQL, see Section 6.2.13, “Pluggable Authentication”.
This section describes how to install the test authentication plugin. For general information about installing plugins, see Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory
location by setting the value of
plugin_dir
at server startup.
To load the plugin at server startup, use the
--plugin-load-add
option to
name the library file that contains it. With this
plugin-loading method, the option must be given each time the
server starts. For example, put these lines in the server
my.cnf
file (adjust the
.so
suffix for your platform as
necessary):
[mysqld] plugin-load-add=auth_test_plugin.so
After modifying my.cnf
, restart the
server to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this
statement (adjust the .so
suffix for your
platform as necessary):
INSTALL PLUGIN test_plugin_server SONAME 'auth_test_plugin.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without
the need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table
or use the SHOW PLUGINS
statement (see
Section 5.5.2, “Obtaining Server Plugin Information”). For example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE '%test_plugin%';
+--------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +--------------------+---------------+ | test_plugin_server | ACTIVE | +--------------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
To associate MySQL accounts with the test plugin, see Using Test Pluggable Authentication.
The method used to uninstall the test authentication plugin depends on how you installed it:
If you installed the plugin at server startup using a
--plugin-load-add
option,
restart the server without the option.
If you installed the plugin at runtime using an
INSTALL PLUGIN
statement,
it remains installed across server restarts. To uninstall
it, use UNINSTALL PLUGIN
:
UNINSTALL PLUGIN test_plugin_server;
To use the test authentication plugin, create an account and
name that plugin in the IDENTIFIED WITH
clause:
CREATE USER 'testuser'@'localhost'
IDENTIFIED WITH test_plugin_server
BY 'testpassword
';
Then provide the --user
and
--password
options for that
account when you connect to the server. For example:
shell>mysql --user=testuser --password
Enter password:
testpassword
The plugin fetches the password as received from the client
and compares it with the value stored in the
authentication_string
column of the account
row in the mysql.user
system table. If the
two values match, the plugin returns the
authentication_string
value as the new
effective user ID.
You can look in the server error log for a message indicating whether authentication succeeded (notice that the password is reported as the “user”):
[Note] Plugin test_plugin_server reported:
'successfully authenticated user testpassword
'
These variables are unavailable unless the appropriate server-side plugin is installed:
authentication_ldap_sasl
for system
variables with names of the form
authentication_ldap_sasl_
xxx
authentication_ldap_simple
for system
variables with names of the form
authentication_ldap_simple_
xxx
Table 6.20 Authentication Plugin System Variable Summary
authentication_ldap_sasl_auth_method_name
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-auth-method-name=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_auth_method_name |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | SCRAM-SHA-1 |
For SASL LDAP authentication, the authentication method name. Communication between the authentication plugin and the LDAP server occurs according to this authentication method. These authentication method values are permitted:
SCRAM-SHA-1
: Authentication uses a
SASL challenge-response mechanism to ensure password
security.
The client-side
authentication_ldap_sasl_client
plugin communicates with the SASL server, using the
password to create a challenge and obtain a SASL request
buffer, then passes this buffer to the server-side
authentication_ldap_sasl
plugin. The
client-side and server-side SASL LDAP plugins use SASL
messages for secure transmission of credentials within
the LDAP protocol, to avoid sending the cleartext
password between the MySQL client and server.
authentication_ldap_sasl_bind_base_dn
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-bind-base-dn=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_bind_base_dn |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For SASL LDAP authentication, the base distinguished name (DN). This variable can be used to limit the scope of searches by anchoring them at a certain location (the “base”) within the search tree.
Suppose that members of one set of LDAP user entries each have this form:
uid=user_name
,ou=People,dc=example,dc=com
And that members of another set of LDAP user entries each have this form:
uid=user_name
,ou=Admin,dc=example,dc=com
Then searches work like this for different base DN values:
If the base DN is
ou=People,dc=example,dc=com
: Searches
find user entries only in the first set.
If the base DN is
ou=Admin,dc=example,dc=com
: Searches
find user entries only in the second set.
If the base DN is
ou=dc=example,dc=com
: Searches find
user entries in the first or second set.
In general, more specific base DN values result in faster searches because they limit the search scope more.
authentication_ldap_sasl_bind_root_dn
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-bind-root-dn=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_bind_root_dn |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For SASL LDAP authentication, the root distinguished name
(DN). This variable is used in conjunction with
authentication_ldap_sasl_bind_root_pwd
as the credentials for authenticating to the LDAP server for
the purpose of performing searches. Authentication uses
either one or two LDAP bind operations, depending on whether
the MySQL account names an LDAP user DN:
If the account does not name a user DN:
authentication_ldap_sasl
performs an
initial LDAP binding using
authentication_ldap_sasl_bind_root_dn
and
authentication_ldap_sasl_bind_root_pwd
.
(These are both empty by default, so if they are not
set, the LDAP server must permit anonymous connections.)
The resulting bind LDAP handle is used to search for the
user DN, based on the client user name.
authentication_ldap_sasl
performs a
second bind using the user DN and client-supplied
password.
If the account does name a user DN: The first bind
operation is unnecessary in this case.
authentication_ldap_sasl
performs a
single bind using the user DN and client-supplied
password. This is faster than if the MySQL account does
not specify an LDAP user DN.
authentication_ldap_sasl_bind_root_pwd
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-bind-root-pwd=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_bind_root_pwd |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For SASL LDAP authentication, the password for the root
distinguished name. This variable is used in conjunction
with
authentication_ldap_sasl_bind_root_dn
.
See the description of that variable.
authentication_ldap_sasl_ca_path
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-ca-path=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_ca_path |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For SASL LDAP authentication, the absolute path of the certificate authority file. Specify this file if it is desired that the authentication plugin perform verification of the LDAP server certificate.
In addition to setting the
authentication_ldap_sasl_ca_path
variable to the file name, you must add the appropriate
certificate authority certificates to the file and enable
the
authentication_ldap_sasl_tls
system variable.
authentication_ldap_sasl_group_search_attr
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-group-search-attr=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_group_search_attr |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | cn |
For SASL LDAP authentication, the name of the attribute that
specifies group names in LDAP directory entries. If
authentication_ldap_sasl_group_search_attr
has its default value of cn
, searches
return the cn
value as the group name.
For example, if an LDAP entry with a uid
value of user1
has a
cn
attribute of
mygroup
, searches for
user1
return mygroup
as the group name.
This variable should be the empty string if you want no group or proxy authentication.
As of MySQL 5.7.21, if the group search attribute is
isMemberOf
, LDAP authentication directly
retrieves the user attribute isMemberOf
value and assigns it as group information. If the group
search attribute is not isMemberOf
, LDAP
authentication searches for all groups where the user is a
member. (The latter is the default behavior.) This behavior
is based on how LDAP group information can be stored two
ways: 1) A group entry can have an attribute named
memberUid
or member
with a value that is a user name; 2) A user entry can have
an attribute named isMemberOf
with values
that are group names.
authentication_ldap_sasl_group_search_filter
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-group-search-filter=value |
Introduced | 5.7.21 |
System Variable | authentication_ldap_sasl_group_search_filter |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | (|(&(objectClass=posixGroup)(memberUid=%s))(&(objectClass=group)(member=%s))) |
For SASL LDAP authentication, the custom group search filter.
As of MySQL 5.7.22, the search filter value can contain
{UA}
and {UD}
notation
to represent the user name and the full user DN. For
example, {UA}
is replaced with a user
name such as "admin"
, whereas
{UD}
is replaced with a use full DN such
as
"uid=admin,ou=People,dc=example,dc=com"
.
The following value is the default, which supports both
OpenLDAP and Active Directory:
(|(&(objectClass=posixGroup)(memberUid={UA})) (&(objectClass=group)(member={UD})))
Previously, if the group search attribute was
isMemberOf
or
memberOf
, it was treated as a user
attribute that has group information. However, in some cases
for the user scenario, memberOf
was a
simple user attribute that held no group information. For
additional flexibility, an optional {GA}
prefix now can be used with the group search attribute.
(Previously, it was assumed that if the group search
attribute is isMemberOf
, it will be
treated differently. Now any group attribute with a {GA}
prefix is treated as a user attribute having group names.)
For example, with a value of
{GA}MemberOf
, if the group value is the
DN, the first attribute value from the group DN is returned
as the group name.
In MySQL 5.7.21, the search filter used
%s
notation, expanding it to the user
name for OpenLDAP
(&(objectClass=posixGroup)(memberUid=%s)
)
and to the full user DN for Active Directory
(&(objectClass=group)(member=%s)
).
authentication_ldap_sasl_init_pool_size
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-init-pool-size=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_init_pool_size |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 10 |
Minimum Value | 0 |
Maximum Value | 32767 |
For SASL LDAP authentication, the initial size of the pool of connections to the LDAP server. Choose the value for this variable based on the average number of concurrent authentication requests to the LDAP server.
The plugin uses
authentication_ldap_sasl_init_pool_size
and
authentication_ldap_sasl_max_pool_size
together for connection-pool management:
When the authentication plugin initializes, it creates
authentication_ldap_sasl_init_pool_size
connections, unless
authentication_ldap_sasl_max_pool_size=0
to disable pooling.
If the plugin receives an anthentication request when
there are no free connections in the current connection
pool, the plugin can create a new connection, up to the
maximum connection pool size given by
authentication_ldap_sasl_max_pool_size
.
If the plugin receives a request when the pool size is already at its maximum and there are no free connections, authentication fails.
When the plugin unloads, it closes all pooled connections.
Changes to plugin system variable settings may have no effect on connections already in the pool. For example, modifying the LDAP server host, port, or TLS settings does not affect existing connections. However, if the original variable values were invalid and the connection pool could not be initialized, the plugin attempts to reinitialize the pool for the next LDAP request. In this case, the new system variable values are used for the reinitialization attempt.
If
authentication_ldap_sasl_max_pool_size=0
to disable pooling, each LDAP connection opened by the
plugin uses the values the system variables have at that
time.
authentication_ldap_sasl_log_status
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-log-status=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_log_status |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 1 |
Minimum Value | 1 |
Maximum Value | 5 |
For SASL LDAP authentication, the logging level for messages written to the error log. The following table shows the permitted level values and their meanings.
Table 6.21 Log Levels for authentication_ldap_sasl_log_status
Option Value | Types of Messages Logged |
---|---|
1 |
No messages |
2 |
Error messages |
3 |
Error and warning messages |
4 |
Error, warning, and information messages |
5 |
Same as previous level plus debugging messages from MySQL |
On the client side, messages can be logged to the standard
output by setting the
AUTHENTICATION_LDAP_CLIENT_LOG
environment variable. The permitted and default values are
the same as for
authentication_ldap_sasl_log_status
.
The AUTHENTICATION_LDAP_CLIENT_LOG
environment variable applies only to SASL LDAP
authentication. It has no effect for simple LDAP
authentication because the client plugin in that case is
mysql_clear_password
, which knows nothing
about LDAP operations.
authentication_ldap_sasl_max_pool_size
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-max-pool-size=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_max_pool_size |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 1000 |
Minimum Value | 0 |
Maximum Value | 32767 |
For SASL LDAP authentication, the maximum size of the pool of connections to the LDAP server. To disable connection pooling, set this variable to 0.
This variable is used in conjunction with
authentication_ldap_sasl_init_pool_size
.
See the description of that variable.
authentication_ldap_sasl_server_host
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-server-host=host_name |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_server_host |
Scope | Global |
Dynamic | Yes |
Type | String |
For SASL LDAP authentication, the LDAP server host. The permitted values for this variable depend on the authentication method:
For
authentication_ldap_sasl_auth_method_name=SCRAM-SHA-1
:
The LDAP server host can be a host name or IP address.
authentication_ldap_sasl_server_port
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-server-port=port_num |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_server_port |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 389 |
Minimum Value | 1 |
Maximum Value | 32376 |
For SASL LDAP authentication, the LDAP server TCP/IP port number.
As of MySQL 5.7.25, if the LDAP port number is configured as
636 or 3269, the plugin uses LDAPS (LDAP over SSL) instead
of LDAP. (LDAPS differs from startTLS
.)
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-tls[={OFF|ON}] |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_tls |
Scope | Global |
Dynamic | Yes |
Type | Boolean |
Default Value | OFF |
For SASL LDAP authentication, whether connections by the
plugin to the LDAP server are secure. If this variable is
enabled, the plugin uses TLS to connect securely to the LDAP
server. If you enable this variable, you may also wish to
set the
authentication_ldap_sasl_ca_path
variable.
MySQL LDAP plugins support the StartTLS method, which
initializes TLS on top of a plain LDAP connection. The
ldaps
method is deprecated and MySQL does
not support it.
authentication_ldap_sasl_user_search_attr
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-sasl-user-search-attr=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_sasl_user_search_attr |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | uid |
For SASL LDAP authentication, the name of the attribute that
specifies user names in LDAP directory entries. If a user
distinguished name is not provided, the authentication
plugin searches for the name using this attribute. For
example, if the
authentication_ldap_sasl_user_search_attr
value is uid
, a search for the user name
user1
finds entries with a
uid
value of user1
.
authentication_ldap_simple_auth_method_name
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-auth-method-name=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_auth_method_name |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | SIMPLE |
For simple LDAP authentication, the authentication method name. Communication between the authentication plugin and the LDAP server occurs according to this authentication method. These authentication method values are permitted:
SIMPLE
: This authentication method
uses either one or two LDAP bind operations, depending
on whether the MySQL account names an LDAP user
distinguished name. See the description of
authentication_ldap_simple_bind_root_dn
.
AD-FOREST
:
authentication_ldap_simple
searches
all the domains in the Active Directory forest,
performing an LDAP bind to each Active Directory domain
until the user is found in some domain.
For simple LDAP authentication, it is recommended to also set TLS parameters to require that communication with the LDAP server take place over secure connections.
authentication_ldap_simple_bind_base_dn
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-bind-base-dn=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_bind_base_dn |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For simple LDAP authentication, the base distinguished name (DN). This variable can be used to limit the scope of searches by anchoring them at a certain location (the “base”) within the search tree.
Suppose that members of one set of LDAP user entries each have this form:
uid=user_name
,ou=People,dc=example,dc=com
And that members of another set of LDAP user entries each have this form:
uid=user_name
,ou=Admin,dc=example,dc=com
Then searches work like this for different base DN values:
If the base DN is
ou=People,dc=example,dc=com
: Searches
find user entries only in the first set.
If the base DN is
ou=Admin,dc=example,dc=com
: Searches
find user entries only in the second set.
If the base DN is
ou=dc=example,dc=com
: Searches find
user entries in the first or second set.
In general, more specific base DN values result in faster searches because they limit the search scope more.
authentication_ldap_simple_bind_root_dn
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-bind-root-dn=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_bind_root_dn |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For simple LDAP authentication, the root distinguished name
(DN). This variable is used in conjunction with
authentication_ldap_simple_bind_root_pwd
as the credentials for authenticating to the LDAP server for
the purpose of performing searches. Authentication uses
either one or two LDAP bind operations, depending on whether
the MySQL account names an LDAP user DN:
If the account does not name a user DN:
authentication_ldap_simple
performs
an initial LDAP binding using
authentication_ldap_simple_bind_root_dn
and
authentication_ldap_simple_bind_root_pwd
.
(These are both empty by default, so if they are not
set, the LDAP server must permit anonymous connections.)
The resulting bind LDAP handle is used to search for the
user DN, based on the client user name.
authentication_ldap_simple
performs a
second bind using the user DN and client-supplied
password.
If the account does name a user DN: The first bind
operation is unnecessary in this case.
authentication_ldap_simple
performs a
single bind using the user DN and client-supplied
password. This is faster than if the MySQL account does
not specify an LDAP user DN.
authentication_ldap_simple_bind_root_pwd
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-bind-root-pwd=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_bind_root_pwd |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For simple LDAP authentication, the password for the root
distinguished name. This variable is used in conjunction
with
authentication_ldap_simple_bind_root_dn
.
See the description of that variable.
authentication_ldap_simple_ca_path
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-ca-path=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_ca_path |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | NULL |
For simple LDAP authentication, the absolute path of the certificate authority file. Specify this file if it is desired that the authentication plugin perform verification of the LDAP server certificate.
In addition to setting the
authentication_ldap_simple_ca_path
variable to the file name, you must add the appropriate
certificate authority certificates to the file and enable
the
authentication_ldap_simple_tls
system variable.
authentication_ldap_simple_group_search_attr
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-group-search-attr=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_group_search_attr |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | cn |
For simple LDAP authentication, the name of the attribute
that specifies group names in LDAP directory entries. If
authentication_ldap_simple_group_search_attr
has its default value of cn
, searches
return the cn
value as the group name.
For example, if an LDAP entry with a uid
value of user1
has a
cn
attribute of
mygroup
, searches for
user1
return mygroup
as the group name.
As of MySQL 5.7.21, if the group search attribute is
isMemberOf
, LDAP authentication directly
retrieves the user attribute isMemberOf
value and assigns it as group information. If the group
search attribute is not isMemberOf
, LDAP
authentication searches for all groups where the user is a
member. (The latter is the default behavior.) This behavior
is based on how LDAP group information can be stored two
ways: 1) A group entry can have an attribute named
memberUid
or member
with a value that is a user name; 2) A user entry can have
an attribute named isMemberOf
with values
that are group names.
authentication_ldap_simple_group_search_filter
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-group-search-filter=value |
Introduced | 5.7.21 |
System Variable | authentication_ldap_simple_group_search_filter |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | (|(&(objectClass=posixGroup)(memberUid=%s))(&(objectClass=group)(member=%s))) |
For simple LDAP authentication, the custom group search filter.
As of MySQL 5.7.22, the search filter value can contain
{UA}
and {UD}
notation
to represent the user name and the full user DN. For
example, {UA}
is replaced with a user
name such as "admin"
, whereas
{UD}
is replaced with a use full DN such
as
"uid=admin,ou=People,dc=example,dc=com"
.
The following value is the default, which supports both
OpenLDAP and Active Directory:
(|(&(objectClass=posixGroup)(memberUid={UA})) (&(objectClass=group)(member={UD})))
Previously, if the group search attribute was
isMemberOf
or
memberOf
, it was treated as a user
attribute that has group information. However, in some cases
for the user scenario, memberOf
was a
simple user attribute that held no group information. For
additional flexibility, an optional {GA}
prefix now can be used with the group search attribute.
(Previously, it was assumed that if the group search
attribute is isMemberOf
, it will be
treated differently. Now any group attribute with a {GA}
prefix is treated as a user attribute having group names.)
For example, with a value of
{GA}MemberOf
, if the group value is the
DN, the first attribute value from the group DN is returned
as the group name.
In MySQL 5.7.21, the search filter used
%s
notation, expanding it to the user
name for OpenLDAP
(&(objectClass=posixGroup)(memberUid=%s)
)
and to the full user DN for Active Directory
(&(objectClass=group)(member=%s)
).
authentication_ldap_simple_init_pool_size
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-init-pool-size=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_init_pool_size |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 10 |
Minimum Value | 0 |
Maximum Value | 32767 |
For simple LDAP authentication, the initial size of the pool of connections to the LDAP server. Choose the value for this variable based on the average number of concurrent authentication requests to the LDAP server.
The plugin uses
authentication_ldap_simple_init_pool_size
and
authentication_ldap_simple_max_pool_size
together for connection-pool management:
When the authentication plugin initializes, it creates
authentication_ldap_simple_init_pool_size
connections, unless
authentication_ldap_simple_max_pool_size=0
to disable pooling.
If the plugin receives an anthentication request when
there are no free connections in the current connection
pool, the plugin can create a new connection, up to the
maximum connection pool size given by
authentication_ldap_simple_max_pool_size
.
If the plugin receives a request when the pool size is already at its maximum and there are no free connections, authentication fails.
When the plugin unloads, it closes all pooled connections.
Changes to plugin system variable settings may have no effect on connections already in the pool. For example, modifying the LDAP server host, port, or TLS settings does not affect existing connections. However, if the original variable values were invalid and the connection pool could not be initialized, the plugin attempts to reinitialize the pool for the next LDAP request. In this case, the new system variable values are used for the reinitialization attempt.
If
authentication_ldap_simple_max_pool_size=0
to disable pooling, each LDAP connection opened by the
plugin uses the values the system variables have at that
time.
authentication_ldap_simple_log_status
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-log-status=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_log_status |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 1 |
Minimum Value | 1 |
Maximum Value | 5 |
For simple LDAP authentication, the logging level for messages written to the error log. The following table shows the permitted level values and their meanings.
Table 6.22 Log Levels for authentication_ldap_simple_log_status
Option Value | Types of Messages Logged |
---|---|
1 |
No messages |
2 |
Error messages |
3 |
Error and warning messages |
4 |
Error, warning, and information messages |
5 |
Same as previous level plus debugging messages from MySQL |
authentication_ldap_simple_max_pool_size
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-max-pool-size=# |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_max_pool_size |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 1000 |
Minimum Value | 0 |
Maximum Value | 32767 |
For simple LDAP authentication, the maximum size of the pool of connections to the LDAP server. To disable connection pooling, set this variable to 0.
This variable is used in conjunction with
authentication_ldap_simple_init_pool_size
.
See the description of that variable.
authentication_ldap_simple_server_host
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-server-host=host_name |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_server_host |
Scope | Global |
Dynamic | Yes |
Type | String |
For simple LDAP authentication, the LDAP server host. The permitted values for this variable depend on the authentication method:
For
authentication_ldap_simple_auth_method_name=SIMPLE
:
The LDAP server host can be a host name or IP address.
For
authentication_ldap_simple_auth_method_name=AD-FOREST
.
The LDAP server host can be an Active Directory domain
name. For example, for an LDAP server URL of
ldap://example.mem.local:389
, the
server name can be mem.local
.
An Active Directory forest setup can have multiple domains (LDAP server IPs), which can be discovered using DNS. On Unix and Unix-like systems, some additional setup may be required to configure your DNS server with SRV records that specify the LDAP servers for the Active Directory domain. Suppose that your configuration has these properties:
The name server that provides information about
Active Directory domains has IP address
10.172.166.100
.
The LDAP servers have names
ldap1.mem.local
through
ldap3.mem.local
and IP addresses
10.172.166.101
through
10.172.166.103
.
You want the LDAP servers to be discoverable using SRV searches. For example, at the command line, a command like this should list the LDAP servers:
host -t SRV _ldap._tcp.mem.local
Perform the DNS configuration as follows:
Add a line to /etc/resolv.conf
to specify the name server that provides information
about Active Directory domains:
nameserver 10.172.166.100
Configure the appropriate zone file for the name server with SRV records for the LDAP servers:
_ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap1.mem.local. _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap2.mem.local. _ldap._tcp.mem.local. 86400 IN SRV 0 100 389 ldap3.mem.local.
It may also be necessary to specify the IP address
for the LDAP servers in
/etc/hosts
if the server host
cannot be resolved. For example, add lines like this
to the file:
10.172.166.101 ldap1.mem.local 10.172.166.102 ldap2.mem.local 10.172.166.103 ldap3.mem.local
With the DNS configured as just described, the server-side LDAP plugin can discover the LDAP servers and will try to authenticate in all domains until authentication succeeds or there are no more servers.
Windows needs no such settings as just described. Given
the LDAP server host in the
authentication_ldap_simple_server_host
value, the Windows LDAP library searches all domains and
attempts to authenticate.
authentication_ldap_simple_server_port
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-server-port=port_num |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_server_port |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 389 |
Minimum Value | 1 |
Maximum Value | 32376 |
For simple LDAP authentication, the LDAP server TCP/IP port number.
As of MySQL 5.7.25, if the LDAP port number is configured as
636 or 3269, the plugin uses LDAPS (LDAP over SSL) instead
of LDAP. (LDAPS differs from startTLS
.)
authentication_ldap_simple_tls
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-tls[={OFF|ON}] |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_tls |
Scope | Global |
Dynamic | Yes |
Type | Boolean |
Default Value | OFF |
For simple LDAP authentication, whether connections by the
plugin to the LDAP server are secure. If this variable is
enabled, the plugin uses TLS to connect securely to the LDAP
server. If you enable this variable, you may also wish to
set the
authentication_ldap_simple_ca_path
variable.
MySQL LDAP plugins support the StartTLS method, which
initializes TLS on top of a plain LDAP connection. The
ldaps
method is deprecated and MySQL does
not support it.
authentication_ldap_simple_user_search_attr
Property | Value |
---|---|
Command-Line Format | --authentication-ldap-simple-user-search-attr=value |
Introduced | 5.7.19 |
System Variable | authentication_ldap_simple_user_search_attr |
Scope | Global |
Dynamic | Yes |
Type | String |
Default Value | uid |
For simple LDAP authentication, the name of the attribute
that specifies user names in LDAP directory entries. If a
user distinguished name is not provided, the authentication
plugin searches for the name using this attribute. For
example, if the
authentication_ldap_simple_user_search_attr
value is uid
, a search for the user name
user1
finds entries with a
uid
value of user1
.
As of MySQL 5.7.17, MySQL Server includes a plugin library that enables administrators to introduce an increasing delay in server response to clients after a certain number of consecutive failed connection attempts. This capability provides a deterrent that slows down brute force attacks that attempt to access MySQL user accounts. The plugin library contains two plugins:
CONNECTION_CONTROL
checks incoming
connections and adds a delay to server responses as necessary.
This plugin also exposes system variables that enable its
operation to be configured and a status variable that provides
rudimentary monitoring information.
The CONNECTION_CONTROL
plugin uses the
audit plugin interface (see
Section 28.2.4.8, “Writing Audit Plugins”). To collect
information, it subscribes to the
MYSQL_AUDIT_CONNECTION_CLASSMASK
event
class, and processes
MYSQL_AUDIT_CONNECTION_CONNECT
and
MYSQL_AUDIT_CONNECTION_CHANGE_USER
subevents to check whether the server should introduce a delay
before responding to client connection attempts.
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
implements an INFORMATION_SCHEMA
table that
exposes more detailed monitoring information for failed
connection attempts.
The following sections provide information about
connection-control plugin installation and configuration. For
information about the
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
table, see
Section 24.34.1, “The INFORMATION_SCHEMA CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS Table”.
This section describes how to install the connection-control
plugins, CONNECTION_CONTROL
and
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
. For
general information about installing plugins, see
Section 5.5.1, “Installing and Uninstalling Plugins”.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory location
by setting the value of
plugin_dir
at server startup.
The plugin library file base name is
connection_control
. The file name suffix
differs per platform (for example, .so
for
Unix and Unix-like systems, .dll
for
Windows).
To load the plugins at server startup, use the
--plugin-load-add
option to name
the library file that contains them. With this plugin-loading
method, the option must be given each time the server starts.
For example, put these lines in the server
my.cnf
file (adjust the
.so
suffix for your platform as necessary):
[mysqld] plugin-load-add=connection_control.so
After modifying my.cnf
, restart the server
to cause the new settings to take effect.
Alternatively, to load the plugins at runtime, use these
statements (adjust the .so
suffix for your
platform as necessary):
INSTALL PLUGIN CONNECTION_CONTROL SONAME 'connection_control.so'; INSTALL PLUGIN CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS SONAME 'connection_control.so';
INSTALL PLUGIN
loads the plugin
immediately, and also registers it in the
mysql.plugins
system table to cause the
server to load it for each subsequent normal startup without the
need for --plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table or
use the SHOW PLUGINS
statement
(see Section 5.5.2, “Obtaining Server Plugin Information”). For
example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE 'connection%';
+------------------------------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +------------------------------------------+---------------+ | CONNECTION_CONTROL | ACTIVE | | CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS | ACTIVE | +------------------------------------------+---------------+
If a plugin fails to initialize, check the server error log for diagnostic messages.
If the plugins have been previously registered with
INSTALL PLUGIN
or are loaded with
--plugin-load-add
, you can use
the --connection-control
and
--connection-control-failed-login-attempts
options at server startup to control plugin activation. For
example, to load the plugins at startup and prevent them from
being removed at runtime, use these options:
[mysqld] plugin-load-add=connection_control.so connection-control=FORCE_PLUS_PERMANENT connection-control-failed-login-attempts=FORCE_PLUS_PERMANENT
If it is desired to prevent the server from running without a
given connection-control plugin, use an option value of
FORCE
or
FORCE_PLUS_PERMANENT
to force server startup
to fail if the plugin does not initialize successfully.
It is possible to install one plugin without the other, but
both must be installed for full connection-control capability.
In particular, installing only the
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
plugin is of little use because without the
CONNECTION_CONTROL
plugin to provide the
data that populates the
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
table, retrievals from the table will always be empty.
To enable you to configure its operation, the
CONNECTION_CONTROL
plugin exposes several
system variables:
connection_control_failed_connections_threshold
:
The number of consecutive failed connection attempts
permitted to clients before the server adds a delay for
subsequent connection attempts.
connection_control_min_connection_delay
:
The amount of delay to add for each consecutive connection
failure above the threshold.
connection_control_max_connection_delay
:
The maximum delay to add.
To entirely disable checking for failed connection attempts,
set
connection_control_failed_connections_threshold
to zero. If
connection_control_failed_connections_threshold
is nonzero, the amount of delay is zero up through that many
consecutive failed connection attempts. Thereafter, the amount
of delay is the number of failed attempts above the threshold,
multiplied by
connection_control_min_connection_delay
milliseconds. For example, with the default
connection_control_failed_connections_threshold
and
connection_control_min_connection_delay
values of 3 and 1000, respectively, there is no delay for the
first three consecutive failed connection attempts by a
client, a delay of 1000 milliseconds for the fourth failed
attempt, 2000 milliseconds for the fifth failed attempt, and
so on, up to the maximum delay permitted by
connection_control_max_connection_delay
.
You can set the CONNECTION_CONTROL
system
variables at server startup or runtime. Suppose that you want
to permit four consecutive failed connection attempts before
the server starts delaying its responses, and to increase the
delay by 1500 milliseconds for each additional failure after
that. To set the relevant variables at server startup, put
these lines in the server my.cnf
file:
[mysqld] plugin-load-add=connection_control.so connection_control_failed_connections_threshold=4 connection_control_min_connection_delay=1500
To set the variables at runtime, use these statements:
SET GLOBAL connection_control_failed_connections_threshold = 4; SET GLOBAL connection_control_min_connection_delay = 1500;
SET
GLOBAL
sets the value for the running MySQL
instance. To make the change permanent, add a line in your
my.cnf
file, as shown previously.
The
connection_control_min_connection_delay
and
connection_control_max_connection_delay
system variables have fixed minimum and maximum values of 1000
and 2147483647, respectively. In addition, the permitted range
of values of each variable also depends on the current value
of the other:
connection_control_min_connection_delay
cannot be set greater than the current value of
connection_control_max_connection_delay
.
connection_control_max_connection_delay
cannot be set less than the current value of
connection_control_min_connection_delay
.
Thus, to make the changes required for some configurations,
you might need to set the variables in a specific order.
Suppose that the current minimum and maximum delays are 1000
and 2000, and that you want to set them to 3000 and 5000. You
cannot first set
connection_control_min_connection_delay
to 3000 because that is greater than the current
connection_control_max_connection_delay
value of 2000. Instead, set
connection_control_max_connection_delay
to 5000, then set
connection_control_min_connection_delay
to 3000.
When the CONNECTION_CONTROL
plugin is
installed, it checks connection attempts and tracks whether
they fail or succeed. For this purpose, a failed connection
attempt is one for which the client user and host match a
known MySQL account but the provided credentials are
incorrect, or do not match any known account.
Failed-connection counting is based on the user/host combination for each connection attempt. Determination of the applicable user name and host name takes proxying into account and occurs as follows:
If the client user proxies another user, the proxying
user's information is used. For example, if
external_user@example.com
proxies
proxy_user@example.com
, connection
counting uses the proxying user,
external_user@example.com
, rather than
the proxied user,
proxy_user@example.com
. Both
external_user@example.com
and
proxy_user@example.com
must have valid
entries in the mysql.user
system table
and a proxy relationship between them must be defined in
the mysql.proxies_priv
system table
(see Section 6.2.14, “Proxy Users”).
If the client user does not proxy another user, but does
match a mysql.user
entry, counting uses
the CURRENT_USER()
value
corresponding to that entry. For example, if a user
user1
connecting from a host
host1.example.com
matches a
user1@host1.example.com
entry, counting
uses user1@host1.example.com
. If the
user matches a user1@%.example.com
,
user1@%.com
, or
user1@%
entry instead, counting uses
user1@%.example.com
,
user1@%.com
, or
user1@%
, respectively.
For the cases just described, the connection attempt matches
some mysql.user
entry, and whether the
request succeeds or fails depends on whether the client
provides the correct authentication credentials. For example,
if the client presents an incorrect password, the connection
attempt fails.
If the connection attempt matches no
mysql.user
entry, the attempt fails. In
this case, no CURRENT_USER()
value is available and connection-failure counting uses the
user name provided by the client and the client host as
determined by the server. For example, if a client attempts to
connect as user user2
from host
host2.example.com
, the user name part is
available in the client request and the server determines the
host information. The user/host combination used for counting
is user2@host2.example.com
.
The server maintains information about which client hosts
can possibly connect to the server (essentially the union of
host values for mysql.user
entries). If a
client attempts to connect from any other host, the server
rejects the attempt at an early stage of connection setup:
ERROR 1130 (HY000): Host 'host_name
' is not
allowed to connect to this MySQL server
Because this type of rejection occurs so early,
CONNECTION_CONTROL
does not see it, and
does not count it.
To monitor failed connections, use these information sources:
The
Connection_control_delay_generated
status variable indicates the number of times the server
added a delay to its response to a failed connection
attempt. This does not count attempts that occur before
reaching the threshold defined by the
connection_control_failed_connections_threshold
system variable.
The INFORMATION_SCHEMA
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
table provides information about the current number of
consecutive failed connection attempts per client
user/host combination. This counts all failed attempts,
regardless of whether they were delayed.
Assigning a value to
connection_control_failed_connections_threshold
at runtime resets all accumulated failed-connection counters
to zero, which has these visible effects:
The
Connection_control_delay_generated
status variable is reset to zero.
The
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
table becomes empty.
This section describes the system and status variables that the
CONNECTION_CONTROL
plugin provides to enable
its operation to be configured and monitored.
If the CONNECTION_CONTROL
plugin is
installed, it exposes these system variables:
connection_control_failed_connections_threshold
Property | Value |
---|---|
Command-Line Format | --connection-control-failed-connections-threshold=# |
Introduced | 5.7.17 |
System Variable | connection_control_failed_connections_threshold |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 3 |
Minimum Value | 0 |
Maximum Value | 2147483647 |
The number of consecutive failed connection attempts permitted to clients before the server adds a delay for subsequent connection attempts:
If the variable has a nonzero value
N
, the server adds a delay
beginning with consecutive failed attempt
N
+1. If a client has
reached the point where connection responses are
delayed, the delay also occurs for the next subsequent
successful connection.
Setting this variable to zero disables failed-connection counting. In this case, the server never adds delays.
For information about how
connection_control_failed_connections_threshold
interacts with other connection-control system and status
variables, see
Section 6.4.2.1, “Connection-Control Plugin Installation”.
connection_control_max_connection_delay
Property | Value |
---|---|
Command-Line Format | --connection-control-max-connection-delay=# |
Introduced | 5.7.17 |
System Variable | connection_control_max_connection_delay |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 2147483647 |
Minimum Value | 1000 |
Maximum Value | 2147483647 |
The maximum delay in milliseconds for server response to
failed connection attempts, if
connection_control_failed_connections_threshold
is greater than zero.
For information about how
connection_control_max_connection_delay
interacts with other connection-control system and status
variables, see
Section 6.4.2.1, “Connection-Control Plugin Installation”.
connection_control_min_connection_delay
Property | Value |
---|---|
Command-Line Format | --connection-control-min-connection-delay=# |
Introduced | 5.7.17 |
System Variable | connection_control_min_connection_delay |
Scope | Global |
Dynamic | Yes |
Type | Integer |
Default Value | 1000 |
Minimum Value | 1000 |
Maximum Value | 2147483647 |
The minimum delay in milliseconds for server response to
failed connection attempts, if
connection_control_failed_connections_threshold
is greater than zero. This is also the amount by which the
server increases the delay for additional successive
failures once it begins delaying.
For information about how
connection_control_min_connection_delay
interacts with other connection-control system and status
variables, see
Section 6.4.2.1, “Connection-Control Plugin Installation”.
If the CONNECTION_CONTROL
plugin is
installed, it exposes this status variable:
Connection_control_delay_generated
The number of times the server added a delay to its
response to a failed connection attempt. This does not
count attempts that occur before reaching the threshold
defined by the
connection_control_failed_connections_threshold
system variable.
This variable provides a simple counter. For more detailed
connection-control monitoring information, examine the
INFORMATION_SCHEMA
CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS
table; see
Section 24.34.1, “The INFORMATION_SCHEMA CONNECTION_CONTROL_FAILED_LOGIN_ATTEMPTS Table”.
Assigning a value to
connection_control_failed_connections_threshold
at runtime resets
Connection_control_delay_generated
to zero.
This variable was added in MySQL 5.7.17.
The validate_password
plugin serves to improve
security by requiring account passwords and enabling strength
testing of potential passwords. This plugin exposes a set of
system variables that enable you to configure password policy.
The validate_password
plugin implements these
capabilities:
For SQL statements that assign a password supplied as a
cleartext value, validate_password
checks
the password against the current password policy and rejects
the password if it is weak (the statement returns an
ER_NOT_VALID_PASSWORD
error).
This applies to the ALTER USER
,
CREATE USER
,
GRANT
, and
SET PASSWORD
statements, and
passwords given as arguments to the
PASSWORD()
and function.
For CREATE USER
statements,
validate_password
requires that a password
be given, and that it satisfies the password policy. This is
true even if an account is locked initially because otherwise
unlocking the account later would cause it to become
accessible without a password that satisfies the policy.
validate_password
implements a
VALIDATE_PASSWORD_STRENGTH()
SQL function that assesses the strength of potential
passwords. This function takes a password argument and returns
an integer from 0 (weak) to 100 (strong).
For statements that assign, modify, or generate account
passwords (ALTER USER
,
CREATE USER
,
GRANT
, and
SET PASSWORD
; statements that use
PASSWORD()
, the
validate_password
capabilities described here
apply only to accounts that use an authentication plugin that
stores credentials internally to MySQL. For accounts that use
plugins that perform authentication against a credentials system
external to MySQL, password management must be handled
externally against that system as well. For more information
about internal credentials storage, see
Section 6.2.11, “Password Management”.
The preceding restriction does not apply to use of the
VALIDATE_PASSWORD_STRENGTH()
function because it does not affect accounts directly.
Examples:
validate_password
checks the cleartext
password in the following statement. Under the default
password policy, which requires passwords to be at least 8
characters long, the password is weak and the statement
produces an error:
mysql> ALTER USER USER() IDENTIFIED BY 'abc';
ERROR 1819 (HY000): Your password does not satisfy the current
policy requirements
Passwords specified as hashed values are not checked because the original password value is not available for checking:
mysql>ALTER USER 'jeffrey'@'localhost'
IDENTIFIED WITH mysql_native_password
AS '*0D3CED9BEC10A777AEC23CCC353A8C08A633045E';
Query OK, 0 rows affected (0.01 sec)
This account-creation statement fails, even though the account is locked initially, because it does not include a password that satisfies the current password policy:
mysql> CREATE USER 'juanita'@'localhost' ACCOUNT LOCK;
ERROR 1819 (HY000): Your password does not satisfy the current
policy requirements
To check a password, use the
VALIDATE_PASSWORD_STRENGTH()
function:
mysql>SELECT VALIDATE_PASSWORD_STRENGTH('weak');
+------------------------------------+ | VALIDATE_PASSWORD_STRENGTH('weak') | +------------------------------------+ | 25 | +------------------------------------+ mysql>SELECT VALIDATE_PASSWORD_STRENGTH('lessweak$_@123');
+----------------------------------------------+ | VALIDATE_PASSWORD_STRENGTH('lessweak$_@123') | +----------------------------------------------+ | 50 | +----------------------------------------------+ mysql>SELECT VALIDATE_PASSWORD_STRENGTH('N0Tweak$_@123!');
+----------------------------------------------+ | VALIDATE_PASSWORD_STRENGTH('N0Tweak$_@123!') | +----------------------------------------------+ | 100 | +----------------------------------------------+
To configure password checking, modify the system variables having
names of the form
validate_password_
;
these are the parameters that control password policy. See
Section 6.4.3.2, “Password Validation Plugin Options and Variables”.
xxx
If validate_password
is not installed, the
validate_password_
system variables are not available, passwords in statements are
not checked, and the
xxx
VALIDATE_PASSWORD_STRENGTH()
function always returns 0. For example, without the plugin
installed, accounts can be assigned passwords shorter than 8
characters, or no password at all.
Assuming that validate_password
is installed,
it implements three levels of password checking:
LOW
, MEDIUM
, and
STRONG
. The default is
MEDIUM
; to change this, modify the value of
validate_password_policy
. The
policies implement increasingly strict password tests. The
following descriptions refer to default parameter values, which
can be modified by changing the appropriate system variables.
LOW
policy tests password length only.
Passwords must be at least 8 characters long. To change this
length, modify
validate_password_length
.
MEDIUM
policy adds the conditions that
passwords must contain at least 1 numeric character, 1
lowercase character, 1 uppercase character, and 1 special
(nonalphanumeric) character. To change these values, modify
validate_password_number_count
,
validate_password_mixed_case_count
,
and
validate_password_special_char_count
.
STRONG
policy adds the condition that
password substrings of length 4 or longer must not match words
in the dictionary file, if one has been specified. To specify
the dictionary file, modify
validate_password_dictionary_file
.
In addition, as of MySQL 5.7.15,
validate_password
supports the capability of
rejecting passwords that match the user name part of the effective
user account for the current session, either forward or in
reverse. To provide control over this capability,
validate_password
exposes a
validate_password_check_user_name
system variable, which is enabled by default.
This section describes how to install the
validate_password
password-validation plugin.
For general information about installing plugins, see
Section 5.5.1, “Installing and Uninstalling Plugins”.
If you installed MySQL 5.7 using the
MySQL Yum
repository,
MySQL SLES
Repository, or
RPM packages provided
by Oracle, validate_password
is
enabled by default after you start your MySQL Server for the
first time.
To be usable by the server, the plugin library file must be
located in the MySQL plugin directory (the directory named by
the plugin_dir
system
variable). If necessary, configure the plugin directory location
by setting the value of
plugin_dir
at server startup.
The plugin library file base name is
validate_password
. The file name suffix
differs per platform (for example, .so
for
Unix and Unix-like systems, .dll
for
Windows).
To load the plugin at server startup, use the
--plugin-load-add
option to name
the library file that contains it. With this plugin-loading
method, the option must be given each time the server starts.
For example, put these lines in the server
my.cnf
file (adjust the
.so
suffix for your platform as necessary):
[mysqld] plugin-load-add=validate_password.so
After modifying my.cnf
, restart the server
to cause the new settings to take effect.
Alternatively, to load the plugin at runtime, use this statement
(adjust the .so
suffix for your platform as
necessary):
INSTALL PLUGIN validate_password SONAME 'validate_password.so';
INSTALL PLUGIN
loads the plugin,
and also registers it in the mysql.plugins
system table to cause the plugin to be loaded for each
subsequent normal server startup without the need for
--plugin-load-add
.
To verify plugin installation, examine the
INFORMATION_SCHEMA.PLUGINS
table or
use the SHOW PLUGINS
statement
(see Section 5.5.2, “Obtaining Server Plugin Information”). For
example:
mysql>SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME LIKE 'validate%';
+-------------------+---------------+ | PLUGIN_NAME | PLUGIN_STATUS | +-------------------+---------------+ | validate_password | ACTIVE | +-------------------+---------------+
If the plugin fails to initialize, check the server error log for diagnostic messages.
If the plugin has been previously registered with
INSTALL PLUGIN
or is loaded with
--plugin-load-add
, you can use
the --validate-password
option at server
startup to control plugin activation. For example, to load the
plugin at startup and prevent it from being removed at runtime,
use these options:
[mysqld] plugin-load-add=validate_password.so validate-password=FORCE_PLUS_PERMANENT
If it is desired to prevent the server from running without the
password-validation plugin, use
--validate-password
with a value
of FORCE
or
FORCE_PLUS_PERMANENT
to force server startup
to fail if the plugin does not initialize successfully.
This section describes the options, system variables, and status
variables that validate_password
provides to
enable its operation to be configured and monitored.
To control activation of the
validate_password
plugin, use this option:
Property | Value |
---|---|
Command-Line Format | --validate-password[=value] |
Type | Enumeration |
Default Value | ON |
Valid Values |
|
This option controls how the server loads the
validate_password
plugin at startup.
The value should be one of those available for
plugin-loading options, as described in
Section 5.5.1, “Installing and Uninstalling Plugins”. For example,
--validate-password=FORCE_PLUS_PERMANENT
tells the server to load the plugin at startup and
prevents it from being removed while the server is
running.
This option is available only if the
validate_password
plugin has been
previously registered with INSTALL
PLUGIN
or is loaded with
--plugin-load-add
. See
Section 6.4.3.1, “Password Validation Plugin Installation”.
If the validate_password
plugin is enabled,
it exposes several system variables that enable configuration
of password checking:
mysql> SHOW VARIABLES LIKE 'validate_password%';
+--------------------------------------+--------+
| Variable_name | Value |
+--------------------------------------+--------+
| validate_password_check_user_name | OFF |
| validate_password_dictionary_file | |
| validate_password_length | 8 |
| validate_password_mixed_case_count | 1 |
| validate_password_number_count | 1 |
| validate_password_policy | MEDIUM |
| validate_password_special_char_count | 1 |
+--------------------------------------+--------+
To change how passwords are checked, you can set these system variables at server startup or at runtime. The following list describes the meaning of each variable.
validate_password_check_user_name
Property | Value |
---|---|
Command-Line Format | --validate-password-check-user-name[={OFF|ON}] |
Introduced | 5.7.15 |
System Variable | validate_password_check_user_name |
Scope | Global |
Dynamic | Yes |
Type | Boolean |
Default Value | OFF |
Whether validate_password
compares
passwords to the user name part of the effective user
account for the current session and rejects them if they
match. This variable is unavailable unless
validate_password
is installed.
By default,
validate_password_check_user_name
is disabled. This variable controls user name matching
independent of the value of
validate_password_policy
.
When
validate_password_check_user_name
is enabled, it has these effects:
Checking occurs in all contexts for which
validate_password
is invoked, which
includes use of statements such as
ALTER USER
or
SET PASSWORD
to change
the current user's password, and invocation of
functions such as
PASSWORD()
and
VALIDATE_PASSWORD_STRENGTH()
.
The user names used for comparison are taken from the
values of the USER()
and CURRENT_USER()
functions for the current session. An implication is
that a user who has sufficient privileges to set
another user's password can set the password to that
user's name, and cannot set that user's password to
the name of the user executing the statement. For
example, 'root'@'localhost'
can set
the password for
'jeffrey'@'localhost'
to
'jeffrey'
, but cannot set the
password to 'root
.
Only the user name part of the
USER()
and
CURRENT_USER()
function
values is used, not the host name part. If a user name
is empty, no comparison occurs.
If a password is the same as the user name or its reverse, a match occurs and the password is rejected.
User-name matching is case-sensitive. The password and user name values are compared as binary strings on a byte-by-byte basis.
If a password matches the user name,
VALIDATE_PASSWORD_STRENGTH()
returns 0 regardless of how other
validate_password
system variables
are set.
validate_password_dictionary_file
Property | Value |
---|---|
Command-Line Format | --validate-password-dictionary-file=file_name |
System Variable | validate_password_dictionary_file |
Scope | Global |
Dynamic | Yes |
Type | File name |
The path name of the dictionary file that
validate_password
uses for checking
passwords. This variable is unavailable unless
validate_password
is installed.
By default, this variable has an empty value and dictionary checks are not performed. For dictionary checks to occur, the variable value must be nonempty. If the file is named as a relative path, it is interpreted relative to