Welcome to awsapilib’s documentation!

Contents:

awsapilib

A python library that exposes AWS services that are not covered by boto3, through the usage of undocumented APIs.

• Documentation: https://awsapilib.readthedocs.org/en/latest

Development Workflow

The workflow supports the following steps

• lint

• test

• build

• document

• upload

• graph

These actions are supported out of the box by the corresponding scripts under _CI/scripts directory with sane defaults based on best practices. Sourcing setup_aliases.ps1 for windows powershell or setup_aliases.sh in bash on Mac or Linux will provide with handy aliases for the shell of all those commands prepended with an underscore.

The bootstrap script creates a .venv directory inside the project directory hosting the virtual environment. It uses pipenv for that. It is called by all other scripts before they do anything. So one could simple start by calling _lint and that would set up everything before it tried to actually lint the project

Once the code is ready to be delivered the _tag script should be called accepting one of three arguments, patch, minor, major following the semantic versioning scheme. So for the initial delivery one would call

$ _tag –minor

which would bump the version of the project to 0.1.0 tag it in git and do a push and also ask for the change and automagically update HISTORY.rst with the version and the change provided.

So the full workflow after git is initialized is:

• repeat as necessary (of course it could be test - code - lint :) )

  • code

  • lint

  • test

• commit and push

• develop more through the code-lint-test cycle

• tag (with the appropriate argument)

• build

• upload (if you want to host your package in pypi)

• document (of course this could be run at any point)

Important Information

This template is based on pipenv. In order to be compatible with requirements.txt so the actual created package can be used by any part of the existing python ecosystem some hacks were needed. So when building a package out of this do not simple call

$ python setup.py sdist bdist_egg

as this will produce an unusable artifact with files missing. Instead use the provided build and upload scripts that create all the necessary files in the artifact.

Project Features

• Please look into the usage files.

Installation

At the command line:

$ pip install awsapilib

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv awsapilib
$ pip install awsapilib

Or, if you are using pipenv:

$ pipenv install awsapilib

Or, if you are using pipx:

$ pipx install awsapilib

Usage

Usage for ControlTower

To use ControlTower in a project:

from awsapilib import ControlTower
tower = ControlTower('arn:aws:iam::ACCOUNTID:role/ValidAdministrativeRole')

for account in tower.accounts:
    print(account.name)
>>> root
    Audit
    Log archive

for account in tower.accounts:
    print(account.guardrail_compliance_status)
>>> COMPLIANT
    COMPLIANT
    COMPLIANT

for ou in tower.organizational_units:
    print(ou.name)
>>> Custom
    Core
    Root

# Creates an OU under root
tower.create_organizational_unit('TestOU')
>>> True

# Creates an OU under Workload/Production
# It would raise NonExistentOU exception if the structure does not exist
tower.create_organizational_unit('TestOU', parent_hierarchy=['Workload','Production'])
>>> True

# Creates an OU under Workload/Production
# It would create the structure if the structure does not exist
tower.create_organizational_unit('TestOU', parent_hierarchy=['Workload','Production'], force_create=True)
>>> True

# Deletes an OU under Root OU
tower.delete_organizational_unit('TestOU')
>>> True

# Deletes an OU under Workload/Production
tower.delete_organizational_unit('TestOU', parent_hierarchy=['Workload','Production'])
>>> True


# Creates account "account-name" under OU "SomeOu" under Root OU
tower.create_account(account_name='account-name',
                     account_email='root-email@domain.com',
                     organizational_unit='SomeOU')
>>> True

# Creates account "account-name" under OU "SomeOu" under Workload/Production
# It would raise NonExistentOU exception if the structure does not exist
tower.create_account(account_name='account-name',
                     account_email='root-email@domain.com',
                     organizational_unit='SomeOU',
                     parent_hierarchy=['Workload','Production'])
>>> True

# Creates account "account-name" under OU "SomeOu" under Workload/Production
# It would create the structure if the structure does not exist
tower.create_account(account_name='account-name',
                     account_email='root-email@domain.com',
                     organizational_unit='SomeOU',
                     parent_hierarchy=['Workload','Production'],
                     force_parent_hierarchy_creation=True)
>>> True


# Creates account "account-name" under OU "SomeOu" under Workload/Production
# It would create the structure if the structure does not exist
# Uses all possible attributes.
tower.create_account(account_name='account-name',
                     account_email='root-email@domain.com',
                     organizational_unit='SomeOU',
                     parent_hierarchy=['Workload','Production'],
                     product_name='product-name-for-account',
                     sso_first_name='Bob',
                     sso_last_name='Builder',
                     sso_user_email='bob-builder@construction.com',
                     force_parent_hierarchy_creation=True)
>>> True

Usage for Sso

To use Sso in a project:

from awsapilib import Sso
sso = Sso('arn:aws:iam::ACCOUNTID:role/ValidAdministrativeRole')

for group in sso.groups:
     print(group.name)

Usage for Billing

To use Billing in a project:

from awsapilib import Billing
billing = Billing('arn:aws:iam::ACCOUNTID:role/ValidAdministrativeRole')

# Set tax inheritance on
billing.tax.inheritance = True

# Set tax information
billing.tax.set_information('some address', 'some city', 'some postal code', 'legal name', 'VAT', 'country code')

# Enable pdf invoice
billing.preferences.pdf_invoice_by_mail = True

# Enable credit sharing
billing.preferences.credit_sharing = True

# Set currency to EUR
billing.currency = 'EUR'

# Disable IAM access to billing (needs to be enabled by root and cannot be enabled by this after disabled!)
billing.iam_access = False

Usage for Account Manager

To use Account Manager in a project:

from awsapilib import AccountManager, PasswordManager

password_manager = PasswordManager()
# Most actions require a captcha to be solved to continue.
# The process is interactive and you get a prompt to solve the captcha by following a url with it
# in a standard console or by presenting the captcha in the terminal if you are using iTerm

# Using the Captcha2 solver would automate the process.
from awsapilib.captcha import Captcha2
solver = Captcha2('API_TOKEN_HERE_FOR_2CAPTCHA_SERVICE')
password_manager = PasswordManager(solver=solver)

# Request the reset of a password for an account
password_manager.request_password_reset('EMAIL_OF_AN_ACCOUNT')
# The above should trigger a reset email with a reset link

# Reset the password
password_manager.reset_password('RESET_URL_RECEIVED_BY_EMAIL_HERE', 'PASSWORD_TO_SET')

account_manager = AccountManager(email, password, region, mfa_serial)
# Most actions require a captcha to be solved to continue.
# The process is interactive and you get a prompt to solve the captcha by following a url with it
# in a standard console or by presenting the captcha in the terminal if you are using iTerm

# Using the Captcha2 solver would automate the process.
from awsapilib.captcha import Captcha2
solver = Captcha2('API_TOKEN_HERE_FOR_2CAPTCHA_SERVICE')
account_manager = AccountManager(email, password, region, mfa_serial, solver=solver)

# Enable IAM billing console access for the account
print(account_manager.iam.billing_console_access)
>>> False

account_manager.iam.billing_console_access = True
print(account_manager.iam.billing_console_access)
>>> True

