setlist

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2025 License: MIT Imports: 11 Imported by: 0

README

setlist

SetList (formerly aws-config-creator)

Setlist is a CLI tool that automates the creation of AWS config files for organizations using AWS SSO. It parses AWS Organizations and Permission Sets to build a complete .aws/config file with all permission sets provisioned across your AWS member accounts.

Why Setlist?

Managing AWS credentials across multiple AWS accounts with SSO can be challenging. While AWS provides the aws sso configure command, it's tedious to use when you have:

  • Multiple AWS accounts in your organization
  • Multiple permission sets per account
  • Teams that need consistent configuration

Setlist solves this by automatically generating a complete .aws/config file with profiles for all accounts and permission sets you have access to, saving you time and preventing configuration errors.

Installation

Download Binary

Download the latest release from the GitHub Releases page.

Build from Source
# Clone the repository
git clone https://github.com/scottbrown/setlist.git
cd setlist

# Install Task (if not already installed)
brew install go-task

# Build the binary
task build

# The binary will be available at .build/setlist

Usage

Prerequisites
  1. AWS CLI installed
  2. AWS SSO configured for your organization
  3. AWS credentials with permissions to access AWS Organizations and SSO Admin APIs

Permissions Required

This tool requires some readonly permissions from your AWS organization account. They are:

  1. organizations:ListAccounts
  2. sso:ListInstances
  3. sso:ListPermissionSetsProvisionedToAccount
  4. sso:DescribePermissionSet

You can view these in the application by running:

setlist --permissions
Basic Usage
# Generate AWS config using the organization's SSO instance
setlist --sso-session myorg --sso-region us-east-1 --output ~/.aws/config
Using an AWS Profile
# Use an existing AWS profile to authenticate
setlist --sso-session myorg --sso-region us-east-1 --profile admin --output ~/.aws/config
Using Account Nicknames
# Map account IDs to friendly names
setlist --sso-session myorg --sso-region us-east-1 \
  --mapping "123456789012=prod,210987654321=staging" \
  --output ~/.aws/config
Print to stdout
# Output to stdout instead of a file
setlist --sso-session myorg --sso-region us-east-1 --stdout
Using a Friendly Name for SSO URL
# Use a friendly name instead of the identity store ID
setlist --sso-session myorg \
  --sso-region us-east-1 \
  --sso-friendly-name my-company \
  --output ~/.aws/config

By supplying a --mapping flag with a comma-delimited list of key=value pairs corresponding to AWS Account ID and its nickname, the tool will create the basic .aws/config profiles and then create a separate set of profiles that follow the format [profile NICKNAME-PERMISSIONSETNAME]. For example: [profile acme-AdministratorAccess]. This removes the need for your users to remember the 12-digit AWS Account ID, but also allows for backward-compatibility for those people that like using the AWS Account ID in the profile name.

Configuration Options

Flag Short Description Required
--sso-session -s Nickname for the SSO session (e.g., organization name) Yes
--sso-region -r AWS region where AWS SSO resides Yes
--profile -p AWS profile to use for authentication No
--mapping -m Comma-delimited account nickname mapping (format: id=nickname) No
--output -o Output file path (default: ./aws.config) No
--stdout Write config to stdout instead of a file No
--sso-friendly-name Alternative name for the SSO start URL No

Generated Config Format

Setlist generates an AWS config file with:

  1. A default section specifying the SSO session
  2. An SSO session section with start URL, region, and registration scopes
  3. Profile sections for each account and permission set combination

Example:

[default]
# Generated on: 2025-02-27T10:15:30 UTC
sso_session = myorg

[sso-session myorg]
sso_start_url = https://d-12345abcde.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

# Administrator access. Session Duration: PT12H
[profile 123456789012-AdministratorAccess]
sso_session = myorg
sso_account_id = 123456789012
sso_role_name = AdministratorAccess

