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.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 an 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_boto3_session(region: Optional[str] = None) → Session#

Returns a boto3 session object with automatic credential refresh.

Only a single boto3 session object should be associated with the credential session. Creating new ones still uses the underlying credentials.

Parameters:

region (str) – Optional argument to define which AWS Region is used for boto3 client calls. This can be different than the region defined when creating the Credentials session.

Returns:

Boto3 session using Credentials for authorizing boto3 client operations

Return type:

boto3.session

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