# Interface with MFA actions
# Create a virtual MFA
# Warning! Setting an MFA will require re instantiation of the account manager with the new seed
# before more actions can be performed on the account.
# Also due to eventual consistency there might be some time required between setting the MFA and
# being able to use it in which case there might be authentication errors in between if actions are
# performed in sequence. The time is usually less that half a minute.
seed = account_manager.mfa.create_virtual_device() # default name is "root-account-mfa-device"
                                                   # can be overridden by passing a name variable
# !! Save the seed somewhere super safe

# Get the current virtual MFA
device = account_manager.mfa.get_virtual_device()
print(device.serial_number)
arn:aws:iam::ACCOUNTID:mfa/root-account-mfa-device

# Delete a virtual MFA
account_manager.mfa.delete_virtual_device(device.serial_number)


# Update info and terminate account

# Update name of account
account_manager.update_account_name('NEW_NAME_TO_SET')

# Update email of the account
# Due to eventual consistency there might be some time required between changing the email and
# being able to use it in which case there might be authentication errors in between if actions are
# performed in sequence. The time is usually less that half a minute.
account_manager.update_account_email('NEW_EMAIL_TO_SET')

# Terminate an account
account_manager.terminate_account()

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Submit Feedback

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

Get Started!

Ready to contribute? Here’s how to set up awsapilib for local development. Using of pipenv is highly recommended.

1. Clone your fork locally:

   $ git clone https://github.com/schubergphilis/awsapilib
   

2. Install your local copy into a virtualenv. Assuming you have pipenv installed, this is how you set up your clone for local development:

   $ cd awsapilib/
   $ pipenv install --ignore-pipfile
   

3. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally. Do your development while using the CI capabilities and making sure the code passes lint, test, build and document stages.

4. Commit your changes and push your branch to the server:

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

5. Submit a merge request

awsapilib

awsapilib package

Subpackages

awsapilib.authentication package

Submodules

awsapilib.authentication.authentication module

Main code for authentication.

class awsapilib.authentication.authentication.Authenticator(arn, session_duration=3600, region=None)

Bases: BaseAuthenticator

Interfaces with aws authentication mechanisms, providing pre signed urls, or authenticated sessions.

property assumed_role_credentials

Valid credentials for an assumed session.

Returns:

A properly structured dictionary of an assumed session credentials.

Return type:

credentials (dict)

get_billing_authenticated_session()

Authenticates to billing and returns an authenticated session.

Returns:

An authenticated session with headers and cookies set.

Return type:

session (requests.Session)

get_cloudformation_authenticated_session()

Authenticates to cloudformation and returns an authenticated session.

Returns:

An authenticated session with headers and cookies set.

Return type:

session (requests.Session)

get_signed_url(domain='Example.com', destination=None)

Returns a pre signed url that is authenticated.

Parameters:

• domain (str) – The domain to request the session as.

• destination (str) – The service to redirect to after successful redirection.

Returns:

An authenticated pre signed url.

Return type:

url (str)

get_sso_authenticated_session()

Authenticates to Single Sign On and returns an authenticated session.

Returns:

An authenticated session with headers and cookies set.

Return type:

session (requests.Session)

property session_credentials

Valid credentials for a session.

Returns:

A properly structured dictionary of session credentials.

Return type:

credentials (dict)

class awsapilib.authentication.authentication.BaseAuthenticator(region=None)

Bases: LoggerMixin

Interfaces with aws authentication mechanisms, providing pre signed urls, or authenticated sessions.

class awsapilib.authentication.authentication.CsrfTokenData(entity_type: str, attributes: dict, attribute_value: str, headers_name: str)

Bases: object

Object modeling the data required for csrf token filtering.

attribute_value: str

attributes: dict

entity_type: str

headers_name: str

class awsapilib.authentication.authentication.Domains(region: str, root: str = 'aws.amazon.com', sign_in: str = 'signin.aws.amazon.com', console: str = 'console.aws.amazon.com')

Bases: object

Dataclass holding the domains required for authenticating.

console: str = 'console.aws.amazon.com'

region: str

property regional_console

The domain of the regional console.

Returns:

The regional console domain.

Return type:

regional_console (str)

root: str = 'aws.amazon.com'

sign_in: str = 'signin.aws.amazon.com'

class awsapilib.authentication.authentication.FilterCookie(name: str, domain: str = '', exact_match: bool = False)

Bases: object

Object modeling a cookie for filtering.

domain: str = ''

exact_match: bool = False

name: str

class awsapilib.authentication.authentication.LoggerMixin

Bases: object

Logger.

property logger

Exposes the logger to be used by objects using the Mixin.

Returns:

The properly named logger.

Return type:

logger (logger)

class awsapilib.authentication.authentication.Urls(region: str, scheme: str = 'https://', root_domain: str = 'aws.amazon.com', root: str = 'https://aws.amazon.com', sign_in: str = 'https://signin.aws.amazon.com', console: str = 'https://console.aws.amazon.com', console_home: str = 'https://console.aws.amazon.com/console/home', billing_home: str = 'https://console.aws.amazon.com/billing/home', billing_rest: str = 'https://console.aws.amazon.com/billing/rest', iam_home: str = 'https://console.aws.amazon.com/iam/home', iam_api: str = 'https://console.aws.amazon.com/iam/api', federation: str = 'https://signin.aws.amazon.com/federation')

Bases: object

Dataclass holding the urls required for authenticating.

billing_home: str = 'https://console.aws.amazon.com/billing/home'

billing_rest: str = 'https://console.aws.amazon.com/billing/rest'

console: str = 'https://console.aws.amazon.com'

console_home: str = 'https://console.aws.amazon.com/console/home'

federation: str = 'https://signin.aws.amazon.com/federation'

property global_billing_home

The url of the global billing console.

Returns:

The url of the global billing console.

Return type:

global_billing (str)

property global_iam_home

The url of the global IAM console.

Returns:

The url of the global IAM console.

Return type:

global_iam_home (str)

iam_api: str = 'https://console.aws.amazon.com/iam/api'

iam_home: str = 'https://console.aws.amazon.com/iam/home'

region: str

property regional_console

The url of the regional console.

Returns:

The regional console url.

Return type:

regional_console (str)

property regional_console_home

The url of the regional console home page.

Returns:

The regional console home page url.

Return type:

regional_console (str)

property regional_control_tower

The url of the regional control tower service.

Returns:

The regional control tower on url.

Return type:

regional_control_tower (str)

property regional_relay_state

The regional relay state url.

Returns:

The regional relay state url.

Return type:

relay_state (str)

property regional_single_sign_on

The url of the regional single sign on.

Returns:

The regional single sign on url.

Return type:

regional_single_sign_on (str)

root: str = 'https://aws.amazon.com'

root_domain: str = 'aws.amazon.com'

scheme: str = 'https://'

sign_in: str = 'https://signin.aws.amazon.com'

awsapilib.authentication.authenticationexceptions module

Custom exception code for authentication.

exception awsapilib.authentication.authenticationexceptions.ExpiredCredentials

Bases: Exception

Credentials used to assume the role has expired.

exception awsapilib.authentication.authenticationexceptions.InvalidCredentials

Bases: Exception

No credentials or the credentials provided are not correct.

exception awsapilib.authentication.authenticationexceptions.NoSigninTokenReceived

Bases: Exception

No Signing token was received.

awsapilib.authentication.utils module

Main code for utils.

class awsapilib.authentication.utils.HarParser(har_file)

Bases: object

Parses a provided har file.

get_communication_for_billing()

Returns a text of the communication of a valid login to billing.

Returns:

