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
--region
$AWS_DEFAULT_REGION
--profile
$AWS_DEFAULT_PROFILE
--role
--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
andaws_secret_access_key
must be provided by the user.keys_with_session
All of aws_access_key_id
,aws_secret_access_key
, andaws_session_token
must be provided by the user.profile
Only profile
must be provided by the user.profile_role
Both profile
, androle
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.
Parameters: - 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.
Parameters: - 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: -
assume_role
()¶ 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.
-
assume_temp_session
()¶ Retrieve some temporary credentials from AWS
Return awsauthhelper.Credentials: Allow chaining.
-
authenticate_mfa
()¶ Use the provided mfa_serial, the existing credentials, and get an mfa session token
Returns:
-
create_session
(internal=False)¶ DEPRECATED. Use awsauthhelper.Credentials.get_session_generator() instead.
Returns:
-
freeze
()¶ Take a snapshot of the credentials and remember them.
Return awsauthhelper.Credentials:
-
get_session_generator
(internal=False)¶ 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):
-
has_keys
()¶ Do we have key credentials?
Return bool:
-
has_mfa
()¶ Have we been provided an mfa_serial to use?
Return bool:
-
has_profile
()¶ Do we have profile credentials?
Return bool:
-
has_role
()¶ Do we have a role to assume?
Return bool:
-
has_session_keys
()¶ Do we have temporal key credentials?
Return bool:
-
reset
()¶ Reset Credentials object back to original state, pre any role assumptions.
Return awsauthhelper.Credentials:
-
use_as_global
()¶ 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:
-
using_role
()¶ 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¶
-
awsauthhelper.password.
generate
(password_policy)¶ 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