SSH Grunt
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 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-gruntfolder contains sample code optimized for learning, experimenting, and testing (but not production usage).
Production deployment
If you want to deploy this module in production, check out the following resources:
-
IAM policy with permissions for ssh-grunt: Production-ready sample code for IAM entites that can be used for managing SSH grunt access.
-
IAM cross account roles in an app account: Production-ready sample code for cross account IAM roles, from the Reference Architecture.
-
IAM cross account roles as defined in a service module: Service module code for IAM roles that can be used for a production-ready app account, as in the production example above.