{"id":37083323,"url":"https://github.com/mozilla-iam/mozilla-aws-cli","last_synced_at":"2026-01-14T10:09:34.478Z","repository":{"id":33675199,"uuid":"160404547","full_name":"mozilla-iam/mozilla-aws-cli","owner":"mozilla-iam","description":"DEPRECATED. A command line tool to allow users to log into AWS with their federated identity using Single Sign On and obtain ephemeral API keys. This is no longer in use in Mozilla SSO/IAM, as of September 15th, 2023.","archived":true,"fork":false,"pushed_at":"2023-08-18T22:36:02.000Z","size":1614,"stargazers_count":20,"open_issues_count":48,"forks_count":6,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-11-27T18:44:17.280Z","etag":null,"topics":["aws","openid-connect","sso"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla-iam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-04T18:55:14.000Z","updated_at":"2024-01-03T14:16:06.000Z","dependencies_parsed_at":"2023-01-15T02:00:37.896Z","dependency_job_id":null,"html_url":"https://github.com/mozilla-iam/mozilla-aws-cli","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mozilla-iam/mozilla-aws-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-iam%2Fmozilla-aws-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-iam%2Fmozilla-aws-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-iam%2Fmozilla-aws-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-iam%2Fmozilla-aws-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla-iam","download_url":"https://codeload.github.com/mozilla-iam/mozilla-aws-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-iam%2Fmozilla-aws-cli/sbom","scorecard":{"id":661974,"data":{"date":"2025-08-11","repo":{"name":"github.com/mozilla-iam/mozilla-aws-cli","commit":"35238c3ded1df8497283011b7375a1ec5f1115d4"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.1,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build-publish.yml:1","Warn: no topLevel permission defined: .github/workflows/test.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Code-Review","score":6,"reason":"Found 6/9 approved changesets -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build-publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/build-publish.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/build-publish.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/build-publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/test.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yml:48: update your workflow using https://app.stepsecurity.io/secureworkflow/mozilla-iam/mozilla-aws-cli/test.yml/master?enable=pin","Warn: pipCommand not pinned by hash: cloudformation/deploy.sh:46","Warn: pipCommand not pinned by hash: .github/workflows/build-publish.yml:14","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:54","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:55","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:33","Warn: pipCommand not pinned by hash: .github/workflows/test.yml:34","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   6 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Mozilla Public License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-232 / GHSA-6c5p-j8vq-pqhj","Warn: Project is vulnerable to: PYSEC-2024-233 / GHSA-cjwg-qfpm-7377","Warn: Project is vulnerable to: PYSEC-2017-28 / GHSA-w799-prg3-cx77"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-21T16:29:00.281Z","repository_id":33675199,"created_at":"2025-08-21T16:29:00.281Z","updated_at":"2025-08-21T16:29:00.281Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28416617,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","openid-connect","sso"],"created_at":"2026-01-14T10:09:33.607Z","updated_at":"2026-01-14T10:09:34.468Z","avatar_url":"https://github.com/mozilla-iam.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mozilla AWS CLI\n\nThe Mozilla AWS CLI is a command line tool to allow users to log into AWS with their federated\nidentity using Single Sign On and obtain ephemeral API keys. This does not use [AWS SSO](https://aws.amazon.com/single-sign-on/)\nwhich only works with Active Directory or SAML identity providers, and instead\nuses [AWS identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)\nwith OpenID Connect (OIDC).\n\nMozilla AWS CLI is the sister project to [Federated AWS RP](https://github.com/mozilla-iam/federated-aws-rp).\nMozilla AWS CLI enables command line and API access to AWS, where Federated AWS \nRP enables login to the AWS Management Console over the web.\n\n* [Prerequisites](#prerequisites)\n* [Setup](#setup)\n* [Usage](#usage)\n* [Output Formats](#output-formats)\n* [Sequence diagram](#sequence-diagram)\n* [Details](#details)\n* [Troubleshooting](#troubleshooting)\n* [Development](#development)\n* [Creating enterprise / organization configuration](#creating-enterprise---organization-configuration)\n* [Other projects in this space](#other-projects-in-this-space)\n\n## Prerequisites\n\n* An OIDC identity provider like [Auth0](https://auth0.com/)\n  * The [OpenID Provider Configuration Document URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)\n    for your OIDC identity provider\n* A provisioned Auth0 [application](https://auth0.com/docs/applications) with a `client_id`\n* An [AWS OpenID Connect Identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)\n* A deployed instance of the [Group Role Map Builder](cloudformation/README.md)\n* A deployed instance of the [ID Token For Roles API](cloudformation/README.md)\n* An [Auth0 rule](https://auth0.com/docs/rules) which \n  [sets the `amr` field of the ID Token to the user's group list](https://github.com/mozilla-iam/auth0-deploy/blob/master/rules/AWS-Federated-AMR.js)\n\n## Setup\n\n### Provision an Auth0 Application\n\nCreate an Auth0 [application](https://auth0.com/docs/applications) with the\nfollowing settings\n\n* Application Type : `Native`\n* Allowed Callback URLs : A list of the localhost URLs created from the\n  [`POSSIBLE_PORTS` list of ports](https://github.com/mozilla-iam/mozilla-aws-cli/blob/6de1d9223f14d2ad5cae85856e2c7036ab8237eb/mozilla_aws_cli/listener.py#L16-L17)   \n  * http://localhost:10800/redirect_uri\n  * http://localhost:10801/redirect_uri\n  * http://localhost:20800/redirect_uri\n  * http://localhost:20801/redirect_uri\n  * http://localhost:30800/redirect_uri\n  * http://localhost:30801/redirect_uri\n  * http://localhost:40800/redirect_uri\n  * http://localhost:40801/redirect_uri\n  * http://localhost:50800/redirect_uri\n  * http://localhost:50801/redirect_uri\n  * http://localhost:60800/redirect_uri\n  * http://localhost:60801/redirect_uri\n* JsonWebToken Signature Algorithm of `RS256`\n* Grants of `Implicit`  and `Authorization Code`\n\nThe `client_id` for this application will be used in the CLI config file\n\n### Create an AWS OIDC Identity Provider\n\nYou can create an identity provider\n\n* [manually through the web console, on the command line or via the API](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)\n* with a [custom CloudFormation resource](https://github.com/mozilla/security/tree/master/operations/cloudformation-templates/oidc_identity_provider) (how we do this at Mozilla)\n  * This custom resource is no longer needed as CloudFormation now supports [OIDCProvider](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html#cfn-iam-oidcprovider-clientidlist)\n    and this `AWS::IAM::OIDCProvider` can be used\n\nThe Identity provider needs to have\n* an audience value of the Auth0 application `client_id`\n* a [valid thumbprint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html)\n* the URL of the Auth0 identity provider\n\n### Create a config file\n\nUsers can either configure Mozilla AWS CLI with a [python package](#creating-enterprise--organization-configuration)\nprovided by their organization (this is how we do it at Mozilla), or they can \ncreate a config file by hand.\n\nThe default files that configuration is fetched from are\n* Windows\n  * `C:\\Users\\\u003cuser\u003e\\AppData\\Roaming\\Mozilla AWS CLI\\config.ini`\n  * `C:\\ProgramData\\Mozilla AWS CLI\\config.ini`\n* Mac\n  * `/Users/\u003cuser\u003e/.config/maws/config.ini`\n  * `/etc/maws/config.ini`\n* Linux\n  * `/etc/xdg/xdg-ubuntu/maws/config.ini` (for Ubuntu)\n  * `/home/\u003cuser\u003e/.config/maws/config.ini`\n\nwhere settings in `/etc` or `C:\\ProgramData` are overridden by settings in \n`C:\\Users\\\u003cuser\u003e\\AppData\\Roaming\\` or `~/.config/maws/` or `/Users/`.\n\nUsers can also assert which config file(s) to read from using the `-c` or `--config`\ncommand line arguments.\n\nThese config files use the standard [INI file format](https://en.wikipedia.org/wiki/INI_file).\n\nThe `config` file should contain a single section called `[maws]` and can\ncontain the following settings.\n\n#### Config file settings\n\nThere are three *required* settings which must either be set in a [python package](#creating-enterprise--organization-configuration)\nprovided by the organization or in the user's config file. Those required\nsettings are\n\n* `well_known_url` : The\n  [OpenID Connect Discovery Endpoint URL](https://openid.net/specs/openid-connect-discovery-1_0.html).\n  ([Auth0](https://auth0.com/docs/protocols/oidc/openid-connect-discovery))\n* `client_id` : The Auth0 `client_id` generated when the Auth0\n  [application](https://auth0.com/docs/applications) was created in the\n  prerequisites\n* `idtoken_for_roles_url` : The URL of the ID Token For Roles API. This URL\n  comes from the location that the user's organization has deployed the\n  [idtoken_for_roles](/cloudformation) API. This API lets a user exchange an ID \n  token for a list of groups and roles that they have rights to. This URL should\n  be the base URL of the API, ending in `/`\n\nAdditional optional settings that can be configured in the config file are\n \n* `scope` : A space delimited list of\n  [OpenID Connect Scopes](https://auth0.com/docs/scopes/current/oidc-scopes).\n  For example `openid`. Avoid including a scope which passes too much data which\n  will exceed the maximum AWS allowed size of the ID Token (for example at\n  Mozilla we neglect to include the raw full group list which is included in the\n  ID Token when the `https://sso.mozilla.com/claim/groups` scope is requested.\n* `output` : The output format for the tool to use. This must be one of the\n  following values : `envvar`, `awscli`, `shared`, `boto`, `js`. Full details on\n  these formats can be found in the [Output Formats](#output-formats) section\n  below\n* `print_role_arn` : Whether or not `maws` should display the AWS IAM Role ARN\n  on the command line. This can have values like `yes`, `no`, `true`, `false`\n\nThe resulting config would look something like this\n```ini\n[maws]\nclient_id = abcdefg\nidtoken_for_roles_url = https://roles-and-aliases.example/roles\nwell_known_url = http://auth.example.com/.well-known/openid-configuration\n```\n\n## Usage\n\nThere are various ways you can run `maws`. The tool can output environment\nvariable setting text to activate your AWS session inside your terminal. Here\nare some methods to use the tool.\n\n### Subcommand : `$(maws)`\n\nYou could run `maws` within a `$()` sub-shell and execute the results\n\n* Interactively prompt for which IAM role to assume\n  * `$(maws)`\n* Pass the IAM role to assume as a command line argument\n  * `$(maws --role-arn arn:aws:iam::123456789012:role/example-role)`\n* Not only enable command line access to AWS, also log into the web console\n  * `$(maws -w)`\n\n\u003e :warning: **Users of [YADR](https://github.com/skwp/dotfiles) and zsh**:\n\u003e Subcommands can result in a broken authentication flow, and so it is\n\u003e recommended that you use either process substitution or `eval`, as described\n\u003e below.\n\n### Process substitution : `source \u003c(maws)`\n\nThis uses [process substitution](http://tldp.org/LDP/abs/html/process-sub.html).\nHere are some examples of how you could run it\n\n`source \u003c(maws -w)`\n\n### Eval : `eval $(maws)`\n\nYou could eval the results\n\n`eval $(maws --role-arn arn:aws:iam::123456789012:role/example-role)`\n\n### Copy paste : `maws`\n\nTake the output of the command and copy paste it into your terminal\n\n`maws`\n\n### Using programmatically\n\nIn general, it is recommended to keep your code independent of `maws` by\nusing environmental variables such as `AWS_PROFILE` and letting the\nunderlying libraries read from your local AWS configuration. \n\nAll AWS SDKs automatically look for API keys in environment variables and AWS\nCLI config files that `maws` works well with.\n\nHowever, if you need to you can call maws and export the resulting credentials \nfor use in code, though it is discouraged.\n\nTo make `maws` output JSON credentials consumable by\n[boto3](https://github.com/boto/boto3) :\n\n```python\nimport boto3\nimport json\nfrom subprocess import Popen, PIPE\n\nif __name__ == \"__main__\":\n    with Popen([\"maws\", \"-o\", \"boto\"], stdout=PIPE) as proc:\n        boto_args = json.loads(proc.stdout.read())\n\n    s3_client = boto3.client('s3', **boto_args)\n\n    print(s3_client.list_buckets())\n```\n\nor as arguments in Javascript\n\n```javascript\nconst AWS = require(\"aws-sdk\");\nconst child_process = require(\"child_process\");\n\nconst botoArgs = JSON.parse(child_process.spawnSync(\"maws\", [\"-o\", \"js\"]).stdout);\n\nnew AWS.S3(botoArgs).listBuckets({}, (err, data) =\u003e {\n  console.log(data);\n});\n```\n\n## Output Formats\n\nThe Mozilla AWS CLI can use various methods to make the ephemeral API keys\navailable for use by AWS SDKs and the AWS CLI. These methods are set via either\nthe `-o / --output` command line argument or the `output` config file setting\n\n* `envvar` (default) : This output format sets environment variables with the\n  credentials. This sets `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. No\n  files are written to with this output format. This is the default output\n  format.\n* `awscli` : This output format stores credentials in the [`~/.aws/credentials`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)\n  file using a profile name based on the AWS account alias and IAM Role name.\n  For example, with the `yoyodyne-accounting` AWS account and the `TeamAP`\n  IAM Role, it would create a profile called `yoyodyne-accounting-TeamAP`. It\n  then sets the `AWS_PROFILE` environment variable to use this profile.\n* `shared` : This output format creates a dedicated `maws` credentials file,\n  for example in Linux `/home/username/.config/maws/credentials`. In this\n  credential file it creates a profile named as is described above in the\n  `awscli` output format. It then sets the AWS CLI/SDK environment variable\n  `AWS_SHARED_CREDENTIALS_FILE` to point to this dedicated credentials file\n  and `AWS_PROFILE` to the created profile name. The benefit of this output\n  format is that the native AWS CLI/SDK credentials file is untouched. If you\n  use a mix of ephemeral API keys using `maws` and long lived API keys that\n  map to IAM users, using the `shared` output ensures that any hand created\n  profiles in the `~/.aws/credentials` aren't potentially overwritten if they\n  have the same profile name as one used by `maws`\n* `boto` : Outputs JSON credentials in a format expected by [boto3](https://github.com/boto/boto3)\n  to stdout. This mode of integration with boto3 is discouraged, and the native\n  environment variable based or `~/.aws/credentials` based output formats are\n  preferred.\n* `js` : Outputs JSON credentials in a format expected by the\n  [AWS JavaScript SDK](https://github.com/aws/aws-sdk-js) to stdout. This mode\n  of integration with the AWS JavaScript SDK is discouraged, and the native\n  environment variable based or `~/.aws/credentials` based output formats are\n  preferred.\n\n### Troubleshooting\n\nIf you run into errors with decrypting the ID token, it is likely that you are using an out-of-date version of Python or cryptographic libraries. This can usually be fixed by running a more Python-native cryptographic library, installed via:\n\n`pip install --upgrade cryptography python-jose[cryptography]`\n\n## Sequence diagram\n\n[\u003cimg src=\"https://raw.githubusercontent.com/mozilla-iam/mozilla-aws-cli/master/docs/img/sequence.png\" width=\"100%\"\u003e](docs/img/sequence.md)\n\n## Details\n\nThis is a collection of technical details that we've decided or discovered in\nbuilding the mozilla-aws-cli\n\n* The user group list should be set in the OIDC claim as a list of groups\n  instead of a string with delimiters\n  * The `amr` claim allows for passing a list\n  * By using a list we don't need to worry about choosing a delimiter and\n    ensuring the delimiter is not allowed in the group name\n  * The [`ForAnyValue:StringLike`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String)\n    IAM policy condition operator doesn't need `*` wildcard characters in the\n    value since each group listed in the policy is a full group name which will\n    match a full group name in the list passed in `amr`\n* Even if you only wish to allow a single user group to assume a role, you still\n  must use the [`ForAnyValue:StringLike`](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html)\n  operator, not the `StringLike` operator. It's not clear why this is the case.\n* AWS has a maximum size that either the `id_token` or the `amr` assertion can\n  be.\n  * When this maximum size is exceeded AWS returns the error \n    `PackedPolicyTooLarge Serialized token too large for session`\n  * It's possible that the size limit is not able to be determined because\n    AWS performs a packing or compression step on it's size such that the size\n    of the `amr` assertion doesn't have a linear relationship with the size\n    of the object AWS tests against it's limit\n  * For example a `amr` value that is a list of 30 group names with an \n    `id_token` length of 800 characters triggers this error.\n* Currently, when a user logs into Auth0 for the first time and performs a Duo\n  MFA authentication, Auth0 overwrites the `amr` assertion that we create with\n  a new list containing a single element `[\"mfa\"]`. We've \n  [opened a bug with Auth0](https://support.auth0.com/tickets/00427989) in hopes\n  that they will change to *appending* to the `amr` assertion.\n  * If they make this change, the `amr` assertion would, in that case, contain\n    the list of groups *and* what would appear like a group called `mfa`. We\n    would need to do some checks to ensure that nobody starts using a real group\n    called `mfa`\n* The `amr` assertion in the OIDC spec isn't supposed to be used to pass a list\n  of groups. It's also not supposed to be used to pass a string like \n  `authenticated` like AWS does with cognito.\n  * The [purpose of the `amr` assertion](https://tools.ietf.org/html/rfc8176#section-1)\n    is to provide an RP with a list of \n    \u003e identifiers for authentication methods used in the authentication\n  * [RFC8176](https://tools.ietf.org/html/rfc8176#page-4) states\n    \u003e The \"amr\" values defined by this specification are not intended to be\n    \u003e an exhaustive set covering all use cases.  Additional values can and\n    \u003e will be added to the registry by other specifications.\n  * The RFC then goes on to define a [list of allowed values](https://tools.ietf.org/html/rfc8176#section-2)\n    which make it clear that `authenticated` or group names are not correct\n  * Given this, it's possible that down the road\n    * AWS will begin to use a different assertion than `amr` to conform to the\n      spec\n    * Auth0 will disallow setting non conforming values in `amr`\n  * If this happens we would need to change how we do things\n* By having an Auth0 rule that queries some external resource (such as the\n  group to role mapping file) and added delay to login is introduced and a risk\n  of a problem in fetching the mapping file which could cause login to fail\n* We use the `amr` assertion because it appears to be the only way to pass data\n  to AWS\n  * The [documentation](https://docs.aws.amazon.com/it_it/IAM/latest/UserGuide/list_awssecuritytokenservice.html#awssecuritytokenservice-web-identity-provider_oaud)\n    indicates that there are 3 assertions that can be used in IAM policy\n    conditions, `aud` `oaud` and `sub`\n  * In testing we've found that\n    `aud` is passed and we use it for the Auth0 client ID\n    `sub` is passed and we use it for the Auth0 username\n    `oaud` is not passed\n    `amr` is passed\n* By passing a group list in the `amr` assertion we take on the following risks\n  * At some point some user may try to login to AWS with SSO and login will fail\n    due to the `PackedPolicyTooLarge` error. This will occur when\n    * Enough AWS account holders across our many AWs accounts create IAM \n      policies which allow a diverse set of user groups to access various roles\n    * This unlucky user has access to so many different AWS accounts and roles\n      because they work across many teams that the union of all the AWS groups\n      which grant them access to the various roles exceeds the\n      `PackedPolicyTooLarge` limit\n  * We can't be sure at the point that we send the assertion that it will fail\n    because we can't know the hard limit on the size of the `amr` assertion or\n    the `id_token` in total\n* We plan to try to log and track users experience over time to see if the\n  group list size issue is becoming a problem. To do so we'll want to see\n  * The size of the `amr` assertion being passed each time a user logs in\n  * If AWS ever returns a `PackedPolicyTooLarge` error\n\n### Supported IAM Policy Features\n\nThe Auth0 rule which finds the intersection in the groups a user is a member of\nwith the union of all groups used in all AWS accounts IAM policies won't\nsupport [all IAM policy operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html#Conditions_String).\nHere are the various use cases and whether they are supported or not\n\n#### Supported\nAn AWS account holder wants to\n\n* enable users that are members of group \"foo\" to assume role \n  arn:aws:iam::123456789012:role/baz\n  * supported\n  * `StringLike`, `StringEquals`\n* enable users that are members of group \"foo\" as well as users that are members\n  of group \"bar\" to assume role arn:aws:iam::123456789012:role/baz\n  * supported\n  * `StringLike`, `StringEquals` for a list of values\n* enable users that are members of any group like \"fo*\" to assume role\n  arn:aws:iam::123456789012:role/baz\n  * supported\n  * `StringLike` with wildcards\n\n#### Not Supported\nAn AWS account holder wants to\n\n* enable users that are members of both group \"foo\" and group \"bar\" to assume\n  role arn:aws:iam::123456789012:role/baz\n  * not supported\n  * multiple `StringLike` or `StringEquals` conditions\n* enable users that are members of group \"foo\" but not allow users that are\n  members of group \"FOO\" to assume role arn:aws:iam::123456789012:role/baz\n  * not supported\n  * when assembling the group list to pass to AWS, we will do case insensitive\n    matching. Additionally, there shouldn't ever be a case where two groups\n    exist with the same characters in their name but different cases\n  * multiple `StringEquals` conditions where the values differ only in case\n* enable users that are not members of group \"bar\" to assume role\n  arn:aws:iam::123456789012:role/baz\n  * not supported\n  * `StringNotEquals`, `StringNotLike`\n* enable users that are members of group \"foo\" but not members of group \"bar\"\n  to assume role arn:aws:iam::123456789012:role/baz\n  * not supported\n  * multiple conditions including `StringNotEquals`, `StringNotLike`\n\n## Troubleshooting\n\nIf you don't see a role listed in the role picker which you would expect to have\naccess to, possible reasons are :\n\n* The IAM role was recently modified and\n  1. the hourly scanner hasn't yet run to update the list of available roles.\n  2. the list of available roles is current but the API that sits in front of\n     it is using an out of date cached copy\n  3. the list of available roles is current but the Auth0 rule is using an out\n     of date cached copy of the available roles and as a result, isn't passing\n     an \"amr\" claim with your current complete list of groups\n  * If the cause is 1 or 2 you can still assume that role, just not using this\n    menu. Instead pass the role ARN on the command line.\n* The conditions in the role don't allow you to access it because\n  * The role has a different \"Principal\" \"Federated\" value than it should\n    * Dev\n      * Federated : `arn:aws:iam::*:oidc-provider/auth.mozilla.auth0.com/`\n      * Aud : `N7lULzWtfVUDGymwDs0yDEq6ZcwmFazj`\n    * Prod\n      * Federated : `arn:aws:iam::*:oidc-provider/auth-dev.mozilla.auth0.com/`\n      * Aud : `xRFzU2bj7Lrbo3875aXwyxIArdkq1AOT`\n  * The role has the wrong \"Action\" value which should be\n    * `sts:AssumeRoleWithWebIdentity`\n  * The role has an \"aud\" condition that doesn't match the Auth0 client ID\n    being passed in the \"aud\" claim from Auth0\n    * Dev : `xRFzU2bj7Lrbo3875aXwyxIArdkq1AOT`\n    * Prod : `N7lULzWtfVUDGymwDs0yDEq6ZcwmFazj`\n  * The key name of the \"aud\" condition is incorrect\n    * Dev : `auth-dev.mozilla.auth0.com/:aud`\n    * Prod : `auth.mozilla.auth0.com/:aud`\n  * The key name of the \"amr\" condition is incorrect\n    * Dev : `auth-dev.mozilla.auth0.com/:amr`\n    * Prod : `auth.mozilla.auth0.com/:amr`\n  * You aren't a member of any of the groups listed in \"amr\" conditions\n* Your AWS account does not delegate security auditing rights to the Enterprise\n  Information Security team so the group role map builder can't scan the IAM\n  roles in your AWS account\n* There is a bug\n  * in the Auth0 rule that filters the list of groups that you are a member of\n    such that the \"amr\" claim returned to you is missing a group that you need\n    to meet an IAM Role condition\n  * in the group role map builder that produces the map of groups to roles to\n    enable the Auth0 rule and the role picker menu to know which roles are\n    available to you\n  * in the ID token for role API that allows you to exchange your ID token for\n    a list of roles so that the role picker can show you a menu of available\n    roles\n\n## Development\n\nWhen developing the tool and testing you can run it without installing it like\nthis\n\n`python -m mozilla_aws_cli.cli --role-arn arn:aws:iam::123456789012:role/example-role`\n\nNote : You must run `python -m mozilla_aws_cli.cli` instead of\n`python mozilla_aws_cli/cli.py` because mozilla_aws_cli uses absolute imports.\n\n## Creating enterprise / organization configuration\n\nIf you want to deploy the Mozilla AWS CLI across your organization and establish\ndefault configuration values without requiring users to create config files you\ncan do so by implementing a standard `mozilla_aws_cli_config` module.\n\nHere are the steps assuming an example organization called `Yoyodyne`\n\n1. Create a new code repo. A good name would be `mozilla-aws-cli-yoyodyne`\n2. In that repo create a `setup.py`\n   ```python\n   #!/usr/bin/env python\n\n   from setuptools import setup\n\n   setup(\n       name=\"mozilla-aws-cli-yoyodyne\",\n       description=\"Yoyodyne specific deployment of the mozilla_aws_cli\",\n       install_requires=[\"mozilla_aws_cli\"],\n       packages=[\"mozilla_aws_cli_config\"],\n       url=\"https://github.com/yoyodyne/mozilla-aws-cli-yoyodyne\",\n       version=\"1.0.0\",\n   )\n   ```\n   * `install_requires` depends on the `mozilla_aws_cli` to ensure that if you\n     instruct the user to `pip install mozilla-aws-cli-yoyodyne` they will get\n     the Yoyodyne config and the tool\n3. Create a directory called `mozilla_aws_cli_config`\n   * This is the reserved / well known module name that every organization can\n     implement. This name must be `mozilla_aws_cli_config` exactly and not\n     include any part of your organization name (e.g. Yoyodyne)\n4. Within that `mozilla_aws_cli_config` directory create a single `__init__.py`\n   file. This will contain your organizations default configuration settings\n5. In this `__init__.py` file create a single variable called `config`\n   containing your organizations default configuration settings.\n   * Yoyodyne's `__init__.py` might look like\n     ```python\n     config = {\n         \"client_id\": \"abcdefghiJKLMNOPQRSTUVWXYZ012345\",\n         \"idtoken_for_roles_url\": \"https://roles-and-aliases.sso.yoyodyne.com/roles\",\n         \"well_known_url\": \"https://auth.yoyodyne.auth0.com/.well-known/openid-configuration\"\n     }\n     ```\n\nThe resulting repository called `mozilla-aws-cli-yoyodyne` would look like this\n\n```\nmozilla-aws-cli-yoyodyne/\n├── mozilla_aws_cli_config\n│   └── __init__.py\n└── setup.py\n```\n\n## Other projects in this space\n\n* https://github.com/aidan-/aws-cli-federator\n* https://github.com/Nike-Inc/gimme-aws-creds\n* https://github.com/sportradar/aws-azure-login\n* https://github.com/oktadeveloper/okta-aws-cli-assume-role\n* https://github.com/jmhale/okta-awscli\n* https://github.com/prolane/samltoawsstskeys\n* https://github.com/physera/onelogin-aws-cli\n* https://github.com/kxseven/axe/blob/master/bin/subcommands/axe-token-krb5formauth-create\n* https://github.com/openstandia/aws-cli-oidc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-iam%2Fmozilla-aws-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla-iam%2Fmozilla-aws-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-iam%2Fmozilla-aws-cli/lists"}