Skip to content

Reset Password#

The mkectl reset-password command resets the password of a local user directly in the cluster. Because it works through the Kubernetes API rather than through a login session, it is the supported method for regaining access in the event that the main admin password is lost and the MKE 4 Dashboard cannot be accessed.

Info

As the mkectl reset-password command requires only a cluster-admin kubeconfig, the mke4.yaml configuration file is not required.

Important

You can only use the mkectl reset-password command to reset the passwords of existing local users. You cannot use it to create users, and it you cannot apply it for users who access the MKE 4 cluster through an external identity provider, such as LDAP, OIDC, or SAML.

Prerequisites#

A kubeconfig with cluster-admin privileges for the target cluster. Pass it with the --kubeconfig flag, or place it at the default location.

Local users are enabled on the cluster. The command fails if spec.authentication.localUsers is set to false in thme mke4.yaml configuration file. For more information, refer to Basic authentication: Disable local users.

The user whose password you want to reset exists as a local user. Local users that were migrated from MKE 3 are included.

Password requirements#

Any password that you supply must be between 8 and 64 characters and contain no white spaces.

Methods for resetting a password#

You can use any of the following three methods to reset an MKE 4 password:

  • Generate a new password
  • Enter a new password at a hidden prompt
  • Pipe in a new password from stdin

Note

It is necessary to confirm the request before a change is made, though you can use the --force to bypass the confirmation prompt. The --password-stdin flag never prompts, and thus it remains usable in automation.

Generate a new password#

Run the mkectl reset-password command with only the --user flag to generate a new random password through MKE 4:

mkectl reset-password --user admin

Example output:

? This will reset the password for user "admin" and revoke their active sessions. Continue? Yes
!!! Make sure to save the credentials shown below !!!
They are only showed once
You won't be able to see them again
Generated username:password
admin:Ke9muvSwb9RTqHlJU2IwDvYjd3rwVYut
Revoked 0 session object(s) of user "admin"

Important

The generated password displays one time only, and it is not stored anywhere on the cluster. As such, you must save it before you close the terminal.

Enter a new password at a hidden prompt#

Run the mkectl reset-password command with the --interactive flag to condfigure a new password at a hidden prompt. Note that this method requires you to enter the password twice:

mkectl reset-password --user alice --interactive

Example output:

? This will reset the password for user "alice" and revoke their active sessions. Continue? Yes
? New password: ************
? Confirm new password: ************
Password for user "alice" has been reset
Revoked 0 session object(s) of user "alice"

Pipe in a new password from stdin#

The recommended method for resetting an MKE 4 password is to run the mkectl reset-password command with the --password-stdin flag to read the new password from stdin, as this neither prompts nor echoes the password:

echo "$NEW_PASS" | mkectl reset-password --user admin --password-stdin

Example output:

Password for user "admin" has been reset
Revoked 0 session object(s) of user "admin"

Session following a password reset#

By default, the command deletes the refresh tokens and offline sessions of the user, and it reports the number of session objects that are removed. As a result, existing sessions cannot renew and thus the user must sign in again with the new password.

ID tokens that have already been issued, however, remain valid until they expire, as set by spec.authentication.expiry.idTokens in the mke4.yaml configuration file. By default, the expiration is set to 1h. Thus, an MKE 4 Dashboard tab that is already open can continue to work for up to the set length of time following the reset, but it cannot renew its session. For more information, refer to Authentication: Set Expiration.

Important

To leave the refresh tokens and offline sessions of the user in place, run the mkectl reset-password command with the --skip-session-revocation flag:

mkectl reset-password --user admin --skip-session-revocation

Mirantis, however, recommends against the use of the --skip-session-revocation flag, as any session that holds a valid refresh token can continue to renew following the reset, including a session that is held by an unauthorized party.

Audit record#

Each successful reset records a PasswordReset Kubernetes Event in the mke namespace, against the Dex Password object of the user:

kubectl --namespace mke get events --field-selector reason=PasswordReset

Kubernetes Events are short-lived, as they are removed once the retention period of the cluster elapses. For a durable record of password resets, enable Kubernetes API server audit logging, as described in Audit logging.