Returns a text of the communication of a valid login to billing.

Return type:

text (str)

get_communication_for_cloudformation()

Returns a text of the communication of a valid login to cloud formation service.

Returns:

Returns a text of the communication of a valid login to cloud formation service.

Return type:

text (str)

get_communication_for_console()

Returns a text of the communication of a valid login to console.

Returns:

Returns a text of the communication of a valid login to console.

Return type:

text (str)

get_communication_for_control_tower()

Returns a text of the communication of a valid login to control tower.

Returns:

Returns a text of the communication of a valid login to control tower.

Return type:

text (str)

get_communication_for_iam()

Returns a text of the communication of a valid login to iam service.

Returns:

Returns a text of the communication of a valid login to iam service.

Return type:

text (str)

get_communication_for_sso()

Returns a text of the communication of a valid login to single sign on.

Returns:

Returns a text of the communication of a valid login to single sign on.

Return type:

text (str)

render_communication_for_billing()

Prints a text of the communication of a valid login to billing.

Returns:

None

render_communication_for_cloudformation()

Prints a text of the communication of a valid login to cloud formation service.

Returns:

None

render_communication_for_console()

Prints a text of the communication of a valid login to console.

Returns:

None

render_communication_for_control_tower()

Prints a text of the communication of a valid login to control tower.

Returns:

None

render_communication_for_iam()

Prints a text of the communication of a valid login iam service.

Returns:

None

render_communication_for_sso()

Prints a text of the communication of a valid login to single sign on.

Returns:

None

Module contents

awsauthenticationlib package.

Import all parts from awsauthenticationlib here

awsapilib.billing package

Submodules

awsapilib.billing.billing module

Main code for billing.

class awsapilib.billing.billing.Billing(arn, region=None)

Bases: LoggerMixin

Models Control Tower by wrapping around service catalog.

property account_id

Account id.

property currency

Currency settings.

Returns:

The currency set.

Return type:

currency (str)

property disabled_region_states

Disabled region states.

property enabled_region_states

Enabled region states.

property iam_access

IAM access to billing setting.

property market_place_id

Marker place id of account.

property payment_cards

Payment cards.

property preferences

Preferences settings.

Returns:

The preferences settings object.

Return type:

preferences (Preferences)

property sor_id

Sor id.

property tax

Tax settings.

Returns:

The tax settings object.

Return type:

tax (Tax)

class awsapilib.billing.billing.PaymentCard(billing, data)

Bases: LoggerMixin

Models a payment card.

property address_id

Address id.

property address_line_1

First line of the address settings.

property address_line_2

Second line of the address settings.

property city

City.

property company

Company.

property country_code

Country code.

property email_address_list

Email address list.

property full_name

Full name.

property payment_instrument_arn

Payment instrument arn.

property phone_number

Phone number.

property postal_code

Postal code.

property state

State.

class awsapilib.billing.billing.Preferences(billing)

Bases: LoggerMixin

Models the preferences of the billing console.

property credit_sharing

The setting of the credit sharing.

Returns:

True if set, False otherwise.

Return type:

setting (bool)

property pdf_invoice_by_mail

The setting of the pdf invoice by email.

Returns:

True if set, False otherwise.

Return type:

setting (bool)

class awsapilib.billing.billing.Tax(billing)

Bases: LoggerMixin

Models the tax settings of the billing console.

property available_country_codes_eu

The available country codes of the tax settings for eu.

Returns:

Available country codes

Return type:

codes (list)

property inheritance

The inheritance settings of the billing preferences.

Returns:

True if set, False otherwise.

Return type:

setting (bool)

set_information(address, city, postal_code, legal_name, vat_number, country_code, state=None)

The inheritance settings setter of the billing preferences.

Returns:

None

awsapilib.billing.billingexceptions module

Custom exception code for billing.

exception awsapilib.billing.billingexceptions.IAMAccessDenied

Bases: Exception

IAM User and Role Access to Billing Information on the account console is not set.

exception awsapilib.billing.billingexceptions.InvalidCountryCode

Bases: Exception

The country code provided is not valid.

exception awsapilib.billing.billingexceptions.InvalidCurrency

Bases: Exception

The currency provided is not a valid value.

exception awsapilib.billing.billingexceptions.NonEditableSetting

Bases: Exception

The setting is not editable, or time disabled.

exception awsapilib.billing.billingexceptions.ServerError

Bases: Exception

The response was not successful.

Module contents

billing package.

Import all parts from billing here

awsapilib.captcha package

Submodules

awsapilib.captcha.captcha module

Main code for captcha.

class awsapilib.captcha.captcha.Captcha2(api_token)

Bases: Solver

2captcha solver.

solve(url)

Presents a captcha image url and returns the captcha.

Parameters:

url (str) – The url to provide that should have the captcha image.

Returns:

The captcha.

Return type:

guess (str)

class awsapilib.captcha.captcha.Iterm

Bases: Solver

Interactive captcha solver for iTerm terminals.

solve(url)

Presents a captcha image and returns the user’s guess for the captcha.

Parameters:

url (str) – The url to provide that should have the captcha image.

Returns:

The guess of the user for the captcha.

Return type:

guess (str)

class awsapilib.captcha.captcha.Solver

Bases: ABC, LoggerMixin

Interface for a Solver object.

abstract solve(url)

Solves a url.

class awsapilib.captcha.captcha.Terminal

Bases: Solver

Interactive captcha solver for standard terminals.

solve(url)

Presents a captcha image url and returns the user’s guess for the captcha.

Parameters:

url (str) – The url to provide that should have the captcha image.

Returns:

The guess of the user for the captcha.

Return type:

guess (str)

awsapilib.captcha.captchaexceptions module

Custom exception code for captcha.

exception awsapilib.captcha.captchaexceptions.CaptchaError

Bases: Exception

There was an error retrieving the captcha.

exception awsapilib.captcha.captchaexceptions.InvalidOrNoBalanceApiToken

Bases: Exception

The api token provided either does not provide access or there is no money on the token to be used.

exception awsapilib.captcha.captchaexceptions.UnsupportedTerminal

Bases: Exception

The terminal executing under is not supported.

Module contents

captcha package.

Import all parts from captcha here

awsapilib.cloudformation package

Submodules

awsapilib.cloudformation.cloudformation module

Main code for billing.

class awsapilib.cloudformation.cloudformation.Cloudformation(arn, region=None)

Bases: LoggerMixin

Models Control Tower by wrapping around service catalog.

property stacksets

Exposes the stacksets settings.

class awsapilib.cloudformation.cloudformation.StackSet(cloudformation_instance)

Bases: object

Models the stacksets settings and implements the interaction with them.

disable_organizations_trusted_access()

Disables organization trusted access.

Returns:

True on success

enable_organizations_trusted_access()

Enables organization trusted access.

Returns:

True on success

property organizations_trusted_access

Setting about the organizations trusted access.

awsapilib.cloudformation.cloudformationexceptions module

Custom exception code for cloudformation.

exception awsapilib.cloudformation.cloudformationexceptions.ServerError

Bases: Exception

The response was not successful.

Module contents

billing package.

Import all parts from billing here

awsapilib.console package

Submodules

awsapilib.console.console module

Main code for console.

class awsapilib.console.console.AccountManager(email, password, region, mfa_serial=None, solver=<class 'awsapilib.captcha.captcha.Terminal'>)

