4. API Reference

4.1. AWSArgumentParser

This class provides a prepackaged set of cli options for AWS authentication.

CLI Option Default Description
--aws-access-key-id $AWS_ACCESS_KEY_ID  
--aws-secret-access-key $AWS_SECRET_ACCESS_KEY  
--aws-session-token $AWS_SESSION_TOKEN  
--config-path $AWS_CONFIG_FILE Custom path to an AWS config file
--credentials-path $AWS_SHARED_CREDENTIALS_FILE Custom path to an AWS credentials path
--auth-debug   If this flag is enabled, execution of the application will stop when create_session() is called.

The AWSArgumentParser class takes all the arguments of a argparser.ArgumentParser class in addition to:

  • role_session_name is a default value in case --role_session_name is not provided by the user.

  • region is a default value in case --region is not provided by the user.

  • profile is a default value in case --profile is not provided by the user.

  • enforce_auth_type enforces the type of arguments which must be passed to this utility. Can be one of:

    Argument Description
    keys Both aws_access_key_id and aws_secret_access_key must be provided by the user.
    keys_with_session All of aws_access_key_id, aws_secret_access_key, and aws_session_token must be provided by the user.
    profile Only profile must be provided by the user.
    profile_role Both profile, and role must be provided by the user.
    config Only config_path must be provided by the user.
    credentials Only credentials_path must be provided by the user.

Like argparse.ArgumentParser, AWSArgumentParser allows chaining/inclusion of multiple ArgumentParser objects through the list[argparse.ArgumentParser]: parents constructor argument. The child ArgumentParser appears last in the list of options when --help is called, so it’s best to add other ArgumentParser objects to AWSArgumentParser, rather than the reverse.

class awsauthhelper.AWSArgumentParser(role_session_name, region=None, profile=None, enforce_auth_type=None, **kwargs)

Helper Class containing a preset set of cli arguments for parsing into the Credentials object. If not explicitly set, arguments are read from the environment variables.

Create our arguments and determine if we need to enforce an auth method.

  • role_session_name (str) – Default name for the role session, in case a user does not provide one.
  • region (str) – AWS Region
  • profile (str) – Name of the profile in the AWS profile to use as the base configuration.
  • enforce_auth_type (str) – The Authentication method can be locked to one of {‘keys’, ‘keys_with_session’, ‘profile’, ‘profile_role’,’config’,’credentials’}
  • kwargs (dict) –
Return awsauthhelper.AWSArgumentParser:

4.2. validate_creds

Helper function validate your credential combinations

4.3. Credentials

The Credentials class allows us to encapsulate and hide all the aws auth operations, exposing three key methods:

The arguments this class takes are the same format as libawsauth.ArgumentParser(), so the Namespace object returned from argparse.ArgumentPareser.parse_args() can be wrapped in vars(...) and injected as kwargs into the Credentials(...) constructor.

>>> configs = aws_options.parse_args()
>>> credentials = awsauthhelper.Credentials(
...   **vars(configs)
... )

>>> if credentials.has_role():
>>>     credentials.assume_role()
>>> boto3_session = credentials.create_session()

>>> s3 = boto3_session().resource('s3')
>>> for bucket in s3.buckets.all():
>>>    print(bucket.name)

>>> for region in regions:
>>>    # The session object can be 're-authorised' across regions.
>>>    print(
...       boto3_session(region=region['RegionName']).client('ec2').describe_instances()
...    )
class awsauthhelper.Credentials(region=None, aws_secret_access_key=None, aws_access_key_id=None, aws_session_token=None, profile=None, role=None, role_session_name=None, config_path=None, credentials_path=None, mfa_serial=None, mfa_session_life=900, mfa_token=None, force_mfa=False, auth_debug=False, **kwargs)

Encapsulates processing of AWS credentials.

Handle the assumption of roles, and creation of Session objects.

  • region (str) – AWS region
  • aws_secret_access_key (str) – AWS_SECRET_ACCESS_KEY to use for the base credentials.
  • aws_access_key_id (str) – AWS_ACCESS_KEY_ID to use for the base credentials.
  • aws_session_token (str) – AWS_SESSION_TOKEN to use for the base credentials. Generally this should not be needed as roles are assumed through providing a role argument.
  • profile (str) – Name of the profile in the AWS profile to use as the base configuration.
  • role (str) – ARN of the AWS IAM Role to assume.
  • role_session_name (str) – Custom name of the role session to override the default.
  • config_path (str) – Custom path to the aws config file if it is not in a location botocore expects.
  • credentials_path (str) – Custom path to the aws credentials file if it is not in a path botocore expects.
  • mfa_serial (str) – Identification number of the MFA device. If you set this argument, your will be prompted for your MFA token.
  • mfa_session_life (str) – The duration, in seconds, that the mfa credentials should remain valid.
  • mfa_token (str) – MFA token to authentication to AWS with.
  • auth_debug (bool) – Whether or not to print debug information. If True, exit() is throw at create_session()
  • kwargs (dict) – catcher to allow arbitrary **var(my_args.parse_args(...)) to be passed in. Arguments in **kwargs not used at all.
Return awsauthhelper.Credentials:

Check if we have a role, and assume it if we do. Otherwise, raise exception.

Raises:ValueError – If a role has not be specified.
Return awsauthhelper.Credentials:
 Allow chaining.

Retrieve some temporary credentials from AWS

Return awsauthhelper.Credentials:
 Allow chaining.

Use the provided mfa_serial, the existing credentials, and get an mfa session token


DEPRECATED. Use awsauthhelper.Credentials.get_session_generator() instead.


Take a snapshot of the credentials and remember them.

Return awsauthhelper.Credentials:

Return a callable which will generate a boto3 Session

Parameters:internal (bool) – Whether or not this method was called from internal or external to the class
Return callable(region):

Do we have key credentials?

Return bool:

Have we been provided an mfa_serial to use?

Return bool:

Do we have profile credentials?

Return bool:

Do we have a role to assume?

Return bool:

Do we have temporal key credentials?

Return bool:

Reset Credentials object back to original state, pre any role assumptions.

Return awsauthhelper.Credentials:

Set this object to use its current credentials as the global boto3 settings. If a role has been assumed, the assumed credentials will be used. If a role is set but has not been assumed, the base credentials will be used. WARNING: This will affect all calls made to boto3.

Return awsauthhelper.Credentials:

If we have a role and either a set of credentials or a profile, then we should assume the role.

Return bool:

4.4. Password generation


Builds a password based on the password policy provided password_policy should be an object with the attributes:

  • minimum_password_length (int) – Minimum length of password. Maximum length of password will be the ceiling of 1.3 times this value.
  • require_symbols (bool) – Make sure password contains !@#$%^&*()_+-=[]{}|'.
  • require_lowercase_characters (bool) – Make sure password contains abcdefghijklmnopqrstuvwxyz.
  • require_uppercase_characters (bool) – Make sure password contains ABCDEFGHIJKLMNOPQRSTUVWXYZ.
  • require_numbers (bool) – Make sure password contains 0123456789.
Parameters:password_policy (iam.AccountPasswordPolicy) – boto password policy
Return basestring:
 New password