API Reference#

Developer Interface#

This part of the documentation covers all the interfaces of Iamra.

iamra#

IAM Roles Anywhere credentials helper.

Iamra (ahy-em-rah) is a helper library to abstract and make obtaining temporary AWS IAM credentials easy. See the documentation at: https://pypi.org/project/iamra

Basic usage with local private key and X.509 certificate:

>>> import iamra
>>> session = iamra.Credentials(
        region="us-east-1",
        certificate_filename="client.pem",
        private_key_filename="client.key",
        duration=3600,
        profile_arn="arn:aws:rolesanywhere:us-west-2:1234567890:profile/3d203fc0-7bba-4ec1-a6ef-697504ce1c72",
        role_arn="arn:aws:iam::1234567890:role/IamRoleWithPermissionsToUse",
        session_name="my_client_test_session",
        trust_anchor_arn="arn:aws:rolesanywhere:us-west-2:1234567890:trust-anchor/29efd0b1-1b66-4df4-8ae7-e935716efd8e",
 )
 >>> session.get_credentials()
 >>> session.access_key_id
 'ASIA5FLYQEXXXXXXZ27N'
 >>> session.secret_access_key
 'HhAViXXXXqIZrq/qENC4ahPqssXXXX9DEfx3mTv'
 >>> session.session_token
 'IQoJb3JpZ2luX2VjEMf//////////wEaCXVzLXdlc3QtMiJHMEUCIEz9JVF+nQce3rmd6OmfJAbTHNbG7RJLEEa6xECqEEbQAiEA6yd2mbe0akoO+np/EgrSA/
 ...
 fARzrFrr0VEpiqFY42NWjFdFUhdLkPiuhsLoTYH+OnaGl92OxAho3j0='
copyright:

  1. Gavin Adams

license:

Apache License, Version 2.0, see LICENSE for more details.

class iamra.Boto3Session(iamra_session: Credentials)#

Creates a Boto3 session with a provided iamra.Credentials object with automatic credential refresh.

This class creates a Boto3 session with the provided iamra.Credentials object, which automatically refreshes IAM permissions when they are due to expire, by requesting refreshed credentials via IAM Roles Anywhere. The returned object is set to the region defined when creating the iamra.Credentials object.

Parameters:

iamra_session (Credentials) – iamra.Credentials session object to request and update credentials as needed

session#

Boto3 session object for use in creating other Boto3 resources such as client, with automated refresh of credentials using Roles Anywhere

Type:

boto3.Session

Returns:

Object for use with boto3 session and client calls.

Return type:

Boto3Session

class iamra.Credentials(region: str, certificate_filename: str, private_key_filename: str, duration: int, profile_arn: str, role_arn: str, trust_anchor_arn: str, session_name: Optional[str] = None, passphrase: Optional[bytes] = None, certificate_chain_filename: Optional[str] = None)#

Creates credentials object for vending temporary AWS credentials.

Create and object ready to make a call to IAM Roles Anywhere for temporary credentials. After creation, a call to get_credentials() will attempt to call Roles Anywhere and obtain time-bound credentials and populate the object’s attributes.

Parameters:

  • region (str) – AWS Region

  • certificate_filename (str) – Path to the certificate file, in PEM format

  • private_key_filename (str) – Path to the private key file, in PEM format

  • passphrase (bytes) – Optional passphrase for the private key file

  • certificate_chain_filename (str) – File containing certificate chain to CA in trust anchor, in PEM format

  • duration (int) – Duration of the credentials in seconds

  • profile_arn (str) – ARN of the Roles Anywhere profile to use

  • role_arn (str) – Name of the IAM role attached to the profile arn to use

  • session_name (str) – Name of the Roles Anywhere session

  • trust_anchor_arn (str) – ARN of the Roles Anywhere trust anchor that signed the certificate

access_key_id#

Access key obtained by get_credentials()

Type:

str

secret_access_key#

Secret access key obtained by get_credentials()

Type:

str

session_token#

Session token obtained by get_credentials() - must be provided with access_key_id and secret_access_key when calling AWS APIs

Type:

str

expiration#

Expiration date and time of credentials in ISO 8601 (UTC) format

Type:

str

Returns:

Object for specific role and profile using provided X.509 credentials.

Return type:

Credentials

Raises:

  • FileNotFoundError – If certificate, private key, or chain files are not found

  • EncryptionAlgorithmError – Private key using algorithm other than the supported RSA or EC

get_credentials() → SessionResponse#

Generate temporary AWS credentials.

Call IAM Roles Anywhere to vend credentials. Upon success set the credentials within the object and also return the full session response object.

Parameters:

None –

Raises:

  • HTTPError – If general HTTP error in encountered

  • ConnectionError – If unable to establish a connection to the endpoint

  • Timeout – If response not received in time

  • RequestException – General requests error

  • UntrustedCertificateError – If certificate is not trusted or insufficient

Returns:

Full response object from IAM Roles Anywhere

Return type:

SessionResponse