boto3_refresh_session.methods.sts.STSRefreshableSession

class boto3_refresh_session.methods.sts.STSRefreshableSession(assume_role_kwargs: AssumeRoleParams, sts_client_kwargs: STSClientParams | None = None, mfa_token_provider: Callable[[], str] | None = None, mfa_token_provider_kwargs: dict | None = None, **kwargs)

A boto3.session.Session object that automatically refreshes temporary AWS credentials using an IAM role that is assumed via STS.

Parameters:

assume_role_kwargsAssumeRoleParams

Required keyword arguments for STS.Client.assume_role (i.e. boto3 STS client). RoleArn is required. RoleSessionName will default to ‘boto3-refresh-session’ if not provided.

For MFA authentication, two modalities are supported:

1. Dynamic tokens (recommended): Provide SerialNumber in assume_role_kwargs and pass mfa_token_provider callable. The provider callable will be invoked on each refresh to obtain fresh MFA tokens. Do not include TokenCode in this case.

2. Static/injectable tokens: Provide both SerialNumber and TokenCode in assume_role_kwargs. You are responsible for updating assume_role_kwargs["TokenCode"] before the token expires.

defer_refreshbool, optional

If True then temporary credentials are not automatically refreshed until they are explicitly needed. If False then temporary credentials refresh immediately upon expiration. It is highly recommended that you use True. Default is True.

sts_client_kwargsSTSClientParams, optional

Optional keyword arguments for the STS.Client object. Do not provide values for service_name as they are unnecessary. Default is None.

mfa_token_providerCallable[[], str], optional

An optional callable that returns a string representing a fresh MFA token code. If provided, this will be called during each credential refresh to obtain a new token, which overrides any TokenCode in assume_role_kwargs. When using this parameter, SerialNumber must be provided in assume_role_kwargs. Default is None.

mfa_token_provider_kwargsdict, optional

Optional keyword arguments to pass to the mfa_token_provider callable. Default is None.

Other Parameters:

kwargsdict

Optional keyword arguments for the boto3.session.Session object.

property available_profiles

The profiles available to the session credentials

client(service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None, aws_account_id=None)

Create a low-level service client by name.

Parameters:

• service_name (string) – The name of a service, e.g. ‘s3’ or ‘ec2’. You can get a list of available services via get_available_services.

• region_name (string) – The name of the region associated with the client. A client is associated with a single region.

• api_version (string) – The API version to use. By default, botocore will use the latest API version when creating a client. You only need to specify this parameter if you want to use a previous API version of the client.

• use_ssl (boolean) – Whether or not to use SSL. By default, SSL is used. Note that not all services support non-ssl connections.

• verify (boolean/string) –

  Whether or not to verify SSL certificates. By default SSL certificates are verified. You can provide the following values:

  • False - do not validate SSL certificates. SSL will still be used (unless use_ssl is False), but SSL certificates will not be verified.

  • path/to/cert/bundle.pem - A filename of the CA cert bundle to uses. You can specify this argument if you want to use a different CA cert bundle than the one used by botocore.

• endpoint_url (string) – The complete URL to use for the constructed client. Normally, botocore will automatically construct the appropriate URL to use when communicating with a service. You can specify a complete URL (including the “http/https” scheme) to override this behavior. If this value is provided, then use_ssl is ignored.

• aws_access_key_id (string) – The access key to use when creating the client. This is entirely optional, and if not provided, the credentials configured for the session will automatically be used. You only need to provide this argument if you want to override the credentials used for this specific client.

• aws_secret_access_key (string) – The secret key to use when creating the client. Same semantics as aws_access_key_id above.

• aws_session_token (string) – The session token to use when creating the client. Same semantics as aws_access_key_id above.

• config (botocore.client.Config) – Advanced client configuration options. If region_name is specified in the client config, its value will take precedence over environment variables and configuration values, but not over a region_name value passed explicitly to the method. See botocore config documentation for more details.

• aws_account_id (string) – The account id to use when creating the client. Same semantics as aws_access_key_id above.

Returns:

Service client instance

property credentials: RefreshableTemporaryCredentials

The current temporary AWS security credentials.

property events

The event emitter for a session

