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-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvariables.tf
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-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-iconREADME.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvariables.tf
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-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 roles for cross-account access

This module can be used to allow IAM users from other AWS accounts to access your AWS accounts (i.e. cross-account access). This allows you to define each environment (mgmt, stage, prod, etc) in a separate AWS account, your IAM users in a single account, and to allow those users to easily switch between accounts with a single set of credentials.

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

How do you use this module?

To set up cross-account access, you need to:

  1. Create IAM roles in one account
  2. Create permissions to assume the IAM roles in other accounts

Create IAM roles in one account

If you want to allow users in AWS account A to access AWS account B, use this module in AWS account B to create IAM roles that specify which services those users may access. Check out the cross-account-iam-roles example for a working sample code of how to use this module.

Create permissions to assume the IAM roles in other accounts

Now that you have created IAM roles in account B, you need to give users in account A permission to use that role. The iam-groups module can automatically create IAM groups that grant these permissions.

In account A, do the following:

  1. Take the ARNs of the IAM roles you created in account B and plug them into the var.iam_groups_for_cross_account_access input variable of the iam-groups module in account A:

    module "iam_groups" {
      source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/iam-groups?ref=v1.0.8"
    
      iam_groups_for_cross_account_access = [
        {
          group_name = "account-b-read-only-access"
          iam_role_arns = ["arn:aws:iam::1234567901234:role/allow-read-only-access-from-other-accounts"]
        }
      ]
    
      # ... (other params omitted) ...
    }
    
  2. Run terraform apply on the iam-groups module.

  3. Add users from account A to the corresponding groups that get created (e.g. account-b-read-only-access).

  4. Users in account A can now "switch" to the roles in account B as described in How to switch between accounts.

Resources Created

This module creates the following IAM roles (all optional):

IAM Roles intended for human users

These IAM Roles are intended to be assumed by human users (i.e., IAM Users in another AWS account). The default maximum session expiration for these roles is 12 hours (configurable via the var.max_session_duration_human_users). Note that these are the maximum session expirations; the actual value for session expiration is specified when making API calls to assume the IAM role (see aws-auth).

  • allow-read-only-access-from-other-accounts: Users from the accounts in var.allow_read_only_access_from_other_account_arns will get read-only access to all services in this account.

  • allow-billing-access-from-other-accounts: Users from the accounts in var.allow_billing_access_from_other_account_arns will get full (read and write) access to the billing details for this account.

  • allow-support-access-from-other-accounts: Users from the accounts in var.allow_support_access_from_other_account_arns will get access to AWS support for this account.

  • allow-logs-access-from-other-accounts: Users from the accounts in var.allow_logs_access_from_other_account_arns will get read access to the logs in CloudTrail, AWS Config, and CloudWatch in this account. Since CloudTrail logs may be encrypted with a KMS CMK, if var.cloudtrail_kms_key_arn is set, these users will also get permissions to decrypt using this KMS CMK.

  • allow-dev-access-from-other-accounts: Users from the accounts in var.allow_dev_access_from_other_account_arns will get full (read and write) access to the services in this account specified in var.dev_permitted_services.

  • allow-full-access-from-other-accounts: Users from the accounts in var.allow_full_access_from_other_account_arns will get full (read and write) access to all services in this account.

  • allow-iam-admin-access-from-other-accounts: Users from the accounts in var.allow_iam_admin_access_from_other_account_arns will get IAM admin access.

IAM Roles intended for machine users

These IAM Roles are intended to be assumed by machine users (i.e., an EC2 Instance in another AWS account). The default maximum session expiration for these roles is 1 hour (configurable via the var.max_session_duration_machine_users). Note that these are the maximum session expirations; the actual value for session expiration is specified when making API calls to assume the IAM role (see aws-auth).

  • allow-ssh-grunt-access-from-other-accounts: Users (or more likely, EC2 Instances) from the accounts in var.allow_ssh_grunt_access_from_other_account_arns will get read access to IAM Groups and public SSH keys. This is useful to allow ssh-grunt running on EC2 Instances in other AWS accounts to validate SSH connections against IAM users defined in this AWS account.

  • allow-auto-deploy-access-from-other-accounts: Users from the accounts in var.allow_auto_deploy_from_other_account_arns will get automated deployment access to all services in this account with the permissions specified in var.auto_deploy_permissions. The main use case is to allow a CI server (e.g. Jenkins) in another AWS account to do automated deployments in this AWS account.

How to switch between accounts

Switching in the AWS console

Check out the AWS Switching to a Role (AWS Console) documentation.

Note that this module automatically outputs the convenient sign-in URLs to quickly switch to a given role. The outputs are named allow_XXX_access_sign_in_url, where XXX is one of read-only, billing, dev, or full.

Switching with CLI tools (including Terraform)

Check out the AWS Switching to a Role (AWS Command Line Interface) documentation. Note that assuming roles with the AWS CLI takes quite a few steps, so use the aws-auth script to reduce it to a one-liner.

Background Information

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

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?