Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon.patcher
file-type-icon_ci
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconaws-config-bucket
file-type-iconaws-config-multi-region
file-type-iconaws-config-rules
file-type-iconaws-config
file-type-iconaws-organizations
file-type-iconcloudtrail-bucket
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconebs-encryption-multi-region
file-type-iconebs-encryption
file-type-iconfail2ban
file-type-icongithub-actions-iam-role
file-type-icongithub-actions-openid-connect-provider
file-type-iconguardduty-bucket
file-type-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-cmk-replica
file-type-iconkms-grant-multi-region
file-type-iconkms-master-key-multi-region
file-type-iconkms-master-key
file-type-iconntp
file-type-iconos-hardening
file-type-iconprivate-s3-bucket
file-type-iconsaml-iam-roles
file-type-iconsecrets-manager-resource-policies
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-icon_ci
file-type-icon_docs
file-type-iconscripts
file-type-iconsrc
file-type-icon.dockerignore
file-type-iconDockerfile
file-type-iconREADME.adoc
file-type-iconcore-concepts.md
file-type-icondocker-compose.yml
file-type-icongo.mod
file-type-icongo.sum
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconterraform-cloud-enterprise-private-module-...

Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon.patcher
file-type-icon_ci
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconaws-config-bucket
file-type-iconaws-config-multi-region
file-type-iconaws-config-rules
file-type-iconaws-config
file-type-iconaws-organizations
file-type-iconcloudtrail-bucket
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconebs-encryption-multi-region
file-type-iconebs-encryption
file-type-iconfail2ban
file-type-icongithub-actions-iam-role
file-type-icongithub-actions-openid-connect-provider
file-type-iconguardduty-bucket
file-type-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-cmk-replica
file-type-iconkms-grant-multi-region
file-type-iconkms-master-key-multi-region
file-type-iconkms-master-key
file-type-iconntp
file-type-iconos-hardening
file-type-iconprivate-s3-bucket
file-type-iconsaml-iam-roles
file-type-iconsecrets-manager-resource-policies
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-icon_ci
file-type-icon_docs
file-type-iconscripts
file-type-iconsrc
file-type-icon.dockerignore
file-type-iconDockerfile
file-type-iconREADME.adoc
file-type-iconcore-concepts.md
file-type-icondocker-compose.yml
file-type-icongo.mod
file-type-icongo.sum
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconterraform-cloud-enterprise-private-module-...
ssh-grunt

ssh-grunt

Manage SSH access to EC2 Instances using groups in AWS IAM or your Identity Provider (e.g., ADFS, Google, Okta, etc).

Code Preview

Preview the Code

mobile file icon

README.adoc

down

maintained%20by gruntwork.io %235849a6

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!

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:

Support

If you need help with this repo or anything else related to infrastructure or DevOps, Gruntwork offers Commercial Support via Slack, email, and phone/video. If you’re already a Gruntwork customer, hop on Slack and ask away! If not, subscribe now. If you’re not sure, feel free to email us at support@gruntwork.io.

Contributions

Contributions to this repo are very welcome and appreciated! If you find a bug or want to add a new feature or even contribute an entirely new module, we are very happy to accept pull requests, provide feedback, and run your changes through our automated test suite.

License

Please see LICENSE.txt for details on how the code in this repo is licensed.

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?