Skip to main content
Security Modules 0.72.0Last updated in version 0.69.2

Custom IAM Entity

View SourceRelease Notes

This Gruntwork Terraform Module creates an IAM group and/or role and attaches a provided set of IAM managed policies to the group. This can be used in conjunction with the iam-groups, cross-account-iam-roles, and saml-iam-roles modules which create a set of groups and roles with smart defaults. Use this module to easily create IAM groups and roles with a defined set of permissions.

Requirements​

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

Instructions​

Check out the custom-iam-entity example for a working example.

Resources Created​

  • IAM group - (optional) an IAM group with the provided name and attaches each of the requested policies.
  • IAM role - (optional) an IAM role with the provided name and attaches each of the requested policies.

If neither role nor group are provided, this module does nothing.

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 policies - This module only attaches policies by ARN or by name. It does not create any new policies.

MFA support​

This module includes the should_require_mfa variable which controls whether MFA should be required for the created IAM group and/or role. The implementation of how MFA is enforced differs between IAM groups and IAM roles.

  • For IAM groups, we attach the require_mfa_policy from the iam-policies module. This policy denies access to all AWS APIs unless MFA is being used, except those allowing a member of the group to manage their own MFA devices.
  • For IAM roles, we use the aws:MultiFactorAuthPresent condition key on the role's trust policy, ensuring that MFA is present when assuming the role.

The reason for this difference is difficult to explain, but boils down to limitations imposed by role chaining in combination with the presence of the aws:MultiFactorAuthPresent condition key under various authentication scenarios. For more information, refer to the AWS docs on Configuring MFA-protected API access.

Background Information​

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

Sample Usage​

main.tf

# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S CUSTOM-IAM-ENTITY MODULE
# ------------------------------------------------------------------------------------------------------

module "custom_iam_entity" {

  source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/custom-iam-entity?ref=v0.72.0"

  # ----------------------------------------------------------------------------------------------------
  # REQUIRED VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # Should we require that all IAM Users use Multi-Factor Authentication for
  # both AWS API calls and the AWS Web Console? (true or false)
  should_require_mfa = <bool>

  # ----------------------------------------------------------------------------------------------------
  # OPTIONAL VARIABLES
  # ----------------------------------------------------------------------------------------------------

  # A list of IAM ARNs (users, groups, or roles) that can assume this role.
  # Required if should_create_iam_role is true.
  assume_role_arns = []

  # Map of custom conditions to apply to the assume role policy for the custom
  # IAM role. The input is a map of objects where the map keys are arbitrary
  # unique IDs and the values are objects that define the condition blocks.
  # Refer to
  # https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#condition
  # for more information on the supported condition fields.
  assume_role_custom_conditions = {}

  # Custom IAM policy JSON for the IAM Role to control assume role settings.
  # Note that when an assume role policy is passed in this manner,
  # var.should_require_mfa is ignored.
  assume_role_iam_policy_json = null

  # The name to use for the custom inline IAM policy that is attached to the
  # Role/Group when var.iam_policy is configured.
  custom_iam_policy_name = "GrantCustomIAMPolicy"

  # A list of IAM AWS Managed Policy names to attach to the group.
  iam_aws_managed_policy_names = null

  # A list of IAM AWS Customer Managed policy names to attach to the group.
  iam_customer_managed_policy_names = null

  # A list of IAM roles that this members of this group can assume.
  iam_group_assume_role_arns = null

  # The name of an IAM Group to create. Required when
  # var.should_create_iam_group is true.
  iam_group_name = null

  # A list of policies (by ARN) to attach to this group.
  iam_policy_arns = null

  # JSON formatted IAM policy that should be attached directly to the IAM
  # role/group.
  iam_policy_json = ""

  # The name to use for the IAM policy that is attached to the Role/Group when
  # var.iam_policy_json is configured.
  iam_policy_json_name = "CustomIAMPolicyFromJSON"

  # The name of an IAM role to create. Required when var.should_create_iam_role
  # is true.
  iam_role_name = null

  # The ARN of the policy that is used to set the permissions boundary for the
  # IAM role
  iam_role_permissions_boundary = null

  # The maximum allowable session duration, in seconds, for the credentials you
  # get when assuming the IAM roles created by this module.
  max_session_duration = 43200

  # A list of AWS services for which the IAM role will receive full permissions.
  # See
  # https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html
  # to find the service name. For example, to grant developers access only to
  # EC2 and Amazon Machine Learning, use the value ["ec2","machinelearning"].
  permitted_full_access_services = []

  # Should we create an IAM group with the attached policies? (default false)
  should_create_iam_group = false

  # Should we create an IAM role with the attached policies? (default false)
  should_create_iam_role = false

}


Reference​

Required​

should_require_mfaboolrequired

Should we require that all IAM Users use Multi-Factor Authentication for both AWS API calls and the AWS Web Console? (true or false)

Optional​

assume_role_arnslist(string)optional

A list of IAM ARNs (users, groups, or roles) that can assume this role. Required if should_create_iam_role is true.

[]
assume_role_custom_conditionsmap(object(…))optional

Map of custom conditions to apply to the assume role policy for the custom IAM role. The input is a map of objects where the map keys are arbitrary unique IDs and the values are objects that define the condition blocks. Refer to https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#condition for more information on the supported condition fields.

map(object({
    test     = string
    values   = list(string)
    variable = string
  }))
{}

Custom IAM policy JSON for the IAM Role to control assume role settings. Note that when an assume role policy is passed in this manner, should_require_mfa is ignored.

null

The name to use for the custom inline IAM policy that is attached to the Role/Group when iam_policy is configured.

"GrantCustomIAMPolicy"
iam_aws_managed_policy_nameslist(string)optional

A list of IAM AWS Managed Policy names to attach to the group.

null

A list of IAM AWS Customer Managed policy names to attach to the group.

null
iam_group_assume_role_arnslist(string)optional

A list of IAM roles that this members of this group can assume.

null
iam_group_namestringoptional

The name of an IAM Group to create. Required when should_create_iam_group is true.

null
iam_policy_arnslist(string)optional

A list of policies (by ARN) to attach to this group.

null
iam_policy_jsonstringoptional

JSON formatted IAM policy that should be attached directly to the IAM role/group.

""
iam_policy_json_namestringoptional

The name to use for the IAM policy that is attached to the Role/Group when iam_policy_json is configured.

"CustomIAMPolicyFromJSON"
iam_role_namestringoptional

The name of an IAM role to create. Required when should_create_iam_role is true.

null

The ARN of the policy that is used to set the permissions boundary for the IAM role

null
max_session_durationnumberoptional

The maximum allowable session duration, in seconds, for the credentials you get when assuming the IAM roles created by this module.

43200
permitted_full_access_serviceslist(string)optional

A list of AWS services for which the IAM role will receive full permissions. See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html to find the service name. For example, to grant developers access only to EC2 and Amazon Machine Learning, use the value ['ec2','machinelearning'].

[]

Should we create an IAM group with the attached policies? (default false)

false

Should we create an IAM role with the attached policies? (default false)

false