Bases: BaseConsoleInterface

Models basic communication with the server for account and password management.

property account_id

IAM.

property iam

IAM.

property mfa

Retrieves an MFA manager.

Returns:

The mfa manager object

Return type:

mfa_manager (MfaManager)

terminate_account()

Terminates the account matching the info provided.

Returns:

True on success, False otherwise.

update_account_email(new_account_email)

Updates the name of an account to the new one provided.

Parameters:

new_account_email – The new account name.

Returns:

True on success.

Raises:

ServerError, UnableToUpdateAccount – On Failure with the corresponding message from the backend service.

update_account_name(new_account_name)

Updates the email of an account to the new one provided.

Parameters:

new_account_name – The new account email.

Returns:

True on success.

Raises:

ServerError, UnableToUpdateAccount – On Failure with the corresponding message from the backend service.

class awsapilib.console.console.BaseConsoleInterface(solver=<class 'awsapilib.captcha.captcha.Terminal'>)

Bases: LoggerMixin

Manages accounts password filecycles and can provide a root console session.

get_mfa_type(email)

Gets the MFA type of the account.

Parameters:

email – The email of the account to check for MFA settings.

Returns:

The type of MFA set (only “SW” currently supported) None if no MFA is set.

class awsapilib.console.console.Captcha(url: str, token: str, obfuscation_token: str)

Bases: object

Models a Captcha.

obfuscation_token: str

token: str

url: str

class awsapilib.console.console.IamAccess(billing_session)

Bases: LoggerMixin

Models the iam access settings and implements the interaction with them.

property billing_console_access

Billing console access setting.

class awsapilib.console.console.MFA(_data: dict)

Bases: object

Models the MFA device.

property enabled_date

Timestamp of enabled day.

property id

Id.

property serial_number

The serial number of the device.

property user_name

The user name set on the device.

class awsapilib.console.console.MfaManager(iam_session)

Bases: LoggerMixin

Models interaction with the api for mfa management.

create_virtual_device(name='root-account-mfa-device')

Creates a virtual MFA device with the provided name.

Parameters:

name – The name of the virtual MFA device, defaults to “root-account-mfa-device”

Returns:

The secret seed of the virtual MFA device. This needs to be saved in a safe place!!

Return type:

seed (str)

Raises:

VirtualMFADeviceExists, UnableToCreateVirtualMFA, UnableToEnableVirtualMFA on respective failures. –

delete_virtual_device(serial_number)

Deletes a virtual MFA with the provided serial number.

Parameters:

serial_number – The serial number of the virtual MFA device to delete.

Returns:

True on success

Raises:

UnableToDisableVirtualMFA on failure. –

get_virtual_device()

Retrieves the virtual MFA device if set.

Returns:

The set virtual MFA device if any else, None.

Return type:

mfa_device (MFA)

class awsapilib.console.console.Oidc(client_id: str, code_challenge: str, code_challenge_method: str, redirect_url: str)

Bases: object

Models an OIDC response.

client_id: str

code_challenge: str

code_challenge_method: str

redirect_url: str

class awsapilib.console.console.PasswordManager(solver=<class 'awsapilib.captcha.captcha.Terminal'>)

Bases: BaseConsoleInterface

Models interaction for account password reset.

request_password_reset(email)

Requests a password reset for an account by it’s email.

Parameters:

email – The email of the account to request the password reset.

Returns:

True on success, False otherwise.

Raises:

UnableToRequestResetPassword if unsuccessful –

reset_password(reset_url, password)

Resets password of an aws account.

Parameters:

• reset_url – The reset url provided by aws thought the reset password workflow.

• password – The new password to set to the account.

Returns:

True on success, False otherwise.

Raises:

UnableToResetPassword on failure –

class awsapilib.console.console.RootAuthenticator(session, region)

Bases: BaseAuthenticator

Interacts with the console to retrieve console and billing page sessions.

get_billing_root_session(redirect_url, unfiltered_session=False)

Retreives a billing session, filtered with specific cookies or not depending on the usage.

Parameters:

• redirect_url (str) – The redirect url provided to initiate the authentication flow after the captcha.

• unfiltered_session (bool) – Returns a full session if unfiltered, or a filtered session with xsrf token if set to True. Defaults to False.

Returns:

A valid session.

Return type:

session (Session)

get_iam_root_session(redirect_url)

Retrieves an iam console session, filtered with specific cookies or not depending on the usage.

Parameters:

redirect_url (str) – The redirect url provided to initiate the authentication flow after the captcha.

Returns:

A valid session.

Return type:

session (Session)

class awsapilib.console.console.VirtualMFADevice(seed: str, serial: str)

Bases: object

Models the active MFA device.

seed: str

serial: str

awsapilib.console.consoleexceptions module

Custom exception code for console.

exception awsapilib.console.consoleexceptions.InvalidAuthentication

Bases: Exception

The authentication did not succeed.

exception awsapilib.console.consoleexceptions.NoMFAProvided

Bases: Exception

The account is MFA provided but no MFA serial was provided.

exception awsapilib.console.consoleexceptions.NotSolverInstance

Bases: Exception

The object provided was not of Solver type.

exception awsapilib.console.consoleexceptions.ServerError

Bases: Exception

Unknown server error occured.

exception awsapilib.console.consoleexceptions.UnableToCreateVirtualMFA

Bases: Exception

The attempt to create a virtual mfa failed.

exception awsapilib.console.consoleexceptions.UnableToDisableVirtualMFA

Bases: Exception

The attempt to disable a virtual mfa failed.

exception awsapilib.console.consoleexceptions.UnableToEnableVirtualMFA

Bases: Exception

The attempt to create a virtual mfa failed.

exception awsapilib.console.consoleexceptions.UnableToGetVirtualMFA

Bases: Exception

The attempt to list a virtual mfa failed.

exception awsapilib.console.consoleexceptions.UnableToQueryMFA

Bases: Exception

Unable to query the account MFA info.

exception awsapilib.console.consoleexceptions.UnableToRequestResetPassword

Bases: Exception

The request to reset password did not work.

exception awsapilib.console.consoleexceptions.UnableToResetPassword

Bases: Exception

The reset password request did not work.

exception awsapilib.console.consoleexceptions.UnableToResolveAccount

Bases: Exception

Unable to resolve the account type.

exception awsapilib.console.consoleexceptions.UnableToUpdateAccount

Bases: Exception

Unable to update the account info.

exception awsapilib.console.consoleexceptions.UnsupportedMFA

Bases: Exception

The MFA enabled is not supported.

exception awsapilib.console.consoleexceptions.VirtualMFADeviceExists

Bases: Exception

The device already exists.

Module contents

console package.

Import all parts from console here

awsapilib.controltower package

Subpackages

awsapilib.controltower.resources package

Submodules

awsapilib.controltower.resources.configuration module

configuration module.

Import all parts from configuration here

awsapilib.controltower.resources.resources module

resources module.

Import all parts from resources here

class awsapilib.controltower.resources.resources.AccountFactory(service_catalog_client, data)

Bases: object

Models the account factory data of service catalog.

class awsapilib.controltower.resources.resources.ControlTowerAccount(control_tower, data, info_polling_interval=30)

Bases: LoggerMixin

Models the account data.

property arn

Arn.

attach_service_control_policy(name)

Attaches a Service Control Policy to the account.

Parameters:

name (str) – The name of the SCP to attach

Returns:

