saml2aws

README

saml2aws

CLI tool which enables you to login and retrieve AWS temporary credentials using SAML with ADFS 3.x.

This is based on python code from How to Implement a General Solution for Federated API/CLI Access Using SAML 2.0.

The process goes something like this:

• Prompt user for credentials
• Log in to ADFS using form based authentication
• Build a SAML assertion containing AWS roles
• Exchange the role and SAML assertion with AWS STS service to get a temporary set of credentials
• Save these creds to an aws profile named "saml"

Requirements

• ADFS 3.x
• AWS SAML Provider configured

Usage

saml2aws --help-long
usage: saml2aws [<flags>] <command> [<args> ...]

A command line tool to help with SAML access to the AWS token service.

Flags:
  --help     Show context-sensitive help (also try --help-long and --help-man).
  --version  Show application version.

Commands:
  help [<command>...]
    Show help.


  login [<flags>]
    Login to a SAML 2.0 IDP and convert the SAML assertion to an STS token.

    -s, --skip-verify     Skip verification of server certificate.
    -p, --profile="saml"  The AWS profile to save the temporary credentials

install

If your on OSX you can install saml2aws using homebrew!

brew tap versent/homebrew-taps
brew install saml2aws

Setup

Install the AWS CLI see https://docs.aws.amazon.com/cli/latest/userguide/installing.html, in our case we are using homebrew on OSX.

brew install awscli

Configure an empty default profile with your region of choice.

$ aws configure
AWS Access Key ID [None]:
AWS Secret Access Key [None]:
Default region name [None]: us-west-2
Default output format [None]:

Then your ready to use saml2aws.

Example

$ saml2aws login
Hostname [id.example.com]:
Username [mark.wolfe@example.com]:
Password: ************

ADFS https://id.example.com
Authenticating to ADFS...
Please choose the role you would like to assume:
[ 0 ]:  arn:aws:iam::123123123123:role/AWS-Admin-CloudOPSBuild
[ 1 ]:  arn:aws:iam::123123123123:role/AWS-Admin-CloudOPSNonProd
Selection: 1
Selected role: arn:aws:iam::123123123123:role/AWS-Admin-CloudOPSNonProd
Requesting AWS credentials using SAML assertion
Saving credentials

Your new access key pair has been stored in the AWS configuration
Note that it will expire at 2016-09-19 15:59:49 +1000 AEST
To use this credential, call the AWS CLI with the --profile option (e.g. aws --profile saml ec2 describe-instances).

Dependencies

This tool would not be possible without some great opensource libraries.

• goquery html querying
• etree xpath selector
• kingpin command line flags
• aws-sdk-go AWS Go SDK
• go-ini INI file parser

License

This code is Copyright (c) 2015 Versent and released under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.

Documentation

Index

• Variables
• func ExtractAwsRoles(data []byte) ([]string, error)
• type ADFSClient
  • func NewADFSClient(skipVerify bool) (*ADFSClient, error)
  • func (ac *ADFSClient) Authenticate(loginDetails *LoginDetails) (string, error)
• type AWSRole
  • func PromptForAWSRoleSelection(roles []string) (*AWSRole, error)
• type ConfigLoader
  • func NewConfigLoader(profile string) *ConfigLoader
  • func (p *ConfigLoader) LoadHostname() (string, error)
  • func (p *ConfigLoader) LoadUsername() (string, error)
  • func (p *ConfigLoader) SaveHostname(hostname string) error
  • func (p *ConfigLoader) SaveUsername(username string) error
• type CredentialsProvider
  • func NewSharedCredentials(profile string) *CredentialsProvider
  • func (p *CredentialsProvider) Load() (string, string, string, error)
  • func (p *CredentialsProvider) Save(id, secret, token string) error
• type ErrMissingElement
  • func (e ErrMissingElement) Error() string
• type LoginDetails
  • func PromptForLoginDetails(username, hostname string) (*LoginDetails, error)

Variables

var (
	// ErrCredentialsHomeNotFound returned when a user home directory can't be located.
	ErrCredentialsHomeNotFound = errors.New("user home directory not found")

	// ErrCredentialsNotFound returned when the required aws credentials don't exist.
	ErrCredentialsNotFound = errors.New("aws credentials not found")
)

var (
	// ErrConfigHomeNotFound returned when a user home directory can't be located.
	ErrConfigHomeNotFound = errors.New("user home directory not found")

	// ErrConfigFileNotFound returned when the required aws credentials file doesn't exist.
	ErrConfigFileNotFound = errors.New("aws credentials file not found")
)

var (
	ErrMissingAssertion = ErrMissingElement{Tag: assertionTag}
)

ErrMissingAssertion indicates that an appropriate assertion element could not be found in the SAML Response

Functions

func ExtractAwsRoles

func ExtractAwsRoles(data []byte) ([]string, error)

Types

type ADFSClient

type ADFSClient struct {
	// contains filtered or unexported fields
}

ADFSClient wrapper around ADFS enabling authentication and retrieval of assertions

func NewADFSClient

func NewADFSClient(skipVerify bool) (*ADFSClient, error)

NewADFSClient create a new ADFS client

func (*ADFSClient) Authenticate

func (ac *ADFSClient) Authenticate(loginDetails *LoginDetails) (string, error)

Authenticate authenticate to ADFS and return the data from the body of the SAML assertion.

type AWSRole

type AWSRole struct {
	RoleARN      string
	PrincipalARN string
}

AWSRole aws role attributes

func PromptForAWSRoleSelection

func PromptForAWSRoleSelection(roles []string) (*AWSRole, error)

PromptForAWSRoleSelection present a list of roles to the user for selection

type ConfigLoader

type ConfigLoader struct {
	Filename string
	Profile  string
}

ConfigLoader loads config options

func NewConfigLoader

func NewConfigLoader(profile string) *ConfigLoader

NewConfigLoader helper to create the config

func (*ConfigLoader) LoadHostname

func (p *ConfigLoader) LoadHostname() (string, error)

LoadHostname load the hostname

func (*ConfigLoader) LoadUsername

func (p *ConfigLoader) LoadUsername() (string, error)

LoadUsername load the username

func (*ConfigLoader) SaveHostname

func (p *ConfigLoader) SaveHostname(hostname string) error

SaveHostname persist the hostname

func (*ConfigLoader) SaveUsername

func (p *ConfigLoader) SaveUsername(username string) error

SaveUsername persist the username

type CredentialsProvider

type CredentialsProvider struct {
	Filename string
	Profile  string
}

CredentialsProvider loads aws credentials file

func NewSharedCredentials

func NewSharedCredentials(profile string) *CredentialsProvider

NewSharedCredentials helper to create the credentials provider

func (*CredentialsProvider) Load

func (p *CredentialsProvider) Load() (string, string, string, error)

func (*CredentialsProvider) Save

func (p *CredentialsProvider) Save(id, secret, token string) error

Save persist the credentials

type ErrMissingElement

type ErrMissingElement struct {
	Tag, Attribute string
}

ErrMissingElement is the error type that indicates an element and/or attribute is missing. It provides a structured error that can be more appropriately acted upon.

func (ErrMissingElement) Error

func (e ErrMissingElement) Error() string

type LoginDetails

type LoginDetails struct {
	Username string
	Password string
	Hostname string
}

LoginDetails used to authenticate to ADFS

func PromptForLoginDetails

func PromptForLoginDetails(username, hostname string) (*LoginDetails, error)

PromptForLoginDetails prompt the user to present their username, password and hostname