cognito-auth

README

Cognito Auth

Maintainer: Kim Pepper

Cognito Auth is a Go package for authenticating with AWS Cognito from the command line, retrieving temporary, limited-privilege credentials for AWS Identity and Access Management (IAM).

These are stored locally for re-use, and automatically refreshed if stale.

Commands

Two modes of authentication are supported:

• Cognito User Pool Authentication
• OpenID Connect Authentication

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

  oidc login [<flags>]
    Logs in a user using their oidc account.

  userpool login --username=USERNAME [<flags>]
    Logs in a user to a Cognito Userpool.

  userpool logout [<flags>]
    Logs out a user from a Cognito Userpool

  userpool reset-password --username=USERNAME [<flags>]
    Resets a users Cognito Userpool password.

Once a user has logged in, they are able to generate a one-time sign in URL to the AWS Console:

  console-signin [<flags>]
    Generates a console sign-in link.

Configuration

User Pool Authentication

Cognito Auth looks for a configuration file in $HOME/.config/cognito-auth/userpool.yml.

Example configuration:

identity_provider_id: <YOUR IDENTITY PROVIDER ID> 
identity_pool_id: <YOUR IDENTITY POOL ID>
client_id: <YOUR CLIENT ID>
console_destination: https://console.aws.amazon.com/cloudwatch
console_issuer: <YOUR CONSOLE ISSUER URL>

Note: client_secret is optional for User Pool Authentication.

By default, it will store OAuth2 tokens and AWS STS Credentials in yaml files in $HOME/Library/Caches/cognito-auth/ (MacOS) or $HOME/.cache/cognito-auth/ (Linux).

OpenID Connect Authentication

Cognito Auth looks for a configuration file in $HOME/.config/cognito-auth/oidc.yml.

identity_provider_id: <YOUR IDENTITY PROVIDER ID>
identity_pool_id: <YOUR IDENTITY POOL ID>
client_id: <YOUR CLIENT ID>
client_secret: <YOUR CLIENT SECRET>
auth_url: <YOUR OIDC AUTH URL>
token_url: <YOUR OIDC TOKEN URL>
console_destination: https://console.aws.amazon.com/cloudwatch
console_issuer: <YOUR CONSOLE ISSUER URL>

OpenID Connect Authentication uses the code flow.

Note: client_secret may be required dependending on your Identity Provider (e.g. Google).

Secure Token Storage

Cognito Auth allows you to store OAuth2 tokens and AWS Credentials in a OS-native keychain.

To enable this feature, add the following lines to the configuration:

creds_store: native
creds_oauth_key: Cognito OAuth Tokens
creds_aws_key: Cognito AWS Credentials

creds_oauth_key and creds_aws_key are used as the unque keychain item key for storage.

Development

Getting started

To work on this project you will first need Go installed on your machine.

Setup

First make sure Go is properly installed and that a GOPATH has been set. You will also need to add $GOPATH/bin to your $PATH. For steps on getting started with Go: https://golang.org/doc/install

Next, using Git, clone this repository into $GOPATH/src/github.com/skpr/cognito-auth. All the necessary dependencies are either vendored or automatically installed, so you just need to type make test. This will run the tests and compile the binary. If this exits with exit status 0, then everything is working!

$ cd "$GOPATH/src/github.com/skpr/cognito-auth"
$ make test

To compile a development version of cognito-auth, run make build. This will build everything using gox and put binaries in the bin and $GOPATH/bin folders:

$ make build
...

# Linux:
$ bin/cognito_auth_linux_amd64 --help

# OSX:
$ bin/cognito_auth_darwin_amd64 --help

Dependencies

cognito-auth use Go Modules for managing dependencies.

Releases

Release artifacts are pushed to the github releases page when tagged properly. Use semantic versioning prefixed with v for version scheme. Examples:

• v1.0.0
• v1.1.0-beta1