# Administrator access. Session Duration: PT12H
[profile prod-AdministratorAccess]
sso_session = myorg
sso_account_id = 123456789012
sso_role_name = AdministratorAccess

Common Use Cases

Team Onboarding

Simplify the onboarding process for new team members by providing a single command that generates a complete AWS config with all the accounts and permission sets they need access to.

Credentials Refresh

When permission sets change in your AWS Organization, quickly regenerate your config file to include the new permission sets without manual configuration.

CI/CD Pipelines

Use Setlist in CI/CD pipelines to ensure consistent AWS configuration across different environments.

Troubleshooting

Permission Issues

If you encounter permission errors, ensure your AWS credentials have access to:

  • organizations:ListAccounts
  • sso-admin:ListInstances
  • sso-admin:ListPermissionSetsProvisionedToAccount
  • sso-admin:DescribePermissionSet
Region Configuration

The --sso-region parameter must specify the region where your AWS SSO instance is deployed, not necessarily the region where your resources are located.

Output File Permissions

Ensure you have write permissions to the output file location.

Development

Prerequisites
  • Go 1.21 or newer
  • Task
Setup Development Environment
# Clone the repository
git clone https://github.com/scottbrown/setlist.git
cd setlist

# Run tests
task test

# Build for development
task build
Running Tests
# Run all tests
task test

# Run security checks
task check
Building Releases
# Build a release version
task release VERSION=v1.2.3
Project Structure
  • cmd/: Command-line interface code
  • *.go: Core functionality for AWS interactions and config generation
  • .github/workflows/: CI/CD pipeline definitions
  • go.mod, go.sum: Go module definitions
  • taskfile.yml: Task automation definitions

Contributing

Contributions are welcome! Here's how to contribute:

  1. Fork the repository
  2. Create a feature branch: git checkout -b my-new-feature
  3. Make your changes and add tests if applicable
  4. Run tests to ensure everything passes: task test
  5. Commit your changes: git commit -am 'Add some feature'
  6. Push to the branch: git push origin my-new-feature
  7. Submit a pull request

Releases

Each release comes with a software bill of materials (SBOM). It is generated using CycloneDX-GoMod using the following command:

cyclonedx-gomod mod -licenses -json -output bom.json

Releases are typically automated via Github Actions whenever a new tag is pushed to the default branch.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Thanks to all contributors who have helped improve Setlist
  • Built with Cobra and AWS SDK for Go v2

Documentation

Overview

Package setlist provides utilities for managing AWS SSO configurations, including building and handling INI files for AWS profiles.

Index

Constants

View Source 
const DefaultNicknamePrefix string = "NoNickname"

DefaultNicknamePrefix defines the prefix used for accounts without explicit nicknames.

View Source 
const SSOAccountIdKey string = "sso_account_id"

SSOAccountIdKey is the key used for specifying the AWS account ID in a profile.

View Source 
const SSORegionKey string = "sso_region"

SSORegionKey is the attribute key for specifying the AWS region.

View Source 
const SSORegistrationScopesKey string = "sso_registration_scopes"

SSORegistrationScopesKey defines the key for SSO registration scopes.

View Source 
const SSORegistrationScopesValue string = "sso:account:access"

SSORegistrationScopesValue defines the default value for SSO registration scopes.

View Source 
const SSORoleNameKey string = "sso_role_name"

SSORoleNameKey is the key used for defining the IAM role name.

View Source 
const SSOSessionAttrKey string = "sso_session"

SSOSessionAttrKey is the attribute key for storing the SSO session name.

View Source 
const SSOSessionSectionKey string = "sso-session"

SSOSessionSectionKey is the key used for defining an SSO session in configuration files.

View Source 
const SSOStartUrlKey string = "sso_start_url"

SSOStartUrlKey is the attribute key for the AWS SSO start URL.

View Source 
const VERSION string = "1.2.1"

Variables

This section is empty.

Functions