True on success, False otherwise.

Return type:

result (bool)

property created_time

Created Time.

delete(suspended_ou_name=None)

Delete.

detach_service_control_policy(name)

Detaches a Service Control Policy from the account.

Parameters:

name (str) – The name of the SCP to detach

Returns:

True on success, False otherwise.

Return type:

result (bool)

property email

Email.

property guardrail_compliance_status

Retrieves the guardrail compliancy status for the account.

Returns:

COMPLIANT|NON COMPLIANT

Return type:

status (str)

property has_available_update: bool

If the account is behind the landing zone version.

property id

Id.

property idempotency_token

Idempotency Token.

property landing_zone_version

Landing zone version.

property last_record_id

Last Record ID.

property name

Name.

property organizational_unit

Organizational Unit.

property owner

Owner.

property physical_id

Physical ID.

property provision_state

Provision state.

property provisioning_artifact_id

Provisioning artifact ID.

property service_catalog_id

Service Catalog ID.

property service_catalog_product_id

Service catalog product ID.

property service_catalog_status

Service catalog status.

property service_catalog_tags

Service catalog tags.

property service_catalog_type

Service catalog type.

property service_catalog_user_arn

Service catalog user arn.

property sso_user_email

SSO user email.

property sso_user_portal

SSO user portal.

property stack_arn

Stack Arn.

property status

Status.

update()

Updates the account in service catalog.

Returns:

True if the call succeeded False otherwise

property user_arn_session

User arn session.

class awsapilib.controltower.resources.resources.ControlTowerOU(control_tower, data)

Bases: LoggerMixin

Model the data of a Control Tower managed OU.

property child_ous

The list child OUs for this ou.

Returns:

List of Child OUs

Return type:

response (list)

property create_date

The date the ou was created in timestamp.

delete()

Deletes the ou.

Returns:

True on success, False otherwise.

Return type:

response (bool)

property id

OU ID.

property name

The name of the OU.

property parent_ou_id

The id of the parent OU.

property parent_ou_name

The name of the parent OU.

property status

The status of the OU.

property type

The type of the OU.

class awsapilib.controltower.resources.resources.CoreAccount(control_tower, account_label, data)

Bases: object

Models the core landing zone account data.

property core_resource_mappings

Core resource mappings.

property email

Email.

property id

Id.

property label

Account label.

property stack_set_arn

Stack set arn.

class awsapilib.controltower.resources.resources.GuardRail(control_tower, data)

Bases: LoggerMixin

Models the guard rail data.

property behavior

Behavior.

property category

Category.

property compliancy_status

Compliancy status.

property description

Description.

property display_name

DisplayName.

property name

Name.

property provider

Provider.

property regional_preference

Regional preference.

property type

Type.

class awsapilib.controltower.resources.resources.OrganizationsOU(data)

Bases: object

Model the data of an Organizations managed OU.

property arn

The arn of the OU.

property id

The id of the OU.

property name

The name of the OU.

property parent_ou_arn

The arn of the parent.

property parent_ou_id

The id of the parent.

property parent_ou_name

The name of the parent.

class awsapilib.controltower.resources.resources.ResultOU(data)

Bases: object

Model the data of an child OU described by the api.

property create_date

The timestamp of the creation.

property id

The id of the OU.

property name

The name of the OU.

property parent_ou_id

The id of the parent.

property status

The status of the OU.

class awsapilib.controltower.resources.resources.ServiceControlPolicy(data)

Bases: object

Models the account factory data of service catalog.

property arn

Arn.

property aws_managed

Aws Managed.

property description

Description.

property id

Id.

property name

Name.

property type

Type.

Module contents

configuration module.

Import all parts from configuration here

Submodules

awsapilib.controltower.controltower module

Main code for controltower.

class awsapilib.controltower.controltower.ControlTower(arn, settling_time=90, region=None)

Bases: LoggerMixin

Models Control Tower by wrapping around service catalog.

property accounts

The accounts under control tower.

Returns:

A list of account objects under control tower’s control.

Return type:

accounts (Account)

property active_artifact_id: str

Contains the id of the active artifact.

Returns:

str with the artifact id or an empty string

api_content_type = 'application/x-amz-json-1.1'

api_user_agent = 'aws-sdk-js/2.528.0 promise'

property baseline_update_available

Baseline update available.

property busy

Busy.

property catastrophic_drift

List of catastrophic drift.

core_account_types = ['PRIMARY', 'LOGGING', 'SECURITY']

property core_accounts

The core accounts of the landing zone.

Returns:

A list of the primary, logging and security account.

Return type:

core_accounts (list)

create_account(account_name: str, account_email: str, organizational_unit: str, parent_hierarchy: list = None, product_name: str = None, sso_first_name: str = None, sso_last_name: str = None, sso_user_email: str = None, force_parent_hierarchy_creation=False) → bool

Creates a Control Tower managed account.

Parameters:

• account_name (str) – The name of the account.

• account_email (str) – The email of the account.

• organizational_unit (str) – The organizational unit that the account should be under.

• parent_hierarchy (list) – The hierarchy under where the OU needs to be placed. Defaults to Root.

• product_name (str) – The product name, if nothing is provided it uses the account name.

• sso_first_name (str) – The first name of the SSO user, defaults to “Control”

• sso_last_name (str) – The last name of the SSO user, defaults to “Tower”

• sso_user_email (str) – The email of the sso, if nothing is provided it uses the account email.

• force_parent_hierarchy_creation (bool) – Forces the creation of missing OUs in the provided hierarchy.

Returns:

True on success, False otherwise.

Return type:

result (bool)

Raises:

• NonExistentOU – If the parent hierarchy provided does not exist and force is not provided as a flag.

• InvalidParentHierarchy – If the parent hierarchy provided is invalid and force is not provided as a flag.

• EmailInUse – If email provided is already used in AWS.

create_organizational_unit(name: str, parent_hierarchy=None, force_create=False) → bool

Creates a Control Tower managed organizational unit.

Parameters:

• name (str) – The name of the OU to create.

• parent_hierarchy (list) – The list of the parent hierarchy path.

• force_create (bool) – Forces the creation of the hierarchy if parents are missing.

Returns:

True if successful, False otherwise.

Return type:

result (bool)

Raises:

• InvalidParentHierarchy – If the hierarchy provided is longer that 5 levels.

• NonExistentOU – If there is an OU missing in the hierarchy and force_create is not set.

decommission() → bool

Decommissions a landing zone.

The api call does not seem to be enough and although the resources are decommissioned like with the proper process, control tower responds with a delete failed on the api, so it seems that aws needs to perform actions on their end for the decommissioning to be successful.

Returns:

True if the process starts successfully, False otherwise.

Return type:

response (bool)

delete_organizational_unit(name: str, parent_hierarchy=None) → bool

Deletes a Control Tower managed organizational unit.

Parameters:

• name (str) – The name of the OU to delete.

• parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

True if successful, False otherwise.

Return type:

result (bool)

Raises:

NonExistentOU – If an OU does not exist in the hierarchy.

deploy(logging_account_email: str, security_account_email: str, logging_account_name: str = 'Log Archive', security_account_name: str = 'Audit', core_ou_name: str = 'Security', custom_ou_name: str = 'Sandbox', regions: Optional[list] = None, retries: int = 10, wait: int = 1) → bool

Deploys control tower.

Returns:

True on success, False on failure.

