Skip to main content
Security Modules 0.71.0Last updated in version 0.69.1

SSH Grunt

View SourceRelease Notes

This module can configure a Linux server to manage SSH access to the server via an Identity Provider (IdP). Via AWS Identity and Access Management (IAM), developers in certain IAM Groups will be able to SSH to your servers using their IAM user name and the SSH key they uploaded to their IAM user account.

ssh-grunt architecturessh-grunt architecture


  • Automatically sync user accounts from your identity provider (e.g., IAM, Google, ADFS) to your servers, so each developer can have their own user name (e.g. "susan", "jim") rather than everyone using a shared user (e.g. "ubuntu", "ec2-user").

  • Each developer uses their own SSH keys to connect to servers (instead of a single, shared Key Pair).

  • Quickly use IAM to rotate old keys and upload a new one

  • Revoke SSH access to servers from the centralized IdP

Conflicts with ec2-instance-connect

AWS has a similar service in EC2 Instance Connect. There are pros and cons to each service. For example, with ssh-grunt, there is no additional client-side tooling required beyond the native SSH that you have already. Connection is a one step process of SSHing to your target instance. With EC2 Instance Connect, in order to use native SSH, you must first use the AWS CLI to push your key up to AWS.

EC2 Instance Connect is installed by default in recent AWS AMIs, including Ubuntu 20.04. It conflicts with ssh-grunt due to both services relying on SSH’s AuthorizedKeysCommand. In order to make ssh-grunt work properly, you’ll need to uninstall the ec2-instance-connect package.

On installation, ssh-grunt will detect if ec2-instance-connect is installed and halt.



This repo is a part of the Gruntwork Infrastructure as Code Library, a collection of reusable, battle-tested, production ready infrastructure code. If you’ve never used the Infrastructure as Code Library before, make sure to read How to use the Gruntwork Infrastructure as Code Library!

Core concepts

Repo organization

  • modules: the main implementation code for this repo, broken down into multiple standalone, orthogonal submodules.

  • examples: This folder contains working examples of how to use the submodules.

  • test: Automated tests for the modules and examples.


Non-production deployment (quick start for learning)

If you just want to try this repo out for experimenting and learning, check out the following resources:

Production deployment

If you want to deploy this module in production, check out the following resources:


Day-to-day operations