Skip to main content
Security Modules 0.74.5Last updated in version 0.74.2

SSH Grunt

View Source Release 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

Features​

  • 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.

Learn​

Note

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.

Deploy​

Compatibility​

This module is known to work on CentOS 7, Ubuntu, Amazon Linux 2, and Amazon Linux 2023

Amazon Linux 1 Compatibility: Amazon Linux 1 reached EOL on December 31, 2023 and is therefore no longer supported in this module.

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:

  • ssh-grunt examples: The examples/ssh-grunt folder contains sample code optimized for learning, experimenting, and testing (but not production usage).

  • Packer template

Production deployment​

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

Manage​

Day-to-day operations​