Return type:

bool

property deploying_messages

Deploying messages.

property drift_messages

Drift messages.

property enabled_guard_rails

Enabled guard rails.

get_account_by_arn(arn)

Retrieves an account by arn.

Returns:

An account object that matches the arn or None.

Return type:

account (Account)

get_account_by_email(email)

Retrieves an account by email.

Returns:

An account object that matches the email or None.

Return type:

account (Account)

get_account_by_id(id_)

Retrieves an account by id.

Returns:

An account object that matches the id or None.

Return type:

account (Account)

get_account_by_name(name)

Retrieves an account by name.

Returns:

An account object that matches the name or None.

Return type:

account (Account)

get_accounts_with_available_updates()

Retrieves the accounts that have available updates from control tower.

Returns:

A list of account objects under control tower’s control with available updates.

Return type:

accounts (Account)

get_available_accounts()

Retrieves the available accounts from control tower.

Returns:

A list of available account objects under control tower’s control.

Return type:

accounts (Account)

static get_available_regions()

The regions that control tower can be active in.

Returns:

A list of strings of the regions that control tower can be active in.

Return type:

regions (list)

get_changing_accounts()

Retrieves the under change accounts from control tower.

Returns:

A list of under change account objects under control tower’s control.

Return type:

accounts (Account)

get_erroring_accounts()

Retrieves the erroring accounts from control tower.

Returns:

A list of erroring account objects under control tower’s control.

Return type:

accounts (Account)

get_organizational_unit_by_id(id_)

Gets a Control Tower managed Organizational Unit by id.

Parameters:

id (str) – The id of the organizational unit to retrieve.

Returns:

A OU object on success, None otherwise.

Return type:

result (ControlTowerOU)

get_organizational_unit_by_name(name, parent_hierarchy=None)

Gets a Control Tower managed Organizational Unit by name.

Parameters:

• name (str) – The name of the organizational unit to retrieve.

• parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

A OU object on success, None otherwise.

Return type:

result (ControlTowerOU)

Raises:

NonExistentOU – If an OU does not exist in the hierarchy.

get_organizations_ou_by_arn(arn)

Gets an Organizations managed Organizational Unit by arn.

Parameters:

arn (str) – The arn of the organizational unit to retrieve.

Returns:

A OU object on success, None otherwise.

Return type:

result (OrganizationsOU)

get_organizations_ou_by_id(id_)

Gets an Organizations managed Organizational Unit by id.

Parameters:

id (str) – The id of the organizational unit to retrieve.

Returns:

A OU object on success, None otherwise.

Return type:

result (OrganizationsOU)

get_organizations_ou_by_name(name, parent_hierarchy=None)

Gets an Organizations managed Organizational Unit by name.

Parameters:

• name (str) – The name of the organizational unit to retrieve.

• parent_hierarchy (list) – A list of names of the hierarchy for a parent starting with ‘Root’

Returns:

A OU object on success, None otherwise.

Return type:

result (OrganizationsOU)

get_service_control_policy_by_name(name)

Retrieves a service control policy by name.

Parameters:

name (str) – The name of the SCP to retrieve

Returns:

The scp if a match is found else None.

Return type:

scp (ServiceControlPolicy)

get_updated_accounts()

Retrieves the accounts that have no available updates from control tower.

Returns:

A list of account objects under control tower’s control with no available updates.

Return type:

accounts (Account)

property governed_regions

Governed regions.

property guard_rails

Guard rails.

property guard_rails_violations

List guard rails violations.

property guardrail_update_available

Guardrail update available.

property is_deployed

The deployment status of control tower.

is_email_used(email)

Check email for availability to be used or if it is already in use.

property landing_zone_update_available

Landing Zone update available.

property landing_zone_version

Landing zone version.

property not_governed_regions

Not governed regions.

property organizational_units

The organizational units under control tower.

Returns:

A list of organizational units objects under control tower’s control.

Return type:

organizational_units (OrganizationalUnit)

property organizations_ous

The organizational units under Organizations.

Returns:

A list of organizational units objects under Organizations.

Return type:

organizational_units (OrganizationsOU)

property percentage_complete

Percentage complete.

property region

Region.

property region_metadata_list

Region metadata list.

register_organizations_ou(name: str, parent_hierarchy=None, force: bool = False) → bool

Registers an Organizations OU under control tower.

Parameters:

• name (str) – The name of the Organizations OU to register to Control Tower.

• force (bool) – Forces re-registering if the OU is already controlled by Control Tower

Returns:

True if successful, False otherwise.

Return type:

result (bool)

repair()

Repairs control tower.

Returns:

True on success, False on failure.

Return type:

bool

property root_ou

The root ou of control tower.

Returns:

The root ou object.

Return type:

root_ou (ControlTowerOU)

property service_control_policies

The service control policies under organization.

Returns:

A list of SCPs under the organization.

Return type:

service_control_policies (list)

property service_landing_zone_version

Service landing zone version.

property status

Status.

supported_targets = ['ListManagedOrganizationalUnits', 'ManageOrganizationalUnit', 'DeregisterOrganizationalUnit', 'ListManagedAccounts', 'DescribeManagedOrganizationalUnit', 'ListGuardrailsForTarget', 'GetAvailableUpdates', 'DescribeCoreService', 'GetAccountInfo', 'ListEnabledGuardrails', 'ListGuardrails', 'ListOrganizationalUnitsForParent', 'ListDriftDetails', 'GetLandingZoneStatus', 'SetupLandingZone', 'GetHomeRegion', 'ListGuardrailViolations', 'GetCatastrophicDrift', 'GetGuardrailComplianceStatus', 'DescribeAccountFactoryConfig', 'PerformPreLaunchChecks', 'DeleteLandingZone']

update()

Updates the control tower to the next available version.

Returns:

True on success, False on failure.

Return type:

bool

property user_landing_zone_version

User landing zone version.

validate_availability()

Validation decorator.

awsapilib.controltower.controltowerexceptions module

Custom exception code for controltower.

exception awsapilib.controltower.controltowerexceptions.ControlTowerBusy

Bases: Exception

The control tower is already executing some action.

exception awsapilib.controltower.controltowerexceptions.ControlTowerNotDeployed

Bases: Exception

The control tower is deployed at all.

exception awsapilib.controltower.controltowerexceptions.EmailCheckFailed

Bases: Exception

Checking of the email was not possible.

exception awsapilib.controltower.controltowerexceptions.EmailInUse

Bases: Exception

The email provided is already in use and cannot be used to deploy an account.

exception awsapilib.controltower.controltowerexceptions.InvalidParentHierarchy

Bases: Exception

The parent hierarchy provided is not valid.

exception awsapilib.controltower.controltowerexceptions.NoActiveArtifactRetrieved

Bases: Exception

Could not retrieve an active artifact.

exception awsapilib.controltower.controltowerexceptions.NoServiceCatalogAccess

Bases: Exception

There is no access to service catalog.

exception awsapilib.controltower.controltowerexceptions.NoSuspendedOU

Bases: Exception

The suspended ou has not been created.

exception awsapilib.controltower.controltowerexceptions.NonExistentOU

Bases: Exception

The OU name provided does not exist in Control Tower.

exception awsapilib.controltower.controltowerexceptions.NonExistentSCP

Bases: Exception

The SCP requested does not exist.

exception awsapilib.controltower.controltowerexceptions.OUCreating

