ALTER USER
MariaDB starting with 10.2.0
The ALTER USER statement was introduced in MariaDB 10.2.0.
Syntax
ALTER USER [IF EXISTS] user_specification [,user_specification] ... [REQUIRE {NONE | tls_option [[AND] tls_option] ...}] [WITH resource_option [resource_option] ...] user_specification: username [authentication_option] authentication_option: IDENTIFIED BY 'password' | IDENTIFIED BY PASSWORD 'password_hash' | IDENTIFIED {VIA|WITH} authentication_plugin | IDENTIFIED {VIA|WITH} authentication_plugin {USING|AS} 'authentication_string' | IDENTIFIED {VIA|WITH} authentication_plugin {USING|AS} PASSWORD('password') tls_option SSL | X509 | CIPHER 'cipher' | ISSUER 'issuer' | SUBJECT 'subject' resource_option MAX_QUERIES_PER_HOUR count | MAX_UPDATES_PER_HOUR count | MAX_CONNECTIONS_PER_HOUR count | MAX_USER_CONNECTIONS count | MAX_STATEMENT_TIME time
Contents
Description
The ALTER USER
statement modifies existing MariaDB accounts. To use it, you must have the global CREATE USER
privilege or the UPDATE
privilege for the mysql
database. The global SUPER
privilege is also required if the read_only
system variable is enabled.
If any of the specified user accounts do not yet exist, an error results. If an error occurs, ALTER USER
will still modify the accounts that do not result in an error. Only one error is produced for all users which have not been modified.
IF EXISTS
When the IF EXISTS
clause is used, MariaDB will return a warning instead of an error for each specified user that does not exist.
Account Names
For ALTER USER
statements, account names are specified as the username
argument in the same way as they are for CREATE USER
statements. See account names from the CREATE USER
page for details on how account names are specified.
CURRENT_USER
or CURRENT_USER()
can also be used to alter the account logged into the current session. For example, to change the current user's password to mariadb
:
ALTER USER CURRENT_USER() IDENTIFIED BY 'mariadb';
Authentication Options
IDENTIFIED BY 'password'
The optional IDENTIFIED BY
clause can be used to provide an account with a password. The password should be specified in plain text. It will be hashed by the PASSWORD
function prior to being stored to the mysql.user
table.
For example, if our password is mariadb
, then we can set the account's password with:
ALTER USER foo2@test IDENTIFIED BY 'mariadb';
If you do not specify a password with the IDENTIFIED BY
clause, the user
will be able to connect without a password. A blank password is not a wildcard
to match any password. The user must connect without providing a password if no
password is set.
The only authentication plugins that this clause supports are mysql_native_password
and mysql_old_password
.
IDENTIFIED BY PASSWORD 'password_hash'
The optional IDENTIFIED BY PASSWORD
clause can be used to provide an account with a password that has already been hashed. The password should be specified as a hash that was provided by the PASSWORD
function. It will be stored to the mysql.user
table as-is.
For example, if our password is mariadb
, then we can find the hash with:
SELECT PASSWORD('mariadb'); +-------------------------------------------+ | PASSWORD('mariadb') | +-------------------------------------------+ | *54958E764CE10E50764C2EECBB71D01F08549980 | +-------------------------------------------+ 1 row in set (0.00 sec)
And then we can set an account's password with the hash:
ALTER USER foo2@test IDENTIFIED BY PASSWORD '*54958E764CE10E50764C2EECBB71D01F08549980';
If you do not specify a password with the IDENTIFIED BY
clause, the user
will be able to connect without a password. A blank password is not a wildcard
to match any password. The user must connect without providing a password if no
password is set.
The only authentication plugins that this clause supports are mysql_native_password
and mysql_old_password
.
IDENTIFIED {VIA|WITH} authentication_plugin
The optional IDENTIFIED VIA authentication_plugin
allows you to specify that the account should be authenticated by a specific authentication plugin. The plugin name must be an active authentication plugin as per SHOW PLUGINS
. If it doesn't show up in that output, then you will need to install it with INSTALL PLUGIN
or INSTALL SONAME
.
For example, this could be used with the PAM authentication plugin:
ALTER USER foo2@test IDENTIFIED VIA pam;
Some authentication plugins allow additional arguments to be specified after a USING
or AS
keyword. For example, the PAM authentication plugin accepts a service name:
ALTER USER foo2@test IDENTIFIED VIA pam USING 'mariadb';
The exact meaning of the additional argument would depend on the specific authentication plugin.
In MariaDB 10.4 and later, the USING
or AS
keyword can also be used to provide a plain-text password to a plugin if it's provided as an argument to the PASSWORD() function. This is only valid for authentication plugins that have implemented a hook for the PASSWORD() function. For example, the ed25519
authentication plugin supports this:
ALTER USER safe@'%' IDENTIFIED VIA ed25519 USING PASSWORD('secret');
TLS Options
By default, MariaDB uses unencrypted connections for all client/server communications. In order to use encrypted connections, OpenSSL or yaSSL must be present in your system. Also, the MariaDB server needs to be built with TLS support and be properly configured to use one of them. See Secure Connections Overview for more information about that.
TLS is the modern term to describe the encryption protocol. SSL refers to the old, now insecure, protocol that preceded TLS. Many of the variable names and options still refer to SSL, rather than TLS, for compatibility reasons. However, MariaDB only uses its more secure successors.
You can require TLS connections on a per-account basis, using the REQUIRE
clause. The following options are available:
Option | Description |
---|---|
REQUIRE NONE | TLS is not required for this account, but can still be used. |
REQUIRE SSL | The account must use TLS, but no valid X509 certificate is required. |
REQUIRE X509 | The account must use TLS and must have a valid X509 certificate. |
REQUIRE ISSUER 'issuer' | The account must use TLS and must have a valid X509 certificate. Also, the Certificate Authority must be the one specified via the string issuer . |
REQUIRE SUBJECT 'subject' | The account must use TLS and must have a valid X509 certificate. Also, the certificate's Subject must be the one specified via the string subject . |
REQUIRE CIPHER 'cipher' | The account must use TLS and must have a valid X509 certificate. Also, the encryption used for the connection must use one of the methods specified in the string cipher . |
If you set REQUIRE X509
, then REQUIRE SSL
is implicitly set. The ISSUER
, SUBJECT
, and CIPHER
options can be set together in any order, and if you set any of them, then REQUIRE X509
is also implicitly set.
The REQUIRE
keyword must be used only once for all specified options, and the AND
keyword can be used to separate individual options, but it is not required.
If any of these options are set for a specific user, then any client who tries to connect with that user will have to be configured to connect with TLS. For example, the mysql
client can be configured to do so by setting options like --ssl
, --ssl-ca
, --ssl-cert
, --ssl-cipher
, --ssl-key
, and --ssl-verify-server-cert
.
For example, you can set an account's TLS options with the following:
ALTER USER 'someone'@'localhost' REQUIRE SUBJECT '/CN=www.mydom.com/O=My Dom, Inc./C=US/ST=Oregon/L=Portland' AND ISSUER '/C=FI/ST=Somewhere/L=City/ O=Some Company/CN=Peter Parker/emailAddress=p.parker@marvel.com' AND CIPHER 'SHA-DES-CBC3-EDH-RSA';
Resource Limit Options
MariaDB starting with 10.2.0
MariaDB 10.2.0 introduced a number of resource limit options.
It is possible to set per-account limits for certain server resources. The following table shows the values that can be set per account:
Limit Type | Decription |
---|---|
MAX_QUERIES_PER_HOUR | Number of statements that the account can issue per hour (including updates) |
MAX_UPDATES_PER_HOUR | Number of updates (not queries) that the account can issue per hour |
MAX_CONNECTIONS_PER_HOUR | Number of connections that the account can start per hour |
MAX_USER_CONNECTIONS | Number of simultaneous connections that can be accepted from the same account; if it is 0, max_connections will be used instead; if max_connections is 0, there is no limit for this account's simultaneous connections. |
MAX_STATEMENT_TIME | Timeout, in seconds, for statements executed by the user. See also Aborting Statements that Exceed a Certain Time to Execute. |
If any of these limits are set to 0
, then there is no limit for that resource for that user.
Here is an example showing how to set an account's resource limits:
ALTER USER 'someone'@'localhost' WITH MAX_USER_CONNECTIONS 10 MAX_QUERIES_PER_HOUR 200;
The resources are tracked per account, which means 'user'@'server'
; not per user name or per connection.
The count can be reset for all users using FLUSH USER_RESOURCES
, FLUSH PRIVILEGES
or mysqladmin reload
.
Per account resource limits are stored in the user
table, in the mysql
database. Columns used for resources limits are named max_questions
, max_updates
, max_connections
(for MAX_CONNECTIONS_PER_HOUR
), and max_user_connections
(for MAX_USER_CONNECTIONS
).
See Also
- GRANT
- CREATE USER
- DROP USER
- SET PASSWORD
- SHOW CREATE USER
- mysql.user table
- Password Validation Plugins - permits the setting of basic criteria for passwords
- Authentication Plugins - allow various authentication methods to be used, and new ones to be developed.