# aws-assumptions
* Easily switch between roles, or a chain of roles and create boto3 clients and resources off of those assumed identities.
* Can be used as a library to assume roles. The created object also provides a factory for creating boto3 clients/resources off of the object
* CLI script that allows printing credentials to stdout as either the standard response from boto3.sts.assume_role or formatted to use as env vars in a *nix terminal.
* CLI provides `exec` command to execute terminal commands in a subshell with the newly minted credentials injected into the environment
### Available CLI commands
```
~ > assumptions -h
usage: assumptions [-h] {whoami,assume} ...
positional arguments:
{whoami,assume,exec}
optional arguments:
-h, --help show this help message and exit
Switch roles, or through a chain or roles, or print identity information from AWS STS
```
### Getting current identity
```
> assumptions whoami -h
usage: assumptions whoami [-h]
optional arguments:
-h, --help show this help message and exit
Prints get-caller-identity info in JSON format
```
### Assuming a role
```
~ > assumptions assume -h
usage: assumptions assume [-h] -r ROLE_ARN [-n ROLE_SESSION_NAME] [-p POLICY_ARN] [-t TAG] [-T TRANSITIVE_TAG_KEY] [-E EXTERNAL_ID] [-d DURATION_SECONDS] [-e]
optional arguments:
-h, --help show this help message and exit
-r ROLE_ARN, --role-arn ROLE_ARN
Role to assume. If declared multiple times each role will assume the next in the order given. All other options will be applied to all roles in the chain.
-n ROLE_SESSION_NAME, --role-session-name ROLE_SESSION_NAME
The session name to use with the role.
-p POLICY_ARN, --policy-arn POLICY_ARN
Optional policy to attach to a session. Can be declared multiple times.
-t TAG, --tag TAG Optional tag to add to the session in the format of `mytagkey=myvalue`. Can be declared multiple times for multiple tags.
-T TRANSITIVE_TAG_KEY, --transitive-tag-key TRANSITIVE_TAG_KEY
Transitive tag key. Can be declared multiple times.
-E EXTERNAL_ID, --external-id EXTERNAL_ID
Optional External ID for the session. Required by some AssumeRole policies
-d DURATION_SECONDS, --duration-seconds DURATION_SECONDS
Optional duration for the session.
-e, --env-vars Output env vars usable from a terminal. If not set the output will match the output of aws-cli's `aws sts assume-role` JSON
Assume a role or a chain of roles with optional attributes, outputting the newly acquired credentials. Maintains parity with boto3's sts.assume_role except for MFA
```
Example of assuming a role with env vars
```
> assumptions assume -r "arn:aws:iam::123456789876:role/my-role" -n bob@nowhere.com -e > creds.env
> . creds.env
```
or
```
$(assumptions assume -r "arn:aws:iam::123456789876:role/my-role" -n bob@nowhere.com)
```
### Using `exec`
```
usage: scripts.py exec [-h] -r ROLE_ARN [-n ROLE_SESSION_NAME] [-p POLICY_ARN] [-t TAG] [-T TRANSITIVE_TAG_KEY] [-E EXTERNAL_ID] [-d DURATION_SECONDS] [-N] [-e ENV_VAR] [--env-file ENV_FILE] ...
positional arguments:
exec_command
optional arguments:
-h, --help show this help message and exit
-r ROLE_ARN, --role-arn ROLE_ARN
Role to assume. If declared multiple times each role will assume the next in the order given. All other options will be applied to all roles in the chain.
-n ROLE_SESSION_NAME, --role-session-name ROLE_SESSION_NAME
The session name to use with the role.
-p POLICY_ARN, --policy-arn POLICY_ARN
Optional policy to attach to a session. Can be declared multiple times.
-t TAG, --tag TAG Optional tag to add to the session in the format of `mytagkey=myvalue`. Can be declared multiple times for multiple tags.
-T TRANSITIVE_TAG_KEY, --transitive-tag-key TRANSITIVE_TAG_KEY
Transitive tag key. Can be declared multiple times.
-E EXTERNAL_ID, --external-id EXTERNAL_ID
Optional External ID for the session. Required by some AssumeRole policies
-d DURATION_SECONDS, --duration-seconds DURATION_SECONDS
Optional duration for the session.
-N, --no-inherit-env Don't allow the executed command to inherit the parent's env.
-e ENV_VAR, --env-var ENV_VAR
Env var in the format `MYVAR=foo` to pass to the executed command's environment. Can be declared multiple times.
--env-file ENV_FILE Load env vars from a .env file.
Execute a command in a shell with newly created credentials.
```
Example
```
> assumptions exec -r "arn:aws:iam::123456789876:role/my-role" -n bob@nowhere.com aws sts get-caller-identity
{
"UserId": "AROA4HO3IAI67GZHCWWWQ:bob@nowhere.com",
"Account": "840662778429",
"Arn": "arn:aws:sts::123456789876:assumed-role/my-role/bob@nowhere.com"
}
```
Example passing env vars to an interactive shell
```
> assumptions exec -r "arn:aws:iam::123456789876:role/my-role" -n bob@nowhere.com -e FOO=bar bash
$ echo $FOO
bar
```
## Switching through multiple roles
If you need to chain roles (EG: Assume a role that assumes a role that assumes a role) you can pass the `-r` flag multiple times.
Note however that all other options, such as `--external-id` or `--tag` will be applied to every session in the chain.
## As a library
Assuming a role and creating clients
```python
from aws_assumptions.identity import Identity
session = Identity(
RoleArn="arn:aws:iam::123456789876:role/my-role",
RoleSessionName="bob"
)
res = session.client("eks").list_clusters()
current_role = session.whoami()
session_that_made_current_rule = session.whomademe()
```
Chaining roles
```python
from aws_assumptions.identity import Identity
session = Identity(
RoleArn=[
"arn:aws:iam::123456789876:role/my-role",
"arn:aws:iam::123456789876:role/my-second-role"
],
RoleSessionName="bob"
)
res = session.client("eks").list_clusters()
current_role = session.whoami()
session_that_made_current_rule = session.whomademe()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/mathewmoon/aws-assumptions",
"name": "aws-assumptions",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Mathew Moon",
"author_email": "me@mathewmoon.net",
"download_url": "https://files.pythonhosted.org/packages/ec/a1/d6348f03e48988659f6f4707f79fb3140cbc82e2ede36583d6545577fc2d/aws_assumptions-0.2.2.tar.gz",
"platform": null,
"description": "# aws-assumptions\n\n* Easily switch between roles, or a chain of roles and create boto3 clients and resources off of those assumed identities.\n* Can be used as a library to assume roles. The created object also provides a factory for creating boto3 clients/resources off of the object\n* CLI script that allows printing credentials to stdout as either the standard response from boto3.sts.assume_role or formatted to use as env vars in a *nix terminal.\n* CLI provides `exec` command to execute terminal commands in a subshell with the newly minted credentials injected into the environment\n\n\n### Available CLI commands\n```\n~ > assumptions -h\nusage: assumptions [-h] {whoami,assume} ...\n\npositional arguments:\n {whoami,assume,exec}\n\noptional arguments:\n -h, --help show this help message and exit\n\nSwitch roles, or through a chain or roles, or print identity information from AWS STS\n```\n\n### Getting current identity\n```\n> assumptions whoami -h\nusage: assumptions whoami [-h]\n\noptional arguments:\n -h, --help show this help message and exit\n\nPrints get-caller-identity info in JSON format\n```\n\n### Assuming a role\n```\n~ > assumptions assume -h\nusage: assumptions assume [-h] -r ROLE_ARN [-n ROLE_SESSION_NAME] [-p POLICY_ARN] [-t TAG] [-T TRANSITIVE_TAG_KEY] [-E EXTERNAL_ID] [-d DURATION_SECONDS] [-e]\n\noptional arguments:\n -h, --help show this help message and exit\n -r ROLE_ARN, --role-arn ROLE_ARN\n Role to assume. If declared multiple times each role will assume the next in the order given. All other options will be applied to all roles in the chain.\n -n ROLE_SESSION_NAME, --role-session-name ROLE_SESSION_NAME\n The session name to use with the role.\n -p POLICY_ARN, --policy-arn POLICY_ARN\n Optional policy to attach to a session. Can be declared multiple times.\n -t TAG, --tag TAG Optional tag to add to the session in the format of `mytagkey=myvalue`. Can be declared multiple times for multiple tags.\n -T TRANSITIVE_TAG_KEY, --transitive-tag-key TRANSITIVE_TAG_KEY\n Transitive tag key. Can be declared multiple times.\n -E EXTERNAL_ID, --external-id EXTERNAL_ID\n Optional External ID for the session. Required by some AssumeRole policies\n -d DURATION_SECONDS, --duration-seconds DURATION_SECONDS\n Optional duration for the session.\n -e, --env-vars Output env vars usable from a terminal. If not set the output will match the output of aws-cli's `aws sts assume-role` JSON\n\nAssume a role or a chain of roles with optional attributes, outputting the newly acquired credentials. Maintains parity with boto3's sts.assume_role except for MFA\n```\n\nExample of assuming a role with env vars\n```\n> assumptions assume -r \"arn:aws:iam::123456789876:role/my-role\" -n bob@nowhere.com -e > creds.env\n> . creds.env\n```\n\nor\n\n```\n$(assumptions assume -r \"arn:aws:iam::123456789876:role/my-role\" -n bob@nowhere.com)\n```\n\n### Using `exec`\n\n```\nusage: scripts.py exec [-h] -r ROLE_ARN [-n ROLE_SESSION_NAME] [-p POLICY_ARN] [-t TAG] [-T TRANSITIVE_TAG_KEY] [-E EXTERNAL_ID] [-d DURATION_SECONDS] [-N] [-e ENV_VAR] [--env-file ENV_FILE] ...\n\npositional arguments:\n exec_command\n\noptional arguments:\n -h, --help show this help message and exit\n -r ROLE_ARN, --role-arn ROLE_ARN\n Role to assume. If declared multiple times each role will assume the next in the order given. All other options will be applied to all roles in the chain.\n -n ROLE_SESSION_NAME, --role-session-name ROLE_SESSION_NAME\n The session name to use with the role.\n -p POLICY_ARN, --policy-arn POLICY_ARN\n Optional policy to attach to a session. Can be declared multiple times.\n -t TAG, --tag TAG Optional tag to add to the session in the format of `mytagkey=myvalue`. Can be declared multiple times for multiple tags.\n -T TRANSITIVE_TAG_KEY, --transitive-tag-key TRANSITIVE_TAG_KEY\n Transitive tag key. Can be declared multiple times.\n -E EXTERNAL_ID, --external-id EXTERNAL_ID\n Optional External ID for the session. Required by some AssumeRole policies\n -d DURATION_SECONDS, --duration-seconds DURATION_SECONDS\n Optional duration for the session.\n -N, --no-inherit-env Don't allow the executed command to inherit the parent's env.\n -e ENV_VAR, --env-var ENV_VAR\n Env var in the format `MYVAR=foo` to pass to the executed command's environment. Can be declared multiple times.\n --env-file ENV_FILE Load env vars from a .env file.\n\nExecute a command in a shell with newly created credentials.\n```\n\nExample\n```\n> assumptions exec -r \"arn:aws:iam::123456789876:role/my-role\" -n bob@nowhere.com aws sts get-caller-identity\n{\n \"UserId\": \"AROA4HO3IAI67GZHCWWWQ:bob@nowhere.com\",\n \"Account\": \"840662778429\",\n \"Arn\": \"arn:aws:sts::123456789876:assumed-role/my-role/bob@nowhere.com\"\n}\n```\n\nExample passing env vars to an interactive shell\n```\n> assumptions exec -r \"arn:aws:iam::123456789876:role/my-role\" -n bob@nowhere.com -e FOO=bar bash\n$ echo $FOO\nbar\n```\n\n## Switching through multiple roles\nIf you need to chain roles (EG: Assume a role that assumes a role that assumes a role) you can pass the `-r` flag multiple times.\nNote however that all other options, such as `--external-id` or `--tag` will be applied to every session in the chain.\n\n## As a library\n\nAssuming a role and creating clients\n```python\nfrom aws_assumptions.identity import Identity\n\nsession = Identity(\n RoleArn=\"arn:aws:iam::123456789876:role/my-role\",\n RoleSessionName=\"bob\"\n)\n\nres = session.client(\"eks\").list_clusters()\ncurrent_role = session.whoami()\nsession_that_made_current_rule = session.whomademe()\n```\n\nChaining roles\n\n```python\nfrom aws_assumptions.identity import Identity\n\nsession = Identity(\n RoleArn=[\n \"arn:aws:iam::123456789876:role/my-role\",\n \"arn:aws:iam::123456789876:role/my-second-role\"\n ],\n RoleSessionName=\"bob\"\n)\n\nres = session.client(\"eks\").list_clusters()\ncurrent_role = session.whoami()\nsession_that_made_current_rule = session.whomademe()\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Assume role(s) from a terminal and easily manage boto3 clients for multiple identities at once.",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://github.com/mathewmoon/aws-assumptions",
"Homepage": "https://github.com/mathewmoon/aws-assumptions"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eae1ae29890e88de360f29c230f0ecb425e47ab2f25dcc35c4791a2722f83061",
"md5": "ba30e16cf033ddf9374c0669485836a0",
"sha256": "9dbede36f376553711bb856865a9e19982d192759daee3da1383c7cc555fabb2"
},
"downloads": -1,
"filename": "aws_assumptions-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba30e16cf033ddf9374c0669485836a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 7447,
"upload_time": "2023-05-10T23:23:40",
"upload_time_iso_8601": "2023-05-10T23:23:40.756817Z",
"url": "https://files.pythonhosted.org/packages/ea/e1/ae29890e88de360f29c230f0ecb425e47ab2f25dcc35c4791a2722f83061/aws_assumptions-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eca1d6348f03e48988659f6f4707f79fb3140cbc82e2ede36583d6545577fc2d",
"md5": "9772d4ad466fa5ec6977629c0ad300ba",
"sha256": "1f9102afa63458f50571997f3d47a6204409818eea206f8b6c8b33a06950e5dc"
},
"downloads": -1,
"filename": "aws_assumptions-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "9772d4ad466fa5ec6977629c0ad300ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 6934,
"upload_time": "2023-05-10T23:23:29",
"upload_time_iso_8601": "2023-05-10T23:23:29.117089Z",
"url": "https://files.pythonhosted.org/packages/ec/a1/d6348f03e48988659f6f4707f79fb3140cbc82e2ede36583d6545577fc2d/aws_assumptions-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-10 23:23:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mathewmoon",
"github_project": "aws-assumptions",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aws-assumptions"
}