Bases: Exception

The organizational unit is still under creation and cannot be used.

exception awsapilib.controltower.controltowerexceptions.PreDeployValidationFailed

Bases: Exception

The pre deployment validation failed.

exception awsapilib.controltower.controltowerexceptions.RoleCreationFailure

Bases: Exception

Unable to create the required roles for the deployment of control tower, manual clean up is required.

exception awsapilib.controltower.controltowerexceptions.ServiceCallFailed

Bases: Exception

The call to the service has failed.

exception awsapilib.controltower.controltowerexceptions.UnavailableRegion

Bases: Exception

The region or regions provided to control tower to deploy in are not available.

exception awsapilib.controltower.controltowerexceptions.UnsupportedTarget

Bases: Exception

The target call is not supported by the current implementation.

Module contents

controltower module.

Import all parts from controltower here

awsapilib.sso package

Subpackages

awsapilib.sso.entities package

Submodules

awsapilib.sso.entities.entities module

Main code for entities.

class awsapilib.sso.entities.entities.Account(sso_instance, data)

Bases: Entity

Models the Account object of AWS SSO.

property arn

The arn of the application.

Returns:

The arn of the application

Return type:

arn (str)

property associated_profiles

The associated profiles with the Account.

Returns:

The profiles associated with the Account

Return type:

associated_profiles (list)

property email

The name of the application.

Returns:

The name of the application

Return type:

email (str)

property id

The id of the application.

Returns:

The id of the application

Return type:

id (str)

property instance_id

The instance id of the Account.

Returns:

The instance id of the account

Return type:

instance_id (str)

property name

The name of the application.

Returns:

The name of the application

Return type:

name (str)

provision_saml_provider()

Creates the SAMl provider.

Returns:

The arn of the SAMl provider

Return type:

arn (str)

property status

The status of the application.

Returns:

The status of the application

Return type:

status (str)

property url

Url for the account.

Returns:

The url of the account

Return type:

url (str)

class awsapilib.sso.entities.entities.Entity(sso_instance, data)

Bases: LoggerMixin

The core entity.

class awsapilib.sso.entities.entities.Group(sso_instance, data)

Bases: Entity

Models the group object of AWS SSO.

property description

The description of the group.

Returns:

The description of the group

Return type:

description (str)

property id

The id of the group.

Returns:

The id of the group

Return type:

id (str)

property name

The name of the group.

Returns:

The name of the group

Return type:

name (str)

property users

The users in the group.

Returns:

The users part of the group

Return type:

users (list)

class awsapilib.sso.entities.entities.PermissionSet(sso_instance, data)

Bases: Entity

Models the permission set object of SSO.

assign_custom_policy_to_permission_set(policy_document)

Assign Custom policy to a permission_set.

Parameters:

• permission_set_name – The name of the permission_set .

• policy_document – The policy for the permission_set

Returns:

True or False

Return type:

Bool

property creation_date

The creation date of the permission set.

Returns:

The creation date of the permission set

Return type:

creation_date (str)

delete_custom_policy_from_permission_set()

Assign Custom policy to a permission_set.

Returns:

True or False

Return type:

Bool

property description

The description of the permission set.

Returns:

The description of the permission set

Return type:

description (str)

property id

The id of the permission set.

Returns:

The id of the permission set

Return type:

id (str)

property name

The name of the permission set.

Returns:

The name of the permission set

Return type:

name (str)

property permission_policy

The permission policy of the permission_set.

Returns:

The permission policy of the permission_set

Return type:

permission_policy (dict)

property provisioned_accounts

The provisioned accounts with the permission set.

Returns:

Accounts provisioned with the permission set

Return type:

list

property relay_state

The relay_state of the permission_set.

Returns:

The relayState of the permission_set

Return type:

relay_state (str)

property ttl

The ttl of the permission set.

Returns:

The ttl of the permission set

Return type:

ttl (str)

update(description=' ', relay_state='', ttl='')

The relayState of the permission_set.

Parameters:

• description – Description for the permission set

• relay_state – The relay state for the permission set. https://docs.aws.amazon.com/singlesignon/latest/userguide/howtopermrelaystate.html

• ttl – session duration

Returns:

True or False

Return type:

bool

property url

Url of the permission set.

Returns:

The url of the permission set

Return type:

url (str)

class awsapilib.sso.entities.entities.User(sso_instance, data)

Bases: Entity

Models the user object of SSO.

property created_at

The date and time of the users’s activation.

Returns:

The datetime object of when the user was activated

Return type:

created_at (datetime)

property display_name

The display name of the user.

Returns:

The display name of the user

Return type:

display_name (str)

property emails

The date and time of the users’s last password change.

Returns:

The datetime object of when the user last changed password

Return type:

emails (datetime)

property first_name

The first name of the user.

Returns:

The first name of the user

Return type:

first_name (str)

property groups

The groups associated with the user.

Returns:

The groups associated with the user

Return type:

groups (list)

property id

The manager of the user.

Returns:

The manager of the user

Return type:

id (str)

property last_name

The last name of the user.

Returns:

The last name of the user

Return type:

last_name (str)

property name

The manager of the user.

Returns:

The manager of the user

Return type:

name (str)

property status

The status of the user.

Returns:

The status of the user

Return type:

status (str)

property updated_at

The date and time of the users’s status change.

Returns:

The datetime object of when the user had last changed status

Return type:

updated_at (datetime)

property url

Url for the user.

Returns:

The url for the user

Return type:

url (str)

Module contents

entities package.

Import all parts from entities here

Submodules

awsapilib.sso.sso module

Main code for sso.

class awsapilib.sso.sso.Sso(arn, region=None)

Bases: LoggerMixin

Models AWS SSO.

API_CONTENT_ENCODING = 'amz-1.0'

API_CONTENT_TYPE = 'application/json; charset=UTF-8'

DEFAULT_AWS_REGION = 'eu-west-1'

property accounts

The aws accounts in sso.

Returns:

The accounts configured in SSO

Return type:

accounts (generator)

property api_url

The url of the api for sso.

Returns:

The url of the api for sso.

Return type:

api_url (str)

associate_group_to_account(group_name, account_name, permission_set_name)

Associates a group with an account with proper permissions.

Parameters:

• group_name – The name of the group to be assigned.

• account_name – Name of the account to which the group will be assigned

• permission_set_name – the Permission Set the group will have on the account

Returns:

True or False

Return type:

bool

associate_user_to_account(user_name, account_name, permission_set_name)

Associates an user with an account with proper permissions.

Parameters:

• user_name – The name of the user to be assigned.

• account_name – Name of the account to which the user will be assigned

• permission_set_name – the Permission Set the user will have on the account

Returns:

True or False

Return type:

bool

property aws_region

Aws Console Region.

Returns:

The region of the console.

Return type:

region (str)

create_permission_set(name, description=' ', relay_state=None, ttl='PT2H')

Create a permission_set with a aws defined policy or custom policy.

Parameters:

• name – The name of the permission_set .

• description – Description for the permission set

• relay_state – The relay state for the permission set. https://docs.aws.amazon.com/singlesignon/latest/userguide/howtopermrelaystate.html

• ttl – session duration

Returns:

Permission Set object

Return type:

PermissionSet

delete_permission_set(name)

Delete a permission_set .

Parameters:

name – The name of the permission_set .

Returns:

Status of the deletion

Return type:

Bool

