path: root/python-aws-assume-role-lib.spec

%global _empty_manifest_terminate_build 0
Name:		python-aws-assume-role-lib
Version:	2.10.0
Release:	1
Summary:	Assumed role session chaining (with credential refreshing) for boto3
License:	Apache-2.0
URL:		https://github.com/benkehoe/aws-assume-role-lib
Source0:	https://mirrors.nju.edu.cn/pypi/web/packages/b7/42/2ad7a24a388aa1de44890539e9252a889bb03cdee9b026ec47dd843503b1/aws-assume-role-lib-2.10.0.tar.gz
BuildArch:	noarch

Requires:	python3-boto3

%description
# aws-assume-role-lib
**Assumed role session chaining (with credential refreshing) for boto3**

The typical way to use boto3 when programmatically assuming a role is to explicitly call [`sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role) and use the returned credentials to create a new [`boto3.Session`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html) or client.
It looks like this mess of code:

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

sts = session.client("sts")
response = sts.assume_role(
    RoleArn=role_arn,
    RoleSessionName="something_you_have_to_think_about"
)

credentials = response["Credentials"]

assumed_role_session = boto3.Session(
    aws_access_key_id=credentials["AccessKeyId"],
    aws_secret_access_key=credentials["SecretAccessKey"],
    aws_session_token=credentials["SessionToken"]
)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

This code is verbose, requires specifying a role session name even if you don't care what it is, and must explicitly handle credential expiration and refreshing if needed (in a Lambda function, this is typically handled by calling `AssumeRole` in every invocation).

With `aws-assume-role-lib`, all that collapses down to a single line. The assumed role session automatically refreshes expired credentials and generates a role session name if one is not provided.

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

assumed_role_session = aws_assume_role_lib.assume_role(session, role_arn)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

In a Lambda function that needs to assume a role, you can create the assumed role session during initialization and use it for the lifetime of the execution environment, with `AssumeRole` calls only being made when necessary, not on every invocation.

Note that in `~/.aws/config`, [you have the option to have profiles that assume a role based on another profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html), and this automatically handles refreshing expired credentials as well.

If you've only used `boto3.client()` and are not familiar with boto3 sessions, [here's an explainer](https://ben11kehoe.medium.com/boto3-sessions-and-why-you-should-use-them-9b094eb5ca8e).

# Installation

```bash
pip install --user aws-assume-role-lib
```

Or just add [`aws_assume_role_lib.py`](https://raw.githubusercontent.com/benkehoe/aws-assume-role-lib/stable/aws_assume_role_lib/aws_assume_role_lib.py) to your project.

View the release history [here](CHANGELOG.md).

# Usage

```python
import boto3
from aws_assume_role_lib import assume_role

# Get a session
session = boto3.Session()
# or with a profile:
# session = boto3.Session(profile_name="my-profile")

# Assume the session
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole")

# do stuff with the original credentials
print(session.client("sts").get_caller_identity()["Arn"])

# do stuff with the assumed role
print(assumed_role_session.client("sts").get_caller_identity()["Arn"])
```

In Lambda, initialize the sessions outside the handler, and `AssumeRole` will only get called when necessary, rather than on every invocation:
```python
import os
import boto3
from aws_assume_role_lib import assume_role, generate_lambda_session_name

# Get the Lambda session
SESSION = boto3.Session()

# Get the config
ROLE_ARN = os.environ["ROLE_ARN"]
ROLE_SESSION_NAME = generate_lambda_session_name() # see below for details

# Assume the session
ASSUMED_ROLE_SESSION = assume_role(SESSION, ROLE_ARN, RoleSessionName=ROLE_SESSION_NAME)

def handler(event, context):
    # do stuff with the Lambda role using SESSION
    print(SESSION.client("sts").get_caller_identity()["Arn"])

    # do stuff with the assumed role using ASSUMED_ROLE_SESSION
    print(ASSUMED_ROLE_SESSION.client("sts").get_caller_identity()["Arn"])
```
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

# Interface

```
assume_role(
    # required arguments
    session:           boto3.Session,
    RoleArn:           str,

    *,
    # keyword-only arguments for AssumeRole
    RoleSessionName:   str                                    = None,
    PolicyArns:        Union[list[dict[str, str]], list[str]] = None,
    Policy:            Union[str, dict]                       = None,
    DurationSeconds:   Union[int, datetime.timedelta]         = None,
    Tags:              list[dict[str, str]]                   = None,
    TransitiveTagKeys: list[str]                              = None,
    ExternalId:        str                                    = None,
    SerialNumber:      str                                    = None,
    TokenCode:         str                                    = None,
    SourceIdentity:    str                                    = None,
    additional_kwargs: dict                                   = None,

    # keyword-only arguments for returned session
    region_name:       Union[str, bool]                       = None,

    # keyword-only arguments for assume_role() itself
    validate:          bool                                   = True,
    cache:             dict                                   = None,
)
```

`assume_role()` takes a session and a role ARN, and optionally [other keyword arguments for `sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role).

