12.1 Account Password and Authentication Utilities

The util global object provides the following functions for changing account passwords and upgrading accounts from the deprecated mysql_native_password authentication plugin to caching_sha2_password.

A value supplied for account must be a fully qualified account name, for example, app@%. An error is reported if the account does not exist or the connected account has insufficient privileges.

Important

Passwords entered at prompts or supplied in an options dictionary are not written to the MySQL Shell application log or history file.

About the Utilities

• util.changePassword(): Change the password for current or named accounts.The function supports explicit and randomly generated passwords, retaining the existing password as a secondary password, and discarding a secondary password.

  When changePassword() operates on an account that uses mysql_native_password, MySQL Shell displays a warning recommending that you use upgradeAuthMethod() to change the authentication plugin. MySQL Shell also displays this warning when an interactive session is established using an account that authenticates with mysql_native_password.

• util.upgradeAuthMethod(): Migrate mysql_native_password accounts to caching_sha2_password.

Note

The mysql_native_password authentication plugin was deprecated in MySQL 8.0.34, disabled by default in MySQL 8.4, and removed in MySQL 9.0. For more information, see Native Pluggable Authentication and Caching SHA-2 Pluggable Authentication.

Requirements and Restrictions

These utilities require the following:

• Changing another account requires the global CREATE USER privilege or the UPDATE privilege for the mysql system schema.

• Retaining or discarding a secondary password for your own account requires the APPLICATION_PASSWORD_ADMIN privilege.

• Retaining or discarding secondary passwords for other accounts requires the CREATE USER privilege.

• upgradeAuthMethod() modifies an account only if it uses mysql_native_password. If the account does not use that authentication plugin, the utility displays a note and makes no changes.

Change Password Utility

util.changePassword() has the following signature:

        util.changePassword(Dictionary options)

The options argument is optional. If it is omitted, the utility prompts to change the password for the account authenticated for the current session, prompting for the new password.

The options dictionary supports the following:

account

A string containing the fully qualified name of the account to modify. If omitted, the account authenticated for the current session is used.

random

Boolean. If true, the utility generates a random password and returns it as a string. If random is omitted or false, the function returns an empty string.

This option annot be used with newPassword.

dual

Boolean. If true, the utility retains the current password as the account secondary password when it assigns the new primary password.

If the account already has a secondary password, setting dual to true causes an error. The error instructs you to discard the existing secondary password before retaining another password. If dual is omitted or false and the account already has a secondary password, the utility displays a warning explaining how to discard it.

discardOld

Boolean. If true, the utility discards the account secondary password. If the account does not have a secondary password, the utility displays a note and succeeds.

newPassword

A string containing the new password. If specified, the utility does not prompt for the new password or its confirmation.

The following example shows util.changePassword() changing the password for the current account, which uses the mysql_native_password plugin:

> util.changePassword()
Changing password for currentuser@localhost.
Warning: currentuser@localhost is using mysql_native_password authentication plugin, 
which was deprecated because of its weak security. Please use the "util.changeAuthMethod" 
function to upgrade it to the more secure caching_sha2_password. 
Enter new password: yyy
Confirm new password: yyy
Info: password has been successfully updated.

The following account changes the password of a named account:

>util.changePassword({"account": "app@%"})
Changing password for app@%.
Enter new password:
Confirm new password:
Info: Password has been successfully updated.

The following examples shows how to establish a new primary password while retaining the current password as the secondary password:

>util.changePassword({"account": "app@%", "dual": true})
Enter new password:
Confirm new password:
Info: Password changed successfully. The current password remains
valid as the secondary password.

Upgrade Authentication Utility

Use util.upgradeAuthMethod() to migrate an account's authentication method from mysql_native_password to caching_sha2_password.

upgradeAuthMethod() utility has the following signature:

        util.upgradeAuthMethod(Dictionary options)

account

A string containing the fully qualified name of the account to modify. If omitted, the account authenticated for the current session is used.

password

A string containing the current password when the operation requires it. If specified, the utility does not prompt for the current password.

The following example shows the upgrade of the current account, which uses the mysql_native_password authentication plugin:

>util.upgradeAuthMethod()
Switching authentication plugin from mysql_native_password to
caching_sha2_password for account currentuser@localhost.
Enter current password:
Info: Authentication method has been successfully updated.

The following example shows the upgrade of a named account, which uses the mysql_native_password authentication plugin:

>util.upgradeAuthMethod({"account": "app@%"})
Switching authentication plugin from mysql_native_password to
caching_sha2_password for account app@%.
Enter new password:
Confirm new password:
Info: Authentication method has been successfully updated.