Terraform

Tokenless Terraform using SAML.to

Introduction

The SAML.to Command Line Interface can be used for authentication to AWS and can be used with the terraform CLI or any tool that supports Terraform (such as terragrunt).

This document will detail how to use SAML.to to authenticate to AWS to run Terraform commands with Tokenless Authentication.

Create a Terraform Runner Role

Create a terraform-runner role (or whatever name you prefer) that has a Trust Relationship to SAML.to.

Example: Role Permissions for Terraform + S3 State Storage

If the Terraform Configuration uses S3 State storage, such as:

terraform {
  backend "s3" {
    bucket = "mybucket"
    key    = "path/to/my/key"
    region = "us-east-1"
  }
}

The role needs permission to the S3 Bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::mybucket"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::mybucket/path/to/my/key"
    }
  ]
}

In saml-to.yml, grant access to GitHub Users to assume terraform-runner:

      - name: arn:aws::YOUR_ACCOUNT_ID:role/terraform-runner
        ...
        users:
          github:
            - SOME_GITHUB_USERNAME
            - ANOTHER_GITHUB_USERNAME

Ensure the role is functional:

$(saml-to assume terraform-runner)
aws sts get-caller-identity

And run terraform init to ensure you have access to the State File.

If the Role in AWS has Read/Write permissions to the AWS account, such as AdministratorAccess, at this point, you can run terraform plan and terraform apply with the terraform-runner identity.

If you want to make a second role in the same or another account, see A Terraform Applier Role.

Optional: A Terraform Applier Role

Create a second role in whatever AWS account you'd like, terraform-applier (or whatever you want to call it) that grants terraform-runner the ability to assume it:

Trust Relationship

{
  "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:role/terraform-runner"
        },
        "Action": "sts:AssumeRole"
    }]
}

It's not necessary to declare terraform-applier in the saml-to.yml. Role Assumption in Terraform uses STS Role Assumption internally and relies on IAM trust relationships!

Configure role assumption in Terraform:

terraform {
  ... uses the System Terminal Role for terraform init ...
}

provider "aws" {
  profile = "terraform-runner"
  region  = "us-east-1"
  assume_role {
    role_arn = "arn:aws:iam::THE_ACCOUNT_ID:role/terraform-applier"
  }
}

resource "aws_..." {
  ... Terraform transparently assumes terraform-applier, then creates the resource ...
}

Save the temporary credentials to ~/.aws/credentials using the --save flag on the SAML.to CLI:

saml-to assume terraform-runner --save

And run Terraform commands:

terraform init
terraform plan
terraform apply 

Questions/Comments/Issues?

Contact us!