A best-practices set of IAM roles for SAML access
This module can be used to allow users authenticated via external Security Assertion Markup Language (SAML) identity providers such as Google, Amazon SSO, Microsoft Active Directory Federation Services (ADFS), Okta, and OneLogin to access your AWS accounts (saml-access). This allows you to define each environment (mgmt, stage, prod, etc) in a separate AWS account and to use SAML to assume different roles in each account.
If you're not familiar with IAM concepts, start with the Background Information section as a way to familiarize yourself with the terminology.
Resources Created
This module creates the following IAM roles (all optional):
-
allow-read-only-access-from-saml: Users authenticated by the SAML providers in
var.allow_read_only_access_from_saml_provider_arns
will get read-only access to all services in this account. -
allow-billing-access-from-saml: Users authenticated by the SAML providers in
var.allow_billing_access_from_saml_provider_arns
will get full (read and write) access to the billing details for this account. -
allow-support-access-from-saml: Users authenticated by the SAML providers in
var.allow_support_access_from_saml_provider_arns
will get access to AWS support for this account. -
allow-logs-access-from-saml: Users authenticated by the SAML providers in
var.allow_logs_access_from_saml_provider_arns
will get read access to the logs in CloudTrail, AWS Config, and CloudWatch for this account. Since CloudTrail logs may be encrypted with a KMS CMK, ifvar.cloudtrail_kms_key_arn
is set, these users will also get permissions to decrypt using this KMS CMK. -
allow-ssh-grunt-access-from-saml: Users authenticated by the SAML providers in
var.allow_ssh_grunt_access_from_saml_provider_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-dev-access-from-saml:Users authenticated by the SAML providers in
var.allow_dev_access_from_saml_provider_arns
will get full (read and write) access to the services in this account specified invar.dev_permitted_services
. -
allow-full-access-from-saml: Users authenticated by the SAML providers in
var.allow_full_access_from_saml_provider_arns
will get full (read and write) access to all services in this account. -
allow-iam-admin-access-from-saml: Users authenticated by the SAML providers in
var.allow_iam_admin_access_from_saml_provider_arns
will get full IAM (iam:*
) access in this account. -
allow-auto-deploy-access-from-saml: Users authenticated by the SAML providers in
var.allow_read_only_access_from_saml_provider_arns
will get automated deployment access to all services in this account with the permissions specified invar.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.
Sample Usage
- Terraform
- Terragrunt
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S SAML-IAM-ROLES MODULE
# ------------------------------------------------------------------------------------------------------
module "saml_iam_roles" {
source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/saml-iam-roles?ref=v0.74.4"
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# The ID of the AWS Account.
aws_account_id = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# A flag to indicate if auto deploy access will be delegated to SAML
# providers.
allow_auto_deploy_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated the auto
# deploy IAM role that has the permissions in var.auto_deploy_permissions.
allow_auto_deploy_from_saml_provider_arns = []
# A flag to indicate if billing access will be delegated to SAML providers.
allow_billing_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to the billing info for this account.
allow_billing_access_from_saml_provider_arns = []
# A flag to indicate if dev access will be delegated to SAML providers.
allow_dev_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to the services in this account specified in
# var.dev_permitted_services.
allow_dev_access_from_saml_provider_arns = []
# A flag to indicate if full access will be delegated to SAML providers.
allow_full_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to this account.
allow_full_access_from_saml_provider_arns = []
# A flag to indicate if IAM admin access will be delegated to SAML providers.
allow_iam_admin_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated IAM admin
# access to this account.
allow_iam_admin_access_from_saml_provider_arns = []
# A flag to indicate if logs access will be delegated to SAML providers.
allow_logs_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read access
# to the logs in CloudTrail, AWS Config, and CloudWatch for this account. If
# var.cloudtrail_kms_key_arn is set, the users will also be delegated access
# to decrypt using this KMS CMK.
allow_logs_access_from_saml_provider_arns = []
# A flag to indicate if read only access will be delegated to SAML providers.
allow_read_only_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read-only
# access to this account.
allow_read_only_access_from_saml_provider_arns = []
# A flag to indicate if ssh-grunt access will be delegated to SAML providers.
allow_ssh_grunt_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read access
# to IAM groups and publish SSH keys. This is used for ssh-grunt.
allow_ssh_grunt_access_from_saml_provider_arns = []
# A flag to indicate if AWS support access will be delegated to SAML
# providers.
allow_support_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated AWS support
# access for this account.
allow_support_access_from_saml_provider_arns = []
# What to name the auto deploy IAM role
auto_deploy_access_iam_role_name = "allow-auto-deploy-from-saml"
# A list of IAM permissions (e.g. ec2:*) which will be granted for automated
# deployment.
auto_deploy_permissions = []
# What to name the billing access IAM role
billing_access_iam_role_name = "allow-billing-only-access-from-saml"
# The ARN of a KMS CMK used to encrypt CloudTrail logs. If set, the logs IAM
# roles will include permissions to decrypt using this CMK.
cloudtrail_kms_key_arn = null
# What to name the dev access IAM role
dev_access_iam_role_name = "allow-dev-access-from-saml"
# A list of AWS services for which the developers from the accounts in
# var.allow_dev_access_from_other_account_arns will receive full permissions.
# See https://goo.gl/ZyoHlz to find the IAM Service name. For example, to
# grant developers access only to EC2 and Amazon Machine Learning, use the
# value ["ec2","machinelearning"]. Do NOT add iam to the list of services, or
# that will grant Developers de facto admin access.
dev_permitted_services = []
# What to name the full access IAM role
full_access_iam_role_name = "allow-full-access-from-saml"
# What to name the IAM admin access IAM role
iam_admin_access_iam_role_name = "allow-iam-admin-access-from-saml"
# What to name the logs access IAM role
logs_access_iam_role_name = "allow-logs-access-from-saml"
# The maximum allowable session duration, in seconds, for the credentials you
# get when assuming the IAM roles created by this module. This variable
# applies to all IAM roles created by this module that are intended for people
# to use, such as allow-read-only-access-from-saml. For IAM roles that are
# intended for machine users, such as allow-auto-deploy-from-other-accounts,
# see var.max_session_duration_machine_users.
max_session_duration_human_users = 43200
# The maximum allowable session duration, in seconds, for the credentials you
# get when assuming the IAM roles created by this module. This variable
# applies to all IAM roles created by this module that are intended for
# machine users, such as allow-auto-deploy-from-saml. For IAM roles that are
# intended for human users, such as
# allow-read-only-access-from-other-accounts, see
# var.max_session_duration_human_users.
max_session_duration_machine_users = 3600
# What to name the read-only access IAM role
read_only_access_iam_role_name = "allow-read-only-access-from-saml"
# What to name the ssh-grunt access IAM role
ssh_grunt_access_iam_role_name = "allow-ssh-grunt-access-from-saml"
# What to name the support access IAM role
support_access_iam_role_name = "allow-support-access-from-saml"
# A map of tags to apply to the IAM roles.
tags = {}
}
# ------------------------------------------------------------------------------------------------------
# DEPLOY GRUNTWORK'S SAML-IAM-ROLES MODULE
# ------------------------------------------------------------------------------------------------------
terraform {
source = "git::git@github.com:gruntwork-io/terraform-aws-security.git//modules/saml-iam-roles?ref=v0.74.4"
}
inputs = {
# ----------------------------------------------------------------------------------------------------
# REQUIRED VARIABLES
# ----------------------------------------------------------------------------------------------------
# The ID of the AWS Account.
aws_account_id = <string>
# ----------------------------------------------------------------------------------------------------
# OPTIONAL VARIABLES
# ----------------------------------------------------------------------------------------------------
# A flag to indicate if auto deploy access will be delegated to SAML
# providers.
allow_auto_deploy_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated the auto
# deploy IAM role that has the permissions in var.auto_deploy_permissions.
allow_auto_deploy_from_saml_provider_arns = []
# A flag to indicate if billing access will be delegated to SAML providers.
allow_billing_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to the billing info for this account.
allow_billing_access_from_saml_provider_arns = []
# A flag to indicate if dev access will be delegated to SAML providers.
allow_dev_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to the services in this account specified in
# var.dev_permitted_services.
allow_dev_access_from_saml_provider_arns = []
# A flag to indicate if full access will be delegated to SAML providers.
allow_full_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated full (read
# and write) access to this account.
allow_full_access_from_saml_provider_arns = []
# A flag to indicate if IAM admin access will be delegated to SAML providers.
allow_iam_admin_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated IAM admin
# access to this account.
allow_iam_admin_access_from_saml_provider_arns = []
# A flag to indicate if logs access will be delegated to SAML providers.
allow_logs_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read access
# to the logs in CloudTrail, AWS Config, and CloudWatch for this account. If
# var.cloudtrail_kms_key_arn is set, the users will also be delegated access
# to decrypt using this KMS CMK.
allow_logs_access_from_saml_provider_arns = []
# A flag to indicate if read only access will be delegated to SAML providers.
allow_read_only_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read-only
# access to this account.
allow_read_only_access_from_saml_provider_arns = []
# A flag to indicate if ssh-grunt access will be delegated to SAML providers.
allow_ssh_grunt_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated read access
# to IAM groups and publish SSH keys. This is used for ssh-grunt.
allow_ssh_grunt_access_from_saml_provider_arns = []
# A flag to indicate if AWS support access will be delegated to SAML
# providers.
allow_support_access_from_saml_provider = false
# A list of IAM ARNs of Identity Providers that will be delegated AWS support
# access for this account.
allow_support_access_from_saml_provider_arns = []
# What to name the auto deploy IAM role
auto_deploy_access_iam_role_name = "allow-auto-deploy-from-saml"
# A list of IAM permissions (e.g. ec2:*) which will be granted for automated
# deployment.
auto_deploy_permissions = []
# What to name the billing access IAM role
billing_access_iam_role_name = "allow-billing-only-access-from-saml"
# The ARN of a KMS CMK used to encrypt CloudTrail logs. If set, the logs IAM
# roles will include permissions to decrypt using this CMK.
cloudtrail_kms_key_arn = null
# What to name the dev access IAM role
dev_access_iam_role_name = "allow-dev-access-from-saml"
# A list of AWS services for which the developers from the accounts in
# var.allow_dev_access_from_other_account_arns will receive full permissions.
# See https://goo.gl/ZyoHlz to find the IAM Service name. For example, to
# grant developers access only to EC2 and Amazon Machine Learning, use the
# value ["ec2","machinelearning"]. Do NOT add iam to the list of services, or
# that will grant Developers de facto admin access.
dev_permitted_services = []
# What to name the full access IAM role
full_access_iam_role_name = "allow-full-access-from-saml"
# What to name the IAM admin access IAM role
iam_admin_access_iam_role_name = "allow-iam-admin-access-from-saml"
# What to name the logs access IAM role
logs_access_iam_role_name = "allow-logs-access-from-saml"
# The maximum allowable session duration, in seconds, for the credentials you
# get when assuming the IAM roles created by this module. This variable
# applies to all IAM roles created by this module that are intended for people
# to use, such as allow-read-only-access-from-saml. For IAM roles that are
# intended for machine users, such as allow-auto-deploy-from-other-accounts,
# see var.max_session_duration_machine_users.
max_session_duration_human_users = 43200
# The maximum allowable session duration, in seconds, for the credentials you
# get when assuming the IAM roles created by this module. This variable
# applies to all IAM roles created by this module that are intended for
# machine users, such as allow-auto-deploy-from-saml. For IAM roles that are
# intended for human users, such as
# allow-read-only-access-from-other-accounts, see
# var.max_session_duration_human_users.
max_session_duration_machine_users = 3600
# What to name the read-only access IAM role
read_only_access_iam_role_name = "allow-read-only-access-from-saml"
# What to name the ssh-grunt access IAM role
ssh_grunt_access_iam_role_name = "allow-ssh-grunt-access-from-saml"
# What to name the support access IAM role
support_access_iam_role_name = "allow-support-access-from-saml"
# A map of tags to apply to the IAM roles.
tags = {}
}
Reference
- Inputs
- Outputs
Required
aws_account_id
stringThe ID of the AWS Account.
Optional
A flag to indicate if auto deploy access will be delegated to SAML providers.
false
allow_auto_deploy_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated the auto deploy IAM role that has the permissions in auto_deploy_permissions
.
[]
Example
default = [
"arn:aws:iam::123445678910:role/jenkins"
]
A flag to indicate if billing access will be delegated to SAML providers.
false
allow_billing_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated full (read and write) access to the billing info for this account.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if dev access will be delegated to SAML providers.
false
allow_dev_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated full (read and write) access to the services in this account specified in dev_permitted_services
.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if full access will be delegated to SAML providers.
false
allow_full_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated full (read and write) access to this account.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if IAM admin access will be delegated to SAML providers.
false
allow_iam_admin_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated IAM admin access to this account.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if logs access will be delegated to SAML providers.
false
allow_logs_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated read access to the logs in CloudTrail, AWS Config, and CloudWatch for this account. If cloudtrail_kms_key_arn
is set, the users will also be delegated access to decrypt using this KMS CMK.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if read only access will be delegated to SAML providers.
false
allow_read_only_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated read-only access to this account.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if ssh-grunt access will be delegated to SAML providers.
false
allow_ssh_grunt_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated read access to IAM groups and publish SSH keys. This is used for ssh-grunt.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
A flag to indicate if AWS support access will be delegated to SAML providers.
false
allow_support_access_from_saml_provider_arns
list(string)A list of IAM ARNs of Identity Providers that will be delegated AWS support access for this account.
[]
Example
default = [
"arn:aws:iam::123445678910:root"
]
What to name the auto deploy IAM role
"allow-auto-deploy-from-saml"
auto_deploy_permissions
list(string)A list of IAM permissions (e.g. ec2:*) which will be granted for automated deployment.
[]
What to name the billing access IAM role
"allow-billing-only-access-from-saml"
cloudtrail_kms_key_arn
stringThe ARN of a KMS CMK used to encrypt CloudTrail logs. If set, the logs IAM roles will include permissions to decrypt using this CMK.
null
dev_access_iam_role_name
stringWhat to name the dev access IAM role
"allow-dev-access-from-saml"
dev_permitted_services
list(string)A list of AWS services for which the developers from the accounts in allow_dev_access_from_other_account_arns
will receive full permissions. See https://goo.gl/ZyoHlz to find the IAM Service name. For example, to grant developers access only to EC2 and Amazon Machine Learning, use the value ['ec2','machinelearning']. Do NOT add iam to the list of services, or that will grant Developers de facto admin access.
[]
What to name the full access IAM role
"allow-full-access-from-saml"
What to name the IAM admin access IAM role
"allow-iam-admin-access-from-saml"
What to name the logs access IAM role
"allow-logs-access-from-saml"
The maximum allowable session duration, in seconds, for the credentials you get when assuming the IAM roles created by this module. This variable applies to all IAM roles created by this module that are intended for people to use, such as allow-read-only-access-from-saml. For IAM roles that are intended for machine users, such as allow-auto-deploy-from-other-accounts, see max_session_duration_machine_users
.
43200
The maximum allowable session duration, in seconds, for the credentials you get when assuming the IAM roles created by this module. This variable applies to all IAM roles created by this module that are intended for machine users, such as allow-auto-deploy-from-saml. For IAM roles that are intended for human users, such as allow-read-only-access-from-other-accounts, see max_session_duration_human_users
.
3600
What to name the read-only access IAM role
"allow-read-only-access-from-saml"
What to name the ssh-grunt access IAM role
"allow-ssh-grunt-access-from-saml"
What to name the support access IAM role
"allow-support-access-from-saml"
tags
map(string)A map of tags to apply to the IAM roles.
{}