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-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-icon_docs
file-type-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvariables.tf
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-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-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-icon_docs
file-type-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvariables.tf
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-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.md

down

A Best-Practices Set of IAM Groups

This Gruntwork Terraform Module sets up a set of IAM Groups that will make sense for most organizations and attaches to them a set of IAM Policies (permissions) that make it easier to manage different permissions levels in your AWS account.

If you're not familiar with IAM concepts, start with the Background Information section as a way to familiarize yourself with the terminology.

Motivation

In Summer 2014, a company called CodeSpaces that offered "rock solid, secure, and affordable git hosting and project management" was forced to shut down after a single rogue employee entered its AWS account and wiped out everything (See ArsTechnica Article). The goal of this module is to carefully manage access to your AWS account to reduce the chances of rogue employees or external attackers being able to do too much damage.

How do you use this module?

Requirements

  • You will need to be authenticated to AWS with an account that has iam:* permissions.

Instructions

Check out the iam-groups example for a working example.

Resources Created

IAM Groups

This module optionally creates the following IAM Groups:

  • full-access: IAM Users in this group have full access to all resources in the AWS account.
  • billing: IAM Users in this group can read and write billing settings, but nothing else.
  • logs: IAM Users in this group can read logs in CloudTrail, AWS Config, and CloudWatch.
  • developers: IAM Users in this group have whatever permissions are declared in var.iam_group_developers_permitted_services. In addition, these IAM Users have rights to a personal S3 bucket named <var.iam_group_developers_permitted_services><iam-user-name>.
  • read-only: IAM Users in this group can read all resources in the AWS account but have no write privileges.
  • support: IAM Users in this group can interact with AWS Support.
  • iam-user-self-mgmt: IAM Group with the iam-user-self-mgmt IAM Policy attached. IAM Users in this group have enough permissions to manage their own account (setup MFA, change passwords, etc), but not other IAM Users.
  • iam-admin: IAM Group with the iam-admin IAM Policy attached. IAM Users in this group have full IAM permissions to administer users, groups, roles, and policies. This is effectively the same as administrative access since users can grant arbitrary permissions!
  • use-existing-iam-roles: IAM Users in this group can pass existing IAM Roles to AWS resources to which they have been granted access. These IAM Users cannot create new IAM Roles, only use existing ones. See the three levels of IAM permissions for more information.
  • ssh-grunt-sudo-users: IAM Users in this group have SSH access with sudo privileges to any EC2 Instance configured to use this group to manage SSH logins.
  • ssh-grunt-users: IAM Users in this group have SSH access without sudo privileges to any EC2 Instance configured to use this group to manage SSH logins.
  • cross-account-access: IAM users in these groups can assume an IAM role in another AWS account. This makes cross-account access, easy, where you can have all your users defined in one AWS account (e.g. users) and to grant those users access to certain IAM roles in other AWS accounts (e.g. stage, prod). The IAM groups that are created and which IAM roles they have access to is controlled by the variable var.iam_groups_for_cross_account_access.

These represent a standard set of IAM Groups, but your organization may need additional groups. You're welcome to add additional IAM Groups outside this module to suit your organization's needs. Is the IAM Group you need a Group most teams would need? Let us know at support@gruntwork.io and maybe we'll consider adding it to the module itself.

IAM Policies

This module creates the following IAM Policies:

  • iam-user-self-mgmt: This IAM Policy grants permission to an IAM User to manage her own IAM User account. This includes resetting the IAM User password, and generating AWS account credentials. It also grants permission to list other IAM Users, but not to view any information about them.

This IAM Policy should be attached to any IAM Group that does not already grant all IAM permissions. For example, if an IAM User does not have the ability to pass an IAM Role to an EC2 Instance, that IAM User will be unable to manage his own account unless this IAM Policy is attached to his account.

Resources NOT Created

IAM Users

This module does not create any IAM Users, nor assign any existing IAM Users to IAM Groups. You can use the iam-users module to create users.

IAM Roles

This module does not create any IAM Roles. Those should be created with Terraform, but in separate templates in the context of your specific needs, not as a generic set of roles.

Additional Guidelines

Enable Your Billing IAM Group

By default, only the root AWS account has access to billing information. To enable the billing IAM Group above or otherwise enable IAM Users to access the billing console:

  1. Select "My Account" from the top right of the AWS Web Console.

    Screenshot

  2. You'll be taken to the "Dashboard" page. Now scroll down until you see the below heading and check the box:

    Screnshot

Background Information

For background information on IAM, IAM users, IAM policies, and more, check out the background information docs in the iam-policies module.

TODO

Are we missing any functionality? Let us know by emailing info@gruntwork.io!

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?