property directory_id

The external/internal directory id configured with aws sso.

Returns:

The id of directory configured in SSO

Return type:

str

disassociate_group_from_account(group_name, account_name, permission_set_name)

Disassociates a group with an account with proper permissions.

Parameters:

• group_name – The name of the group to be assigned.

• account_name – Name of the account to which the group will be assigned

• permission_set_name – the Permission Set the group will have on the account

Returns:

True or False

Return type:

bool

disassociate_user_from_account(user_name, account_name, permission_set_name)

Disassociates an user with an account with proper permissions.

Parameters:

• user_name – The name of the user to be assigned.

• account_name – Name of the account to which the user will be assigned

• permission_set_name – the Permission Set the user will have on the account

Returns:

True or False

Return type:

bool

property endpoint_url

The url of the api endpoint for sso.

Returns:

The url of the api endpoint for sso.

Return type:

endpoint_url (str)

get_account_by_id(account_id)

The account configured in SSO.

Returns:

The Account object

Return type:

account (Account)

get_account_by_name(account_name)

The account configured in SSO.

Returns:

The Account object

Return type:

account (Account)

get_api_payload(content_string, target, method='POST', params=None, path='/', content_type=None, content_encoding=None, x_amz_target='', region=None)

Generates the payload for calling the AWS SSO APIs.

Returns:

Returns a deepcopy object of the payload

Return type:

payload (dict)

get_group_by_id(group_id)

The group configured in SSO.

Returns:

The Group object

Return type:

group (Group)

get_group_by_name(group_name)

The group configured in SSO.

Returns:

The Group object

Return type:

group (Group)

get_permission_set_by_name(permission_set_name)

The permission-set configured in SSO.

Returns:

The PermissionSet object

Return type:

permission_set (PermissionSet)

get_user_by_id(user_id)

The user configured in SSO.

Returns:

The User object

Return type:

user (User)

get_user_by_name(user_name)

The user configured in SSO.

Returns:

The User object

Return type:

user (User)

property groups

The groups configured in SSO.

Returns:

The groups configured in SSO

Return type:

groups (generator)

property permission_sets

The permission_sets configured in SSO.

Returns:

The permission sets configured in SSO

Return type:

permission_sets (generator)

property relay_state

The relay state of the SSO.

Returns:

The relay state of sso.

Return type:

relay_state (str)

property users

The users configured in SSO.

Returns:

The users configured in SSO

Return type:

users (generator)

awsapilib.sso.ssoexceptions module

Custom exception code for sso.

exception awsapilib.sso.ssoexceptions.NoAccount

Bases: Exception

The account does not exist.

exception awsapilib.sso.ssoexceptions.NoGroup

Bases: Exception

The group does not exist.

exception awsapilib.sso.ssoexceptions.NoPermissionSet

Bases: Exception

The permission set does not exist.

exception awsapilib.sso.ssoexceptions.NoProfileID

Bases: Exception

The permission set is not associated with the account.

exception awsapilib.sso.ssoexceptions.NoUser

Bases: Exception

The user does not exist.

exception awsapilib.sso.ssoexceptions.UnsupportedTarget

Bases: Exception

The target call is not supported by the current implementation.

Module contents

sso package.

Import all parts from sso here

Submodules

awsapilib.awsapilib module

Main code for awsapilib.

awsapilib.awsapilibexceptions module

Custom exception code for awsapilib.

Module contents

awsapilib package.

Import all parts from awsapilib here

Credits

Development Lead

• Costas Tyfoxylos <ctyfoxylos@schubergphilis.com>

Contributors

• Sjoerd Tromp <valkjes@gmail.com>

• Sayantan Khanra <skhanra@schubergphilis.com>

• Soenke Ruempler <soenke+github@ruempler.eu>

• Rafael Zamana Kineippe <rafael@zamana.com.br>

History

0.0.1 (26-04-2021)

• First code creation

0.1.0 (11-05-2021)

• Initial release

0.1.1 (17-05-2021)

• Filtering out failed accounts from checking their update status

0.1.2 (17-05-2021)

• Fixed a timing issue with getting the active service catalog product on account creation.

0.2.0 (18-05-2021)

• Exposed governed and non governed regions and a small fix with latest update changes.

0.2.1 (18-05-2021)

• Dynamically retrieving updatable information about control tower.

0.2.2 (19-05-2021)

• Added some blocking on actions to prevent race conditions.

0.2.3 (08-06-2021)

• Bumped dependencies.

0.2.4 (16-06-2021)

• Added new feature to provision instance_id for an account

0.3.0 (16-06-2021)

• Added new method to provision saml config in the account

0.4.0 (17-06-2021)

• Added provision_saml_provider to the public api

0.4.1 (19-08-2021)

• Add explict error handling on bad response.

0.4.2 (01-09-2021)

• Added pagination on organizational OU retrieval.

0.5.0 (09-09-2021)

• Explicitly passing region to control tower instantiation.

0.5.1 (09-09-2021)

• Raising exception if csrf token retrieved has no value.

0.5.2 (09-09-2021)

• Fixed hardcoded url pointing to eu-west-1 making it possible to deploy to other home regions than Ireland.

0.6.0 (01-10-2021)

• Implemented contol tower repair and bumped dependencies.

0.7.0 (14-10-2021)

• • Adding a force option to the register_ou function to force re-registering

0.8.0 (14-10-2021)

• • Adding a force option to the register_ou function to force re-registering

0.9.0 (18-10-2021)

• • Adding support to also show updated state when the landingzone gets a new configuration

0.10.0 (29-11-2021)

• Implemented cloudformation stack set organizations trusted access enabling and disabling.

0.10.1 (29-11-2021)

• Added missing dependencies.

1.0.0 (03-12-2021)

• Implemented account lifecycle and info update, MFA support and IAM billing console enablement.

1.1.0 (18-12-2021)

• Added support for nested OUs

2.0.0 (28-12-2021)

• Releasing support for 5 levels of nested OUs

2.0.1 (29-12-2021)

• Fixed a bug where on account creation the OU was not created unless there was a failure with the parent hierarchy.

2.0.2 (29-12-2021)

• Fixed a bug with the handling of the OU without hierarchies.

2.1.0 (30-12-2021)

• Implemented capability of retrieving account by email.

2.1.1 (22-02-2022)

• Updated ‘get_changing_accounts’ to use the search_provisioned_products with a filter which will fix the bug where only the first 100 provisioned products were checked for status “UNDER_CHAGE”.

2.2.0 (26-04-2022)

• Fix for new console authentication flow courtesy of Soenke Ruempler <soenke+github@ruempler.eu>, author of the awesome superwerker!

2.3.0 (05-05-2022)

• Fix for IAM authentication flow.

2.3.1 (18-05-2022)

• Fix for cases where captcha is actually not required.

2.3.2 (23-05-2022)

• Another captcha fix for the root console curtesy of Rafael Zamana Kineippe <rafael@zamana.com.br>

3.0.0 (13-06-2022)

• awsapilib calling aws native apis rather than shadow apis

3.1.0 (17-06-2022)

• fix control tower deploy/setup

3.1.1 (17-08-2022)

• Bumped dependencies.

3.1.2 (27-09-2022)

• Fix for support for Control Tower update for versions over 2.6.

3.1.3 (03-03-2023)

• Bump and loosen dependencies.

Indices and tables

• Index

• Module Index

• Search Page