README.md

awssume - Golang package (and CLI) to manage assuming IAM Roles

Package awssume implements operations around assuming AWS IAM Roles. See documentation on Using IAM Roles and the STS AssumeRole API for more information on how assuming IAM Roles works.

The package uses AWS SDK for Go v2, so it uses the standard configuration patterns common to all official AWS SDKs. It (awssume) does, however, introduce its own configuration, because the configuration shape it works with does not fit within an existing scheme easily.

awssume can be useful in scenarios when working with credentials in one AWS Account, but needing to quickly switch IAM Roles to perform certain tasks. There are other packages out there that help with assuming Roles from identity providers through federataion (see sts:AssumeRoleWithSAML and sts:AssumeRoleWithWebIdentity) (like saml2aws), but they do not offer a solution for performing sts:AssumeRole without any federation and exposing the security credentials as environment variables. This package (and CLI) was written out of that need.

Install

awssume the package can be installed via Go get:

$ go get -u -v github.com/gkze/awssume

awssume the CLI can be installed either via Go get:

$ go get -u -v github.com/gkze/awssume/cmd/awssume

or Homebrew:

brew install gkze/gkze/awssume

Configuration and Usage

awssume does not require initial configuration, and is able to generate its own configuration, given the correct calls / commands.

This is a simple example of how it can be done from Go:

import (
    "github.com/aws/aws-sdk-go-v2/aws/arn"
    "github.com/gkze/awssume/pkg/awssume"
    "github.com/spf13/afero"
)

func main() {
    cfg, err := awssume.NewConfig(&awssume.NewConfigOpts{
        Fs: afero.NewOsFs(), Path: awassume.DefaultConfigFilePath,
    })
    if err != nil {
        panic(err)
    }

    parsedARN, err := arn.Parse("arn:aws:iam::0000000000000:role/SomeRole")
    if err != nil {
        panic(err)
    }

    if err := cfg.AddRole(&awssume.Role{
        Alias: "someAlias",
        ARN: parsedARN,
        SessionName: "someSession",
    }); err != nil {
        panic(err)
    }

    if err := cfg.Save(); err != nil {
        panic(err)
    }
}

From the CLI, it can be done like so:

# awssume add [role] [alias] [session_name]
$ awssume add arn:aws:iam::0000000000000:role/SomeRole someAlias someSession

By default, awssume serializes the configuration to YAML, at the path ~/.config/awssume.yaml. However, awssume is also capable of storing its configuration in either JSON or TOML, and can convert between any two of the formats.

Converting formats is easy:

import (
    "github.com/gkze/awssume/pkg/awssume"
    "github.com/spf13/afero"
)

func main() {
    cfg, err := awssume.NewConfig(&awssume.NewConfigOpts{
        Fs: afero.NewOsFs(), Path: awassume.DefaultConfigFilePath,
    })
    if err != nil {
        panic(err)
    }

    cfg.SetFormat(awssume.JSON)

    if err := cfg.Save(); err != nil {
        panic(err)
    }
}

or

$ awssume convert json

This would make ~/.config/awssume.yaml disappear and ~/.config/awssume.json appear instead in its place.

Executing an Authenticated Subprocess

The main feature of awssume is to execute processes that have STS Temporary Security Credentials exposed as environment variables.

From Go:

import (
    "github.com/gkze/awssume/pkg/awssume"
    "github.com/spf13/afero"
)

func main() {
    cfg, err := awssume.NewConfig(&awssume.NewConfigOpts{
        Fs: afero.NewOsFs(), Path: awassume.DefaultConfigFilePath,
    })
    if err != nil {
        panic(err)
    }

    cfg.ExecRole(
        "roleAlias", // Configured IAM Role alias
        60 * 60,     // 1 hour
        "aws",       // command
        []string{    // arguments
            "sts",
            "get-caller-identity",
        },
    )
}

From the CLI:

$ awssume roleAlias exec -- aws sts get-caller-identity

License

MIT