Resetting passwords on managed instances - AWS Systems Manager

Resetting passwords on managed instances

You can reset the password for any user on a managed instance. This includes Amazon Elastic Compute Cloud (Amazon EC2) instances, on-premises servers, and virtual machines (VMs) that are managed by AWS Systems Manager. The password reset functionality is built on Session Manager, a capability of AWS Systems Manager. You can use this functionality to connect to instances without opening inbound ports, maintaining bastion hosts, or managing SSH keys.

This makes the password reset option useful when a user has forgotten a password, or when you want to quickly update a password without making an RDP or SSH connection to the instance.

Prerequisites

Before you can reset the password on an instance, the following requirements must be met:

  • The instance you want to change a password on must be a Systems Manager managed instance. This means that the SSM Agent is installed on the instance. (SSM Agent Version 2.3.668.0 or later is required for changing passwords.) For information about installing or updating SSM Agent, see Working with SSM Agent.

  • The password reset functionality uses the Session Manager configuration that is set up for your account to connect to the instance. Therefore, the prerequisites for using Session Manager must have been completed for your account in the current AWS Region. For more information, see Setting up Session Manager.

    Note

    Session Manager support for on-premises servers is provided for the advanced-instances tier only. For information, see Turning on the advanced-instances tier.

  • The AWS user who is changing the password must have the ssm:SendCommand permission for the instance. For information, see Restricting Run Command access based on instance tags.

Restricting access

You can limit a user's ability to reset passwords to specific instances. This is done by using identity-based policies for the Session Manager ssm:StartSession operation with the AWS-PasswordReset SSM document. For more information, see Control user session access to instances.

Encrypting data

Turn on AWS Key Management Service (AWS KMS) complete encryption for Session Manager data to use the password reset option for managed instances. For more information, see Turn on KMS key encryption of session data (console).

Reset a password on a managed instance

You can reset a password on a Systems Manager managed instance using the Systems Manager Fleet Manager console or the AWS Command Line Interface (AWS CLI).

To change the password on a managed instance (console)

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Fleet Manager.

    -or-

    If the AWS Systems Manager home page opens first, choose the menu icon ( ) to open the navigation pane, and then choose Fleet Manager in the navigation pane.

  3. Choose the button next to the instance that needs a new password.

  4. In the Instance actions menu, choose Reset password.

  5. For User name, enter the name of the user for which you're changing the password. This can be any user name that has an account on the instance.

  6. Choose Submit.

  7. Follow the prompts in the Enter new password command window to specify the new password.

    Note

    If the version of SSM Agent on the instance doesn't support password resets, you're prompted to install a supported version using Run Command, a capability of AWS Systems Manager.

To reset the password on a managed instance (AWS CLI)

  1. To reset the password for a user on a managed instance, run the following command.

    Note

    To use the AWS CLI to reset a password, the Session Manager plugin must be installed on your local machine. For information, see (Optional) Install the Session Manager plugin for the AWS CLI.

    Linux & macOS
    aws ssm start-session \ --target instance-id \ --document-name "AWS-PasswordReset" \ --parameters '{"username": ["user-name"]}'
    Windows
    aws ssm start-session ^ --target instance-id ^ --document-name "AWS-PasswordReset" ^ --parameters username="user-name"

    instance-id represents the ID of an instance configured for use with Systems Manager and its Session Manager capability.

    user-name represents the name of the user you want to reset password for on the instance.

  2. Follow the prompts in the Enter new password command window to specify the new password.

Troubleshoot password resets on managed instances

Many password reset issues can be resolved by ensuring that you have completed the password reset prerequisites. For other problems, use the following information to help you troubleshoot password reset issues.

Instance not available

Problem: You want to reset the password for an EC2 instance on the Managed instances console page, but the instance isn't in the list.

  • Solution: The instance you want to connect to might not be configured to use with the Systems Manager service. To use an EC2 instance with Systems Manager, an AWS Identity and Access Management (IAM) instance profile that gives Systems Manager permission to perform actions on your instances must be attached to the instance. For information, see Create an IAM instance profile for Systems Manager. To use an on-premises server or virtual machine (VM) that you have activated for use with Systems Manager, create an IAM service role that gives Systems Manager permission to perform actions on your machines. For information, see Create an IAM service role for a hybrid environment. (Session Manager support for on-premises servers and VMs is provided for the advanced-instances tier only. For information, see Turning on the advanced-instances tier.)

SSM Agent not up-to-date (console)

Problem: A message reports that the version of SSM Agent doesn't support password reset functionality.

  • Solution: Version 2.3.668.0 or later of SSM Agent is required to perform password resets. In the console, you can begin the process of updating the agent on the instance by choosing Update SSM Agent.

    An updated version of SSM Agent is released whenever new capabilities are added to Systems Manager or updates are made to existing capabilities. If an older version of the agent is running on an instance, some SSM Agent processes can fail. For that reason, we recommend that you automate the process of keeping SSM Agent up-to-date on your instances. For information, see Automating updates to SSM Agent. Subscribe to the SSM Agent Release Notes page on GitHub to get notifications about SSM Agent updates.

Password reset options aren't provided (AWS CLI)

Problem: You connect successfully to an instance using the AWS CLI start-session command. You specified the SSM Document AWS-PasswordReset and provided a valid user name, but prompts to change the password aren't displayed.

  • Solution: The version of SSM Agent on the instance isn't up-to-date. Version 2.3.668.0 or later is required to perform password resets.

    An updated version of SSM Agent is released whenever new capabilities are added to Systems Manager or updates are made to existing capabilities. If an older version of the agent is running on an instance, some SSM Agent processes can fail. For that reason, we recommend that you automate the process of keeping SSM Agent up-to-date on your instances. For information, see Automating updates to SSM Agent. Subscribe to the SSM Agent Release Notes page on GitHub to get notifications about SSM Agent updates.

No authorization to run ssm:SendCommand

Problem: You attempt to connect to an instance to change its password but receive an error message saying that you aren't authorized to run ssm:SendCommand on the instance.

Session Manager error message

Problem: You receive an error message related to Session Manager.