get_available_partitions()

Lists the available partitions

Return type:

list

Returns:

Returns a list of partition names (e.g., [“aws”, “aws-cn”])

get_available_regions(service_name, partition_name='aws', allow_non_regional=False)

Lists the region and endpoint names of a particular partition.

The list of regions returned by this method are regions that are explicitly known by the client to exist and is not comprehensive. A region not returned in this list may still be available for the provided service.

Parameters:

• service_name (string) – Name of a service to list endpoint for (e.g., s3).

• partition_name (string) – Name of the partition to limit endpoints to. (e.g., aws for the public AWS endpoints, aws-cn for AWS China endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.)

• allow_non_regional (bool) – Set to True to include endpoints that are not regional endpoints (e.g., s3-external-1, fips-us-gov-west-1, etc).

Returns:

Returns a list of endpoint names (e.g., [“us-east-1”]).

get_available_resources()

Get a list of available services that can be loaded as resource clients via Session.resource.

Return type:

list

Returns:

List of service names

get_available_services()

Get a list of available services that can be loaded as low-level clients via Session.client.

Return type:

list

Returns:

List of service names

get_credentials()

Return the botocore.credentials.Credentials object associated with this session. If the credentials have not yet been loaded, this will attempt to load them. If they have already been loaded, this will return the cached credentials.

get_identity() → dict[str, Any]

Returns metadata about the identity assumed.

Returns:

Identity

Dict containing caller identity according to AWS STS.

get_partition_for_region(region_name)

Lists the partition name of a particular region.

Parameters:

region_name (string) – Name of the region to list partition for (e.g., us-east-1).

Return type:

string

Returns:

Returns the respective partition name (e.g., aws).

classmethod items() → dict[str, type]

Typed accessor for introspection / debugging.

property profile_name

The read-only profile name.

refreshable_credentials() → RefreshableTemporaryCredentials

The current temporary AWS security credentials.

Returns:

RefreshableTemporaryCredentials

Temporary AWS security credentials containing:

AWS_ACCESS_KEY_IDstr

AWS access key identifier.

AWS_SECRET_ACCESS_KEYstr

AWS secret access key.

AWS_SESSION_TOKENstr

AWS session token.

property region_name

The read-only region name.

resource(service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None)

Create a resource service client by name.

Parameters:

• service_name (string) – The name of a service, e.g. ‘s3’ or ‘ec2’. You can get a list of available services via get_available_resources.

• region_name (string) – The name of the region associated with the client. A client is associated with a single region.

• api_version (string) – The API version to use. By default, botocore will use the latest API version when creating a client. You only need to specify this parameter if you want to use a previous API version of the client.

• use_ssl (boolean) – Whether or not to use SSL. By default, SSL is used. Note that not all services support non-ssl connections.

• verify (boolean/string) –

  Whether or not to verify SSL certificates. By default SSL certificates are verified. You can provide the following values:

  • False - do not validate SSL certificates. SSL will still be used (unless use_ssl is False), but SSL certificates will not be verified.

  • path/to/cert/bundle.pem - A filename of the CA cert bundle to uses. You can specify this argument if you want to use a different CA cert bundle than the one used by botocore.

• endpoint_url (string) – The complete URL to use for the constructed client. Normally, botocore will automatically construct the appropriate URL to use when communicating with a service. You can specify a complete URL (including the “http/https” scheme) to override this behavior. If this value is provided, then use_ssl is ignored.

• aws_access_key_id (string) – The access key to use when creating the client. This is entirely optional, and if not provided, the credentials configured for the session will automatically be used. You only need to provide this argument if you want to override the credentials used for this specific client.

• aws_secret_access_key (string) – The secret key to use when creating the client. Same semantics as aws_access_key_id above.

• aws_session_token (string) – The session token to use when creating the client. Same semantics as aws_access_key_id above.

• config (botocore.client.Config) –

  Advanced client configuration options. If region_name is specified in the client config, its value will take precedence over environment variables and configuration values, but not over a region_name value passed explicitly to the method. If user_agent_extra is specified in the client config, it overrides the default user_agent_extra provided by the resource API. See botocore config documentation for more details.

Returns:

Subclass of ServiceResource