func ListAccounts 

func ListAccounts(ctx context.Context, client OrganizationsClient) ([]types.Account, error)

ListAccounts retrieves all accounts within an AWS Organization using the provided Organizations client.

func ListPermissionsRequired added in v1.2.0 

func ListPermissionsRequired() []string

func ParseNicknameMapping 

func ParseNicknameMapping(mapping string) (map[string]string, error)

ParseNicknameMapping parses a nickname mapping string into a map. The expected format is "accountID1=nickname1,accountID2=nickname2". Returns an error if the format is invalid.

func PermissionSets 

func PermissionSets(ctx context.Context, client SSOAdminClient, instanceArn string, accountId string) ([]types.PermissionSet, error)

PermissionSets retrieves the list of permission sets provisioned to an account.

func SsoInstance 

func SsoInstance(ctx context.Context, client SSOAdminClient) (types.InstanceMetadata, error)

SsoInstance retrieves the SSO instance metadata. AWS SSO allows only a single instance per organization.

Types

type ConfigFile 

type ConfigFile struct {
	SessionName     string            // Name of the SSO session
	IdentityStoreId string            // The unique identity store ID
	FriendlyName    string            // Alt name used for the SSO instance
	Region          string            // AWS region
	Profiles        []Profile         // List of AWS profiles
	NicknameMapping map[string]string // Mapping of account IDs to nicknames
}

ConfigFile represents the structure of the configuration file, including session details, profiles, and nickname mappings.

func (ConfigFile) HasNickname 

func (c ConfigFile) HasNickname(accountId string) bool

HasNickname determines whether an account has a mapped nickname.

func (*ConfigFile) StartURL 

func (c *ConfigFile) StartURL() string

StartURL constructs the AWS SSO start URL based on the IdentityStoreId or FriendlyName.

type FileBuilder 

type FileBuilder struct {
	Config ConfigFile
}

FileBuilder is responsible for generating an INI file based on the provided configuration.

func NewFileBuilder 

func NewFileBuilder(configFile ConfigFile) FileBuilder

NewFileBuilder creates a new FileBuilder instance with the given configuration.

func (*FileBuilder) Build 

func (f *FileBuilder) Build() (*ini.File, error)

Build generates an INI file based on the configuration. It adds a default section, an SSO section, and profile sections for each configured profile. If a nickname mapping exists, it creates an additional profile section for the nickname.

type OrganizationsClient added in v1.2.0 

type OrganizationsClient interface {
	ListAccounts(ctx context.Context, params *organizations.ListAccountsInput, optFns ...func(*organizations.Options)) (*organizations.ListAccountsOutput, error)
}

Define interface for the Organizations client to make testing easier

type Profile 

type Profile struct {
	Name            string
	Description     string
	SessionDuration string
	SessionName     string
	AccountId       string
	RoleName        string
}

Profile represents an AWS SSO profile configuration.

type SSOAdminClient added in v1.2.0 

type SSOAdminClient interface {
	ListInstances(ctx context.Context, params *ssoadmin.ListInstancesInput, optFns ...func(*ssoadmin.Options)) (*ssoadmin.ListInstancesOutput, error)
	ListPermissionSetsProvisionedToAccount(ctx context.Context, params *ssoadmin.ListPermissionSetsProvisionedToAccountInput, optFns ...func(*ssoadmin.Options)) (*ssoadmin.ListPermissionSetsProvisionedToAccountOutput, error)
	DescribePermissionSet(ctx context.Context, params *ssoadmin.DescribePermissionSetInput, optFns ...func(*ssoadmin.Options)) (*ssoadmin.DescribePermissionSetOutput, error)
}

Define interface for the SSO Admin client to make testing easier

Source Files

View all Source files

Directories

Path Synopsis
Package main provides the command-line interface (CLI) entry point for the Setlist application.
 Package main provides the command-line interface (CLI) entry point for the Setlist application.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.