Unlike the `AssumeRole` API call itself, `RoleArn` is required, but `RoleSessionName` is not.
The `RoleSessionName` is set for you if it is not provided; it will use the [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) if that is provided, otherwise it will generated.
If you want this generated value for `RoleSessionName` when `SourceIdentity` is provided (the behavior in v2.8 and before), set `RoleSessionName` to the special value `aws_assume_role_lib.AUTOMATIC_ROLE_SESSION_NAME`.

Note that unlike the boto3 sts client method, you can provide the `Policy` parameter (the [inline session policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session)) as a `dict` instead of as a serialized JSON string, `PolicyArns` as a list of ARNs, and `DurationSeconds` as a `datetime.timedelta` instead of as an integer.

By default, the session returned by `assume_role()` links its region configuration to the input session.
If you would like to set the region explicitly, pass it in the `region_name` parameter.

Note that if the parent session was created without a region passed in to the `Session` constructor, it has an implicit region, based on searching potential configuration locations.
This means that the region used by the session can change (for example, if you set or change `os.environ["AWS_DEFAULT_REGION"]`).
By default, the child session region is linked to the parent session, so if the parent session has an implicit region, or if the parent session's region is changed directly, they would both change.
If you would like to fix the child session region to be explicitly the current value, pass `region_name=True`.
If, for some reason, you have an explicit region set on the parent, and want the child to have implicit region config, pass `region_name=False`.

