Skip to content

Latest commit

 

History

History
228 lines (166 loc) · 7.55 KB

README.md

File metadata and controls

228 lines (166 loc) · 7.55 KB

Assume AWS Role (assume-aws-role)

Assume an AWS role using SAML.to

Example Usage

"features": {
    "ghcr.io/saml-to/devcontainer-features/assume-aws-role:2": {}
}

Options

Options Id Description Type Default Value
role (Optional) The AWS Role Name (or ARN). If specified, role prompts will be skipped. string -
profile (Optional) The AWS Profile (in `~/.aws) to set. string default
region (Optional) The AWS region (in `~/.aws/config) to set. string us-east-1
org (Optional) The GitHub user/organization for which to use a saml-to.yml. string -
provider (Optional) The Provider Key in the user/organization's saml-to.yml. string -

Customizations

VS Code Extensions

  • saml-to.saml-to-vscode

Overview

This Devcontainer Feature enables GitHub Codespaces to obtain AWS Access Credentials for a desired IAM Role using AWS IAM SAML and a GitHub Actions Repository Token.

Benefits:

  • No need to copy/paste AWS Access Tokens into Codespaces Secrets
  • No need to rotate AWS Access Tokens

This action uses SAML.to and an AWS IAM Identity Provider to exchange the Codespace User's GitHub Token for AWS Access Credentials.

This feature will store and rotate AWS credentials for the Devcontainer in:

  • /home/codespace/.aws/credentials
  • /home/codespace/.aws/config

Usage in devcontainer.json

"features": {
    "ghcr.io/saml-to/devcontainer-features/assume-aws-role:2": {
        "role": "arn:aws:iam::123456789012:role/some-role"
    }
}

Usage

  1. Follow the Installation instructions
  2. Launch the Devcontainer using GitHub Codespaces
  3. The assume-aws-role feature will automatically create and update:
    • /home/codespace/.aws/credentials
    • /home/codespace/.aws/config
    • When:
      • When first connecting to a codespace
      • Before the credentials expire (every ~30 minutes)

With the AWS CLI

Within a Terminal of Codespaces, you can:

  • aws sts get-caller-identity: Show which role is assumed
  • aws s3 cp ...: For example, if the role is granted S3 Access
  • aws ec2 describe-instances: For example, if the role is granted EC2 Access

Within an Application

If Codespaces launches an Application (Python, Node, etc.) the AWS SDK installed (boto3, @aws-sdk, etc) is configured to read credentials from ~/.aws/credentials.

In Python (or even a Jupyter Notebook codespace!), for example:

pip install boto3
import boto3

sts = boto3.client('sts')
s3 = boto3.client('s3')

print(sts.get_caller_identity())
print(s3.list_buckets())

Installation

Step 1: Configure AWS

  1. Download Your Metadata from SAML.to

  2. If you haven't already, create a new SAML Identity Provider in AWS IAM

    1. Provider Name: saml.to
    2. Metadata Document: Upload the IdP Metadata from SAML.to
    3. Make note of the Provder ARN in the AWS console

  3. Create or Edit an IAM Role. Set the Trust Relationship on a the Role to contain the following statement:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "PROVIDER_ARN"
      },
      "Action": "sts:AssumeRoleWithSAML",
      "Condition": {
        "StringEquals": {
          "SAML:aud": "https://signin.aws.amazon.com/saml"
        }
      }
    }
  ]
}
    • Replace PROVIDER_ARN with the newly created ARN of the provider, e.g. arn:aws:iam::123456789012:saml-provider/saml.to
    • Make note of the Role ARN for this Role

  4. Add a new file named saml-to.yml to the Codespaces Repository:

    your-codespaces-repository/saml-to.yml:

    ---
version: "20220101"
providers:
  aws:
    entityId: https://signin.aws.amazon.com/saml
    acsUrl: https://signin.aws.amazon.com/saml
    attributes:
      https://aws.amazon.com/SAML/Attributes/RoleSessionName: "<#= repo.name #>"
      https://aws.amazon.com/SAML/Attributes/SessionDuration: "3600"
      https://aws.amazon.com/SAML/Attributes/Role: "<#= system.selectedRole #>,<#= provider.variables.providerArn #>"
permissions:
  aws:
    roles:
      - name: ROLE_ARN # Change this
        provider:
          variables:
            providerArn: PROVIDER_ARN # Change this
        users:
          github:
            - YOUR_GITHUB_USERNAME # Change this
    • Replace PROVIDER_ARN with the ARN of the provider created above (e.g. arn:aws:iam::123456689012:saml-provider/my-repository)
    • Replace ROLE_ARN with the ARN of the IAM Role modified above. (e.g. arn:aws:iam::123456689012:role/admin)
    • Replace YOUR_GITHUB_USERNAME with your GitHub User ID (e.g. octokat)
      • Optional: List any additional Github User IDs that may need this Codespace and Role

  5. Commit and Push the changes to saml-to.yml to the Default Branch of the Codespaces Repository.

Step 2: Add the Feature to devcontainer.json

  1. Modify .devcontainer.json to add a feature which will setup the AWS Role:

    your-repository/.devcontainer/devcontainer.json or your-repository/.devcontainer.json:

    {
  ... other devcontainer.json configuration ...

  "features": {
    "ghcr.io/saml-to/devcontainer-features/assume-aws-role:2": {
      "role": "ROLE_ARN"
    },
    "ghcr.io/devcontainers/features/aws-cli:1": {}
  }
}
    • Replace ROLE_ARN with the ARN of the IAM Role modified above. (e.g. arn:aws:iam::123456689012:role/admin)
    • Note: If installing aws CLI is not desired, remove "ghcr.io/devcontainers/features/aws-cli:1": {}

  2. Rebuild the Container or Restart the Codespace to enable the Feature

Changing the Default Region

Add the region option to the assume-aws-role feature:

your-repository/.devcontainer/devcontainer.json or your-repository/.devcontainer.json:

{
  ... other devcontainer.json configuration ...

  "features": {
    "ghcr.io/saml-to/devcontainer-features/assume-aws-role:1": {
      "role": "ROLE_ARN",
      "region": "us-west-2"
    },
    "ghcr.io/devcontainers/features/aws-cli:1": {}
  }
}

FAQs

See FAQs

Maintainers

Help & Support

Note: This file was auto-generated from the devcontainer-feature.json. Add additional notes to a NOTES.md.