NAME

Amazon::Credentials

SYNOPSIS

my $aws_creds = Amazon::Credentials->new({order => [qw/env file container role/]});

DESCRIPTION

Class to find AWS credentials from either the environment, configuration files, instance meta-data or container role.

You can specify the order using the order option in the constructor to determine the order in which the class will look for credentials. The default order is environent, file, container, instance meta-data. See "new".

SUBROUTINES/METHODS

new

new( options );

my $aws_creds = Amazon::Credential->new( { profile => 'sandbox', debug => 1 });

options is a hash of keys that represent various options you can pass to the constructor to control how it will look for credentials. Any of the options can also be retrieved using their corresponding 'get_{option} method.

options

aws_access_key_id

AWS access key.

aws_secret_access_key

AWS secret access key.

Note: If you pass the access keys in the constructor then the constructor will not look in other places for credentials.

container - Task Role

If the process is running in a container, the container may have a task role. We'll look credentials using the container metadata service.

http://169.254.170.2/$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

debug

Set to true for verbose troubleshooting information. Set logger to a logger that implements a logging interface (ala Log::log4perl.

env - Environment

If there exists an environment variable $AWS_PROFILE, then an attempt will be made to retrieve credentials from the credentials file using that profile, otherwise the class will for these environment variables to provide credentials.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

Note that when you set the environment variable AWS_PROFILE, the order essentially is overridden and we'll look in your credential files (~/.aws/config, ~/.aws/credentials) for your credentials.

file - Configuration Files

~/.aws/config
~/.aws/credentials

The class will attempt to find the credentials in either of these two files. You can also specify a profile to use for looking up the credentials by passing it into the constructor or setting it the environment variable AWS_PROFILE. If no profile is provided, the default credentials or the first profile found is used.

my $aws_creds = Amazon::Credentials->new({ order => [qw/environment role file/] });

logger

Pass in your own logger that has a debug() method. Otherwise the default logger will output debug messages to STDERR.

order

An array reference containing tokens that specifies the order in which the class will search for credentials.

default: env, role, container, file

Example:

my $creds = Amazon::Credentials->new( { order => [ qw/file env role/] });

profile

The profile name in the configuration file (~/.aws/config or ~/.aws/credentials).

my $aws_creds = Amazon::Credentials->new({ profile => 'sandbox' });

The class will also look for the environment variable AWS_PROFILE, so you can invoke your script like this:

$ AWS_PROFILE=sandbox my-script.pl

region

Default region. The class will attempt to find the region in either the configuration files or the instance unless you specify the region in the constructor.

role - Instance Role

The class will use the http://169.254.169.254/latest/meta-data/iam/security-credential URL to look for an instance role and credentials.

Credentials returned by accessing the meta-data include a token that should be passed to Amazon APIs along with the access key and secret. That token has an expiration and should be refreshed before it expires.

if ( $aws_creds->is_token_expired() ) {
  $aws_creds->refresh_token()
}

timeout

When looking for credentials in metadata URLs, this parameter specifies the timeout value for LWP. The default is 3 seconds.

user_agent

Pass in your own user agent, otherwise LWP will be used. Probably only useful to override this for testing purposes.>

as_string

as_string()

Returns the credentials as a JSON encode string.

credential_keys

my $credential_keys = $creds->credential_keys;

Return a hash reference containing the credential keys with standard key names. Note that the session token will only be present in the hash for temporary credentials.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

format_credentials

format_credentials(format-string)

Returns the credentials as a formatted string. The <format> argument allows you to include a format string that will be used to output each of the credential parts.

format("export %s=%s\n");

The default format is a "%s %s\n".

find_credentidals

find_credentials( option => value, ...);

You normally don't want to use this method. It's automatically invoked by the constructor if you don't pass in any credentials. Accepts a hash or hash reference consisting of keys (order or profile) in the same manner as the constructor.

get_creds_from_*

These methods are called internally when the new constructor is invoked. You should not normally call these methods

get_creds_from_container

get_creds_from_container()

Retrieves credentials from the container's metadata at http://169.254.170.2. Returns a hash of credentials containing:

aws_access_key_id
aws_secret_access_key
aws_session_token

Returns an empty hash if no credentials found. The environment variable AWS_CONTAINER_CREDENTIALS_RELATIVE_URI must exist or you must pass the value of the path as an argument.

get_creds_from_process

get_creds_from_process(process)

Retrieves credentials from a helper process defined in the config file. Returns the credentials tuple.

get_creds_from_role

get_creds_from_role()

Returns a hash, possibly containing access keys and a token.

aws_access_key_id: The AWS access key.
aws_secret_access_key: The AWS secret key.
token: Security token used with access keys.
expiration: Token expiration date.
role: IAM role if available.
source: Will be 'IAM' if role and credentials found.

get_default_region

Returns the region of the currently running instance. The constructor will set the region to this value unless you set your own region value. Use get_region to retrieve the value after instantiation or you can call this method again and it will make a second call to retrieve the instance metadata.

You can also invoke this as a class method:

AWS_REGION=$(perl -MAmazon::Credentials -e 'print Amazon::Credentials::get_default_region;')

get_ec2_credentials (deprecated)

See "find_credentials"

is_token_expired

is_token_expired( window-interval )

Returns true if the token is about to expire (or is expired). window-interval is the time in minutes before the actual expiration time that the method should consider the token expired. The default is 5 minutes. Amazon states that new credentials will be available at least 5 minutes before a token expires.

refresh_token

refresh_token() (deprecated)
refresh_credentials()

Retrieves a fresh set of IAM credentials.

if ( $creds->is_token_expired ) {
  $creds->refresh_token()
}

SETTERS/GETTERS

All of the parameters described in the new method can be accessed by a getter or set using a setter.

CONTRIBUTING

You can find this project on GitHub at https://github.com/rlauer6/perl-Amazon-Credentials. PRs are always welcomed!

VERSION

This document reverse to verion @PACKAGE_VERION@ of Amazon::Credentials.

DIAGNOSTICS

Set the environment variable DEBUG or pass a true value for the debug attribute in the constructor to output debug and diagnostic messages.

CONFIGURATION AND ENVIRONMENT

The module will recognize severa AWS specific environment variables describe throughout this documentation.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
AWS_REGION
AWS_DEFAULT_REGION
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI

You can also set the environment variable DEBUG to any true value to output debugging information.

BUGS AND LIMITATIONS

Amazon::Credentials will not attempt to retrieve temporary credentials for profiles that specify a role. If you, for example you define a role in your credentials file:

[developer]

 role_arn = arn:aws:iam::123456789012:role/developer-access-role
 source_profile = dev

The module will not return credentials for the developer profile.

DEPENDENCIES

Dependencies as report by scandeps.pl...however lower versions of these modules are probably acceptable.

'Carp'                          => '1.26',
'Class::Accessor::Fast'         => '0.31',
'Config::Tiny'                  => '2.28',
'Data::Dumper'                  => '2.145',
'Date::Format'                  => '2.24',
'Exporter'                      => '5.68',
'File::HomeDir'                 => '1.00',
'File::chdir'                   => '0.1010',
'HTTP::Request'                 => '6.00',
'JSON::PP'                      => '2.97001',
'LWP::UserAgent'                => '6.36',
'POSIX::strptime'               => '0.13',
'Scalar::Util'                  => '1.50',
'Time::Local'                   => '1.2300',
'constant'                      => '1.33',
'parent'                        => '0.225',

INCOMPATIBILITIES

This module has not been tested on Windows OS.

LICENSE AND COPYRIGHT

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

AUTHOR

Rob Lauer - <rlauer6@comcast.net>

To install Amazon::Credentials, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Amazon::Credentials

CPAN shell

perl -MCPAN -e shell
install Amazon::Credentials

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)