By default, `assume_role()` checks if the parameters are invalid.
Without this validation, errors for these issues are more confusingly raised when the child session is first used to make an API call (boto3 doesn't make the call to retrieve credentials until they are needed).
However, this incurs a small time penalty, so parameter validation can be disabled by passing `validate=False`.

If any new arguments are added to `AssumeRole` in the future and this library is not updated to allow them directly, they can be passed in as a dict via the `additional_kwargs` argument.

The parent session is available on the child session in the `assume_role_parent_session` property.
Note this property is added by this library; ordinary boto3 sessions do not have it.

# Patching boto3

You can make the `assume_role()` function available directly in boto3 by calling `patch_boto3()`.
This creates a `boto3.assume_role(RoleArn, ...)` function (note that it does not take a session, it uses the same default session as `boto3.client()`), and adds a `boto3.Session.assume_role()` method.
So usage for that looks like:

```python
import boto3
import aws_assume_role_lib
aws_assume_role_lib.patch_boto3()

assumed_role_session = boto3.assume_role("arn:aws:iam::123456789012:role/MyRole")
# the above is basically equivalent to:
# aws_assume_role_lib.assume_role(boto3.Session(), "arn:aws:iam::123456789012:role/MyRole")

session = boto3.Session(profile_name="my-profile")
assumed_role_session = session.assume_role("arn:aws:iam::123456789012:role/MyRole")
```

# Role session names for Lambda functions
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

If you don't provide a role session name, but you provide a [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html), this value is used for the role session name as well.
If `SourceIdentity` is not provided either, the underlying `botocore` library [generates one using a timestamp](https://github.com/boto/botocore/blob/c53072ec257ef47e2fc749c384a9488fd3f3e626/botocore/credentials.py#L730).
That's the best it can do, because it doesn't have any other context.

But in a Lambda function, we do have additional context, the Lambda function itself.
If you call `generate_lambda_session_name()` inside an instance of a Lambda function, it returns a session name that corresponds to the function instance, which you can use when assuming a role in the Lambda function (either with this library's `assume_role()` or any other method).
The purpose of this is to simplify tracing usage of the session back to the function instance.

The returned value is in one of the following forms, depending on the length of the values, to keep the session name within the maximum of 64 characters:
* `{function_name}`
* `{function_name}.{identifier}`
* `{function_name}.{function_version}.{identifier}`

The function version is never included if it is `$LATEST`.

The maximum role session name length is 64 characters. To ensure this, and
to provide at least 4 characters of the identifier when it is used, the
following rules apply, in order:
1. If the function name is longer than 59 characters, the session name is the truncated function name.
2. If the function name plus the function version is longer than 59 characters, the session name is the function name plus the identifier, truncated.
3. Otherwise, the session name is the function name plus the version (if one is found and not $LATEST) plus the identifier, truncated.

The identifier is the function instance's unique ID taken from the CloudWatch log stream name; if this cannot be found, it's a timestamp if the identifier can be at least 14 characters long (to provide for second-level precision), otherwise it is a random string.
The identifier will not be included unless at least 4 characters

The values are automatically extracted from [the relevant environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime); you can override any of them by providing them as arguments to the function.

# ARN formatting
`assume_role()` requires a role ARN, and if you know the role name and account id but have trouble remembering the [exact format of role ARNs](https://docs.aws.amazon.com/service-authorization/latest/reference/list_identityandaccessmanagement.html#identityandaccessmanagement-resources-for-iam-policies), there's `get_role_arn()` for you.
There's additionally a `get_assumed_role_session_arn()` for formatting assumed role session ARNs.

```
get_role_arn(
    account_id: Union[str, int],
    role_name:  str,
    path:       str             = "",
    partition:  str             = "aws",
)

get_assumed_role_session_arn(
    account_id:        Union[str, int],
    role_name:         str,
    role_session_name: str,
    partition:         str             = "aws",
)
```

For `get_role_arn()`, if the role name has a path, it can be provided as part of the name or as the separate `path` argument (but not both).
Assumed role session ARNs do not include the role path; if it is used in the role name it is removed.

# Caching

If you would like to cache the credentials on the file system, you can use the `JSONFileCache` class, which will create files under the directory you provide in the constructor (which it will create if it doesn't exist).
Use it like:
```python
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole", cache=JSONFileCache("path/to/dir"))
```
You can also use any `dict`-like object for the cache (supporting `__getitem__`/`__setitem__`/`__contains__`).

# Command line use
`aws-assume-role-lib` has basic support for retrieving assumed role credentials from the command line.
In general, it's better to make profiles in `~/.aws/config` for role assumption, like this:

```ini
# this is a pre-existing profile you already have
[profile profile-to-call-assume-role-with]
# maybe it's IAM User credentials
# or AWS SSO config
# or whatever else you may have

[profile my-assumed-role]
role_arn = arn:aws:iam::123456789012:role/MyRole
# optional: role_session_name = MyRoleSessionName

source_profile = profile-to-call-assume-role-with
# or instead of source_profile, you can tell it to
# use external credentials. one of:
# credential_source = Environment
# credential_source = Ec2InstanceMetadata
# credential_source = EcsContainer
```

You can use `my-assumed-role` like any other profile.
It uses the AWS SDKs' built-in support for role assumption, rather than relying on this third party library.
It also gets you credential refreshing from the SDKs, where getting the credentials in the manner below cannot refresh them when they expire.

But if you absolutely must have ad hoc role assumption on the command line, use the module invocation syntax `python -m aws_assume_role_lib ROLE_ARN [OPTIONS]`.

The options are:
* `--profile`: use a specific configuration profile.
* `--env`: print the credentials as environment variables (the default), suitable for `export $(python -m aws_assume_role_lib ...)`.
* `--json`: print the credentials in [`credential_process`-formatted JSON format](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Note that you don't normally need to use this as a `credential_process` in a profile, because you can just directly make the profile do role assumption as shown above.
* The remaining options are the arguments to `assume_role()`:
  * `--RoleSessionName`
  * `--PolicyArns`: must be a comma-separated list of ARNs, a JSON list of ARNs, or a JSON object per the API
  * `--Policy`: must be a JSON object
  * `--DurationSeconds`
  * `--Tags`: must be formatted as `Key1=Value1,Key2=Value2`, or a JSON object.
  * `--TransitiveTagKeys`: must be a comma-separated list or a JSON list.
  * `--ExternalId`
  * `--SerialNumber`
  * `--TokenCode`
  * `--SourceIdentity`
  * `--additional-kwargs`: must be a JSON object.



%package -n python3-aws-assume-role-lib
Summary:	Assumed role session chaining (with credential refreshing) for boto3
Provides:	python-aws-assume-role-lib
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-aws-assume-role-lib
# aws-assume-role-lib
**Assumed role session chaining (with credential refreshing) for boto3**

The typical way to use boto3 when programmatically assuming a role is to explicitly call [`sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role) and use the returned credentials to create a new [`boto3.Session`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html) or client.
It looks like this mess of code:

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

sts = session.client("sts")
response = sts.assume_role(
    RoleArn=role_arn,
    RoleSessionName="something_you_have_to_think_about"
)

credentials = response["Credentials"]

assumed_role_session = boto3.Session(
    aws_access_key_id=credentials["AccessKeyId"],
    aws_secret_access_key=credentials["SecretAccessKey"],
    aws_session_token=credentials["SessionToken"]
)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

This code is verbose, requires specifying a role session name even if you don't care what it is, and must explicitly handle credential expiration and refreshing if needed (in a Lambda function, this is typically handled by calling `AssumeRole` in every invocation).

With `aws-assume-role-lib`, all that collapses down to a single line. The assumed role session automatically refreshes expired credentials and generates a role session name if one is not provided.

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

assumed_role_session = aws_assume_role_lib.assume_role(session, role_arn)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

In a Lambda function that needs to assume a role, you can create the assumed role session during initialization and use it for the lifetime of the execution environment, with `AssumeRole` calls only being made when necessary, not on every invocation.

Note that in `~/.aws/config`, [you have the option to have profiles that assume a role based on another profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html), and this automatically handles refreshing expired credentials as well.

If you've only used `boto3.client()` and are not familiar with boto3 sessions, [here's an explainer](https://ben11kehoe.medium.com/boto3-sessions-and-why-you-should-use-them-9b094eb5ca8e).

# Installation

```bash
pip install --user aws-assume-role-lib
```

Or just add [`aws_assume_role_lib.py`](https://raw.githubusercontent.com/benkehoe/aws-assume-role-lib/stable/aws_assume_role_lib/aws_assume_role_lib.py) to your project.

View the release history [here](CHANGELOG.md).

# Usage

```python
import boto3
from aws_assume_role_lib import assume_role

# Get a session
session = boto3.Session()
# or with a profile:
# session = boto3.Session(profile_name="my-profile")

# Assume the session
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole")

# do stuff with the original credentials
print(session.client("sts").get_caller_identity()["Arn"])

# do stuff with the assumed role
print(assumed_role_session.client("sts").get_caller_identity()["Arn"])
```

In Lambda, initialize the sessions outside the handler, and `AssumeRole` will only get called when necessary, rather than on every invocation:
```python
import os
import boto3
from aws_assume_role_lib import assume_role, generate_lambda_session_name

# Get the Lambda session
SESSION = boto3.Session()

# Get the config
ROLE_ARN = os.environ["ROLE_ARN"]
ROLE_SESSION_NAME = generate_lambda_session_name() # see below for details

# Assume the session
ASSUMED_ROLE_SESSION = assume_role(SESSION, ROLE_ARN, RoleSessionName=ROLE_SESSION_NAME)

def handler(event, context):
    # do stuff with the Lambda role using SESSION
    print(SESSION.client("sts").get_caller_identity()["Arn"])

    # do stuff with the assumed role using ASSUMED_ROLE_SESSION
    print(ASSUMED_ROLE_SESSION.client("sts").get_caller_identity()["Arn"])
```
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

# Interface

```
assume_role(
    # required arguments
    session:           boto3.Session,
    RoleArn:           str,

    *,
    # keyword-only arguments for AssumeRole
    RoleSessionName:   str                                    = None,
    PolicyArns:        Union[list[dict[str, str]], list[str]] = None,
    Policy:            Union[str, dict]                       = None,
    DurationSeconds:   Union[int, datetime.timedelta]         = None,
    Tags:              list[dict[str, str]]                   = None,
    TransitiveTagKeys: list[str]                              = None,
    ExternalId:        str                                    = None,
    SerialNumber:      str                                    = None,
    TokenCode:         str                                    = None,
    SourceIdentity:    str                                    = None,
    additional_kwargs: dict                                   = None,

    # keyword-only arguments for returned session
    region_name:       Union[str, bool]                       = None,

    # keyword-only arguments for assume_role() itself
    validate:          bool                                   = True,
    cache:             dict                                   = None,
)
```

`assume_role()` takes a session and a role ARN, and optionally [other keyword arguments for `sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role).

Unlike the `AssumeRole` API call itself, `RoleArn` is required, but `RoleSessionName` is not.
The `RoleSessionName` is set for you if it is not provided; it will use the [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) if that is provided, otherwise it will generated.
If you want this generated value for `RoleSessionName` when `SourceIdentity` is provided (the behavior in v2.8 and before), set `RoleSessionName` to the special value `aws_assume_role_lib.AUTOMATIC_ROLE_SESSION_NAME`.

Note that unlike the boto3 sts client method, you can provide the `Policy` parameter (the [inline session policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session)) as a `dict` instead of as a serialized JSON string, `PolicyArns` as a list of ARNs, and `DurationSeconds` as a `datetime.timedelta` instead of as an integer.

By default, the session returned by `assume_role()` links its region configuration to the input session.
If you would like to set the region explicitly, pass it in the `region_name` parameter.

Note that if the parent session was created without a region passed in to the `Session` constructor, it has an implicit region, based on searching potential configuration locations.
This means that the region used by the session can change (for example, if you set or change `os.environ["AWS_DEFAULT_REGION"]`).
By default, the child session region is linked to the parent session, so if the parent session has an implicit region, or if the parent session's region is changed directly, they would both change.
If you would like to fix the child session region to be explicitly the current value, pass `region_name=True`.
If, for some reason, you have an explicit region set on the parent, and want the child to have implicit region config, pass `region_name=False`.

By default, `assume_role()` checks if the parameters are invalid.
Without this validation, errors for these issues are more confusingly raised when the child session is first used to make an API call (boto3 doesn't make the call to retrieve credentials until they are needed).
However, this incurs a small time penalty, so parameter validation can be disabled by passing `validate=False`.

If any new arguments are added to `AssumeRole` in the future and this library is not updated to allow them directly, they can be passed in as a dict via the `additional_kwargs` argument.

The parent session is available on the child session in the `assume_role_parent_session` property.
Note this property is added by this library; ordinary boto3 sessions do not have it.

# Patching boto3

You can make the `assume_role()` function available directly in boto3 by calling `patch_boto3()`.
This creates a `boto3.assume_role(RoleArn, ...)` function (note that it does not take a session, it uses the same default session as `boto3.client()`), and adds a `boto3.Session.assume_role()` method.
So usage for that looks like:

```python
import boto3
import aws_assume_role_lib
aws_assume_role_lib.patch_boto3()

assumed_role_session = boto3.assume_role("arn:aws:iam::123456789012:role/MyRole")
# the above is basically equivalent to:
# aws_assume_role_lib.assume_role(boto3.Session(), "arn:aws:iam::123456789012:role/MyRole")

session = boto3.Session(profile_name="my-profile")
assumed_role_session = session.assume_role("arn:aws:iam::123456789012:role/MyRole")
```

# Role session names for Lambda functions
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

If you don't provide a role session name, but you provide a [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html), this value is used for the role session name as well.
If `SourceIdentity` is not provided either, the underlying `botocore` library [generates one using a timestamp](https://github.com/boto/botocore/blob/c53072ec257ef47e2fc749c384a9488fd3f3e626/botocore/credentials.py#L730).
That's the best it can do, because it doesn't have any other context.

But in a Lambda function, we do have additional context, the Lambda function itself.
If you call `generate_lambda_session_name()` inside an instance of a Lambda function, it returns a session name that corresponds to the function instance, which you can use when assuming a role in the Lambda function (either with this library's `assume_role()` or any other method).
The purpose of this is to simplify tracing usage of the session back to the function instance.

The returned value is in one of the following forms, depending on the length of the values, to keep the session name within the maximum of 64 characters:
* `{function_name}`
* `{function_name}.{identifier}`
* `{function_name}.{function_version}.{identifier}`

The function version is never included if it is `$LATEST`.

The maximum role session name length is 64 characters. To ensure this, and
to provide at least 4 characters of the identifier when it is used, the
following rules apply, in order:
1. If the function name is longer than 59 characters, the session name is the truncated function name.
2. If the function name plus the function version is longer than 59 characters, the session name is the function name plus the identifier, truncated.
3. Otherwise, the session name is the function name plus the version (if one is found and not $LATEST) plus the identifier, truncated.

The identifier is the function instance's unique ID taken from the CloudWatch log stream name; if this cannot be found, it's a timestamp if the identifier can be at least 14 characters long (to provide for second-level precision), otherwise it is a random string.
The identifier will not be included unless at least 4 characters

The values are automatically extracted from [the relevant environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime); you can override any of them by providing them as arguments to the function.

# ARN formatting
`assume_role()` requires a role ARN, and if you know the role name and account id but have trouble remembering the [exact format of role ARNs](https://docs.aws.amazon.com/service-authorization/latest/reference/list_identityandaccessmanagement.html#identityandaccessmanagement-resources-for-iam-policies), there's `get_role_arn()` for you.
There's additionally a `get_assumed_role_session_arn()` for formatting assumed role session ARNs.

```
get_role_arn(
    account_id: Union[str, int],
    role_name:  str,
    path:       str             = "",
    partition:  str             = "aws",
)

get_assumed_role_session_arn(
    account_id:        Union[str, int],
    role_name:         str,
    role_session_name: str,
    partition:         str             = "aws",
)
```

For `get_role_arn()`, if the role name has a path, it can be provided as part of the name or as the separate `path` argument (but not both).
Assumed role session ARNs do not include the role path; if it is used in the role name it is removed.

# Caching

If you would like to cache the credentials on the file system, you can use the `JSONFileCache` class, which will create files under the directory you provide in the constructor (which it will create if it doesn't exist).
Use it like:
```python
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole", cache=JSONFileCache("path/to/dir"))
```
You can also use any `dict`-like object for the cache (supporting `__getitem__`/`__setitem__`/`__contains__`).

# Command line use
`aws-assume-role-lib` has basic support for retrieving assumed role credentials from the command line.
In general, it's better to make profiles in `~/.aws/config` for role assumption, like this:

```ini
# this is a pre-existing profile you already have
[profile profile-to-call-assume-role-with]
# maybe it's IAM User credentials
# or AWS SSO config
# or whatever else you may have

[profile my-assumed-role]
role_arn = arn:aws:iam::123456789012:role/MyRole
# optional: role_session_name = MyRoleSessionName

source_profile = profile-to-call-assume-role-with
# or instead of source_profile, you can tell it to
# use external credentials. one of:
# credential_source = Environment
# credential_source = Ec2InstanceMetadata
# credential_source = EcsContainer
```

You can use `my-assumed-role` like any other profile.
It uses the AWS SDKs' built-in support for role assumption, rather than relying on this third party library.
It also gets you credential refreshing from the SDKs, where getting the credentials in the manner below cannot refresh them when they expire.

But if you absolutely must have ad hoc role assumption on the command line, use the module invocation syntax `python -m aws_assume_role_lib ROLE_ARN [OPTIONS]`.

The options are:
* `--profile`: use a specific configuration profile.
* `--env`: print the credentials as environment variables (the default), suitable for `export $(python -m aws_assume_role_lib ...)`.
* `--json`: print the credentials in [`credential_process`-formatted JSON format](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Note that you don't normally need to use this as a `credential_process` in a profile, because you can just directly make the profile do role assumption as shown above.
* The remaining options are the arguments to `assume_role()`:
  * `--RoleSessionName`
  * `--PolicyArns`: must be a comma-separated list of ARNs, a JSON list of ARNs, or a JSON object per the API
  * `--Policy`: must be a JSON object
  * `--DurationSeconds`
  * `--Tags`: must be formatted as `Key1=Value1,Key2=Value2`, or a JSON object.
  * `--TransitiveTagKeys`: must be a comma-separated list or a JSON list.
  * `--ExternalId`
  * `--SerialNumber`
  * `--TokenCode`
  * `--SourceIdentity`
  * `--additional-kwargs`: must be a JSON object.



%package help
Summary:	Development documents and examples for aws-assume-role-lib
Provides:	python3-aws-assume-role-lib-doc
%description help
# aws-assume-role-lib
**Assumed role session chaining (with credential refreshing) for boto3**

The typical way to use boto3 when programmatically assuming a role is to explicitly call [`sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role) and use the returned credentials to create a new [`boto3.Session`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html) or client.
It looks like this mess of code:

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

sts = session.client("sts")
response = sts.assume_role(
    RoleArn=role_arn,
    RoleSessionName="something_you_have_to_think_about"
)

credentials = response["Credentials"]

assumed_role_session = boto3.Session(
    aws_access_key_id=credentials["AccessKeyId"],
    aws_secret_access_key=credentials["SecretAccessKey"],
    aws_session_token=credentials["SessionToken"]
)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

This code is verbose, requires specifying a role session name even if you don't care what it is, and must explicitly handle credential expiration and refreshing if needed (in a Lambda function, this is typically handled by calling `AssumeRole` in every invocation).

With `aws-assume-role-lib`, all that collapses down to a single line. The assumed role session automatically refreshes expired credentials and generates a role session name if one is not provided.

```python
role_arn = "arn:aws:iam::123456789012:role/MyRole"
session = boto3.Session()

assumed_role_session = aws_assume_role_lib.assume_role(session, role_arn)

# use the session
print(assumed_role_session.client("sts").get_caller_identity())
```

In a Lambda function that needs to assume a role, you can create the assumed role session during initialization and use it for the lifetime of the execution environment, with `AssumeRole` calls only being made when necessary, not on every invocation.

Note that in `~/.aws/config`, [you have the option to have profiles that assume a role based on another profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html), and this automatically handles refreshing expired credentials as well.

If you've only used `boto3.client()` and are not familiar with boto3 sessions, [here's an explainer](https://ben11kehoe.medium.com/boto3-sessions-and-why-you-should-use-them-9b094eb5ca8e).

# Installation

```bash
pip install --user aws-assume-role-lib
```

Or just add [`aws_assume_role_lib.py`](https://raw.githubusercontent.com/benkehoe/aws-assume-role-lib/stable/aws_assume_role_lib/aws_assume_role_lib.py) to your project.

View the release history [here](CHANGELOG.md).

# Usage

```python
import boto3
from aws_assume_role_lib import assume_role

# Get a session
session = boto3.Session()
# or with a profile:
# session = boto3.Session(profile_name="my-profile")

# Assume the session
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole")

# do stuff with the original credentials
print(session.client("sts").get_caller_identity()["Arn"])

# do stuff with the assumed role
print(assumed_role_session.client("sts").get_caller_identity()["Arn"])
```

In Lambda, initialize the sessions outside the handler, and `AssumeRole` will only get called when necessary, rather than on every invocation:
```python
import os
import boto3
from aws_assume_role_lib import assume_role, generate_lambda_session_name

# Get the Lambda session
SESSION = boto3.Session()

# Get the config
ROLE_ARN = os.environ["ROLE_ARN"]
ROLE_SESSION_NAME = generate_lambda_session_name() # see below for details

# Assume the session
ASSUMED_ROLE_SESSION = assume_role(SESSION, ROLE_ARN, RoleSessionName=ROLE_SESSION_NAME)

def handler(event, context):
    # do stuff with the Lambda role using SESSION
    print(SESSION.client("sts").get_caller_identity()["Arn"])

    # do stuff with the assumed role using ASSUMED_ROLE_SESSION
    print(ASSUMED_ROLE_SESSION.client("sts").get_caller_identity()["Arn"])
```
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

# Interface

```
assume_role(
    # required arguments
    session:           boto3.Session,
    RoleArn:           str,

    *,
    # keyword-only arguments for AssumeRole
    RoleSessionName:   str                                    = None,
    PolicyArns:        Union[list[dict[str, str]], list[str]] = None,
    Policy:            Union[str, dict]                       = None,
    DurationSeconds:   Union[int, datetime.timedelta]         = None,
    Tags:              list[dict[str, str]]                   = None,
    TransitiveTagKeys: list[str]                              = None,
    ExternalId:        str                                    = None,
    SerialNumber:      str                                    = None,
    TokenCode:         str                                    = None,
    SourceIdentity:    str                                    = None,
    additional_kwargs: dict                                   = None,

    # keyword-only arguments for returned session
    region_name:       Union[str, bool]                       = None,

    # keyword-only arguments for assume_role() itself
    validate:          bool                                   = True,
    cache:             dict                                   = None,
)
```

`assume_role()` takes a session and a role ARN, and optionally [other keyword arguments for `sts.AssumeRole`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sts.html#STS.Client.assume_role).

Unlike the `AssumeRole` API call itself, `RoleArn` is required, but `RoleSessionName` is not.
The `RoleSessionName` is set for you if it is not provided; it will use the [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html) if that is provided, otherwise it will generated.
If you want this generated value for `RoleSessionName` when `SourceIdentity` is provided (the behavior in v2.8 and before), set `RoleSessionName` to the special value `aws_assume_role_lib.AUTOMATIC_ROLE_SESSION_NAME`.

Note that unlike the boto3 sts client method, you can provide the `Policy` parameter (the [inline session policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session)) as a `dict` instead of as a serialized JSON string, `PolicyArns` as a list of ARNs, and `DurationSeconds` as a `datetime.timedelta` instead of as an integer.

By default, the session returned by `assume_role()` links its region configuration to the input session.
If you would like to set the region explicitly, pass it in the `region_name` parameter.

Note that if the parent session was created without a region passed in to the `Session` constructor, it has an implicit region, based on searching potential configuration locations.
This means that the region used by the session can change (for example, if you set or change `os.environ["AWS_DEFAULT_REGION"]`).
By default, the child session region is linked to the parent session, so if the parent session has an implicit region, or if the parent session's region is changed directly, they would both change.
If you would like to fix the child session region to be explicitly the current value, pass `region_name=True`.
If, for some reason, you have an explicit region set on the parent, and want the child to have implicit region config, pass `region_name=False`.

By default, `assume_role()` checks if the parameters are invalid.
Without this validation, errors for these issues are more confusingly raised when the child session is first used to make an API call (boto3 doesn't make the call to retrieve credentials until they are needed).
However, this incurs a small time penalty, so parameter validation can be disabled by passing `validate=False`.

If any new arguments are added to `AssumeRole` in the future and this library is not updated to allow them directly, they can be passed in as a dict via the `additional_kwargs` argument.

The parent session is available on the child session in the `assume_role_parent_session` property.
Note this property is added by this library; ordinary boto3 sessions do not have it.

# Patching boto3

You can make the `assume_role()` function available directly in boto3 by calling `patch_boto3()`.
This creates a `boto3.assume_role(RoleArn, ...)` function (note that it does not take a session, it uses the same default session as `boto3.client()`), and adds a `boto3.Session.assume_role()` method.
So usage for that looks like:

```python
import boto3
import aws_assume_role_lib
aws_assume_role_lib.patch_boto3()

assumed_role_session = boto3.assume_role("arn:aws:iam::123456789012:role/MyRole")
# the above is basically equivalent to:
# aws_assume_role_lib.assume_role(boto3.Session(), "arn:aws:iam::123456789012:role/MyRole")

session = boto3.Session(profile_name="my-profile")
assumed_role_session = session.assume_role("arn:aws:iam::123456789012:role/MyRole")
```

# Role session names for Lambda functions
Learn more about the benefits of `aws-assume-role-lib` in Lambda functions in the [demo](lambda-demo/README.md).

If you don't provide a role session name, but you provide a [`SourceIdentity`](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html), this value is used for the role session name as well.
If `SourceIdentity` is not provided either, the underlying `botocore` library [generates one using a timestamp](https://github.com/boto/botocore/blob/c53072ec257ef47e2fc749c384a9488fd3f3e626/botocore/credentials.py#L730).
That's the best it can do, because it doesn't have any other context.

But in a Lambda function, we do have additional context, the Lambda function itself.
If you call `generate_lambda_session_name()` inside an instance of a Lambda function, it returns a session name that corresponds to the function instance, which you can use when assuming a role in the Lambda function (either with this library's `assume_role()` or any other method).
The purpose of this is to simplify tracing usage of the session back to the function instance.

The returned value is in one of the following forms, depending on the length of the values, to keep the session name within the maximum of 64 characters:
* `{function_name}`
* `{function_name}.{identifier}`
* `{function_name}.{function_version}.{identifier}`

The function version is never included if it is `$LATEST`.

The maximum role session name length is 64 characters. To ensure this, and
to provide at least 4 characters of the identifier when it is used, the
following rules apply, in order:
1. If the function name is longer than 59 characters, the session name is the truncated function name.
2. If the function name plus the function version is longer than 59 characters, the session name is the function name plus the identifier, truncated.
3. Otherwise, the session name is the function name plus the version (if one is found and not $LATEST) plus the identifier, truncated.

The identifier is the function instance's unique ID taken from the CloudWatch log stream name; if this cannot be found, it's a timestamp if the identifier can be at least 14 characters long (to provide for second-level precision), otherwise it is a random string.
The identifier will not be included unless at least 4 characters

The values are automatically extracted from [the relevant environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime); you can override any of them by providing them as arguments to the function.

# ARN formatting
`assume_role()` requires a role ARN, and if you know the role name and account id but have trouble remembering the [exact format of role ARNs](https://docs.aws.amazon.com/service-authorization/latest/reference/list_identityandaccessmanagement.html#identityandaccessmanagement-resources-for-iam-policies), there's `get_role_arn()` for you.
There's additionally a `get_assumed_role_session_arn()` for formatting assumed role session ARNs.

```
get_role_arn(
    account_id: Union[str, int],
    role_name:  str,
    path:       str             = "",
    partition:  str             = "aws",
)

get_assumed_role_session_arn(
    account_id:        Union[str, int],
    role_name:         str,
    role_session_name: str,
    partition:         str             = "aws",
)
```

For `get_role_arn()`, if the role name has a path, it can be provided as part of the name or as the separate `path` argument (but not both).
Assumed role session ARNs do not include the role path; if it is used in the role name it is removed.

# Caching

If you would like to cache the credentials on the file system, you can use the `JSONFileCache` class, which will create files under the directory you provide in the constructor (which it will create if it doesn't exist).
Use it like:
```python
assumed_role_session = assume_role(session, "arn:aws:iam::123456789012:role/MyRole", cache=JSONFileCache("path/to/dir"))
```
You can also use any `dict`-like object for the cache (supporting `__getitem__`/`__setitem__`/`__contains__`).

# Command line use
`aws-assume-role-lib` has basic support for retrieving assumed role credentials from the command line.
In general, it's better to make profiles in `~/.aws/config` for role assumption, like this:

```ini
# this is a pre-existing profile you already have
[profile profile-to-call-assume-role-with]
# maybe it's IAM User credentials
# or AWS SSO config
# or whatever else you may have

[profile my-assumed-role]
role_arn = arn:aws:iam::123456789012:role/MyRole
# optional: role_session_name = MyRoleSessionName

source_profile = profile-to-call-assume-role-with
# or instead of source_profile, you can tell it to
# use external credentials. one of:
# credential_source = Environment
# credential_source = Ec2InstanceMetadata
# credential_source = EcsContainer
```

You can use `my-assumed-role` like any other profile.
It uses the AWS SDKs' built-in support for role assumption, rather than relying on this third party library.
It also gets you credential refreshing from the SDKs, where getting the credentials in the manner below cannot refresh them when they expire.

But if you absolutely must have ad hoc role assumption on the command line, use the module invocation syntax `python -m aws_assume_role_lib ROLE_ARN [OPTIONS]`.

The options are:
* `--profile`: use a specific configuration profile.
* `--env`: print the credentials as environment variables (the default), suitable for `export $(python -m aws_assume_role_lib ...)`.
* `--json`: print the credentials in [`credential_process`-formatted JSON format](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Note that you don't normally need to use this as a `credential_process` in a profile, because you can just directly make the profile do role assumption as shown above.
* The remaining options are the arguments to `assume_role()`:
  * `--RoleSessionName`
  * `--PolicyArns`: must be a comma-separated list of ARNs, a JSON list of ARNs, or a JSON object per the API
  * `--Policy`: must be a JSON object
  * `--DurationSeconds`
  * `--Tags`: must be formatted as `Key1=Value1,Key2=Value2`, or a JSON object.
  * `--TransitiveTagKeys`: must be a comma-separated list or a JSON list.
  * `--ExternalId`
  * `--SerialNumber`
  * `--TokenCode`
  * `--SourceIdentity`
  * `--additional-kwargs`: must be a JSON object.



%prep
%autosetup -n aws-assume-role-lib-2.10.0

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-aws-assume-role-lib -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Sun Apr 23 2023 Python_Bot <Python_Bot@openeuler.org> - 2.10.0-1
- Package Spec generated