{"id":13820329,"url":"https://github.com/rapid7/awsaml","last_synced_at":"2025-04-04T08:08:38.595Z","repository":{"id":3717637,"uuid":"50682822","full_name":"rapid7/awsaml","owner":"rapid7","description":"Awsaml is an application for providing automatically rotated temporary AWS credentials. ","archived":false,"fork":false,"pushed_at":"2025-01-30T15:36:11.000Z","size":5987,"stargazers_count":141,"open_issues_count":9,"forks_count":45,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-28T07:08:40.062Z","etag":null,"topics":["aws","electron","javascript","okta","saml","sso"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rapid7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-29T18:37:06.000Z","updated_at":"2025-02-25T02:40:55.000Z","dependencies_parsed_at":"2023-07-05T18:49:12.592Z","dependency_job_id":"bc97e705-e008-40e4-89a4-104d082613df","html_url":"https://github.com/rapid7/awsaml","commit_stats":{"total_commits":329,"total_committers":22,"mean_commits":"14.954545454545455","dds":0.7325227963525835,"last_synced_commit":"5c50280ac47dd89a3639733ddd9c96fd2d63d43f"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fawsaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fawsaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fawsaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fawsaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapid7","download_url":"https://codeload.github.com/rapid7/awsaml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142066,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","electron","javascript","okta","saml","sso"],"created_at":"2024-08-04T08:01:01.490Z","updated_at":"2025-04-04T08:08:38.577Z","avatar_url":"https://github.com/rapid7.png","language":"JavaScript","readme":"# Awsaml\n\n[![coverage](https://coveralls.io/repos/github/rapid7/awsaml/badge.svg?branch=master)](https://coveralls.io/github/rapid7/awsaml?branch=master)\n\nAwsaml is an application for providing automatically rotated temporary [AWS][]\ncredentials. Credentials are stored in `~/.aws/credentials` so they can be used\nwith AWS SDKs. Credentials are valid for one hour and are rotated every hour\nwhile the application's running.\n\nIn order to rotate credentials, Awsaml takes the following actions\n\n1. Authenticates the user with their identity provider.\n2. Reads the SAML authentication response returned from the identity provider.\n3. Generates new temporary AWS keys by calling the [AssumeRoleWithSAML][] API.*\n4. Writes the new temporary credentials to disk.\n\nThis flow repeats every hour so the user always has a valid set of AWS keys\nwhile the application's running. Awsaml reuses the SAML response from the\nidentity provider, so the user doesn't need to reauthenticate every time.\n\nYou can grab prebuilt binaries for Mac, Linux, and Window from [the releases page][releases].\n\n*This API is used to fetch credentials if the Okta SAML + AWS configuration is used. Alternatively, Awsaml also supports the Just In Time IAM tool in Rapid7's InsightCloudSec product.\n\n## Configuration\n\nConfiguring Awsaml is a multi-step process that involves a bit of back and forth\nbetween Amazon and your identity provider. The general flow looks like this\n\n1. Create a SAML application in your identity provider.\n2. Create a SAML identity provider in AWS.\n3. Create an IAM role in AWS.\n4. Update the SAML application with ARNs.\n5. Run Awsaml and give it your application's metadata.\n\n### 1. Create a SAML application in your identity provider\n\nThe only tested identity provider is [Okta][]. To use Awsaml with Okta, you'll\nneed to create a SAML 2.0 application in Okta with the following settings\n\n#### SAML Settings\n\n| Name                       | Value                                  |\n|----------------------------|----------------------------------------|\n| Single Sign On URL         | http://localhost:2600/sso/saml         |\n| Recipient URL              | http://localhost:2600/sso/saml         |\n| Destination URL            | http://localhost:2600/sso/saml         |\n| Audience Restriction       | http://localhost:2600/sso/saml         |\n| Default Relay State        |                                        |\n| Name ID Format             | EmailAddress                           |\n| Response                   | Signed                                 |\n| Assertion Signature        | Signed                                 |\n| Signature Algorithm        | RSA_SHA256                             |\n| Digest Algorithm           | SHA256                                 |\n| Assertion Encryption       | Unencrypted                            |\n| SAML Single Logout         | Disabled                               |\n| authnContextClassRef       | PasswordProtectedTransport             |\n| Honor Force Authentication | Yes                                    |\n| SAML Issuer ID             | http://www.okta.com/${org.externalKey} |\n\nOnce Okta's created your application, it will show you setup instructions.\n\nAmong those instructions will be a URL for a generated XML metadata document\nthat will look something like this:\n\n```\nhttps://www.okta.com/app/{APP_ID}/sso/saml/metadata\n```\n\nWhere `APP_ID` is the application ID Okta has assigned to your newly created\napp.\n\nYou should do two things with this url:\n\n1. Copy the url and store it somewhere locally because you will need to provide\n   it to the Awsaml desktop application you run later.\n2. Download the contents of the url to a file on disk because you will need to\n   supply that file when you create an identity provider in AWS.\n\n#### A note on naming things (if you are using Okta)\n\nIn the next two steps, you will create and name an identity provider and a role.\nBe sure to choose short names (fewer than 28 characters between the two).\n\nIn the step after you create the identity provider and the role, you will need\nto take the ARNs for the identity provider and role and submit them to Okta.\nHowever, the field into which you will paste these values on the Okta website\nhas a 100 character limit which is not immediately evident.\n\nYou will need to provide a string in the format:\n\n```\n{ROLE_ARN},{IDENTITY_PROVIDER_ARN}\n```\n\nThe `ROLE_ARN` will be in this format:\n\n```\narn:aws:iam::{ACCOUNT_ID}:role/{ROLE_NAME}\n```\n\nWhere the `ACCOUNT_ID` is 12 digits long, and the `ROLE_NAME` is as long as you\nwant it to be.\n\nThe `IDENTITY_PROVIDER_ARN` will be in this format:\n\n```\narn:aws:iam::{ACCOUNT_ID}:saml-provider/{PROVIDER_NAME}\n```\n\nWhere the `ACCOUNT_ID` is 12 digits long, and the `PROVIDER_NAME` is as long as\nyou want it to be.\n\nThus, when combined, the two ARNs will take up 72 characters without considering\nthe number of characters that the names have.\n\n```\narn:aws:iam::XXXXXXXXXXXX:role/,arn:aws:iam::XXXXXXXXXXXX:saml-provider/\n```\n\nAs a consequence, between the name you give to the identity provider and the name\nyou give to the role, you can only use up to 28 characters.\n\n### 2. Create a SAML identity provider in AWS\n\nFollow [Amazon's documentation for creating a SAML identity provider][saml-provider],\nin which you will need to upload the metadata document you downloaded in the\nprevious step.\n\nSave the ARN for your identity provider so you can configure it in your\napplication.\n\n### 3. Create an IAM role in AWS\n\nFollow [Amazon's documentation for creating an IAM role][iam-role] with the\nfollowing modifications:\n\n1. In step 2 \"Select Role Type\"\n    1. After clicking \"Role for Identity Provider Access\", choose \"Grant API\n       access to SAML identity providers\"\n1. In step 3 \"Establish Trust\"\n    1. For 'SAML provider', choose the provider you previous set up\n    2. For 'Attribute', choose SAML:iss\n    3. For 'Value', supply the Issuer URL provided by Okta when you created the\n       application\n\nThe permissions in this role will be the ones users are granted by their the\nAWS tokens Awsaml generates.\n\nOnce the role's created, a trust relationship should have been established\nbetween your role and the SAML identity provider you created. If not, you will\nneed to set up a trust relationship between it and your SAML identity provider\nmanually. Here's an example of the JSON policy document for that relationship.\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [{\n    \"Sid\": \"awsKeysSAML\",\n    \"Effect\": \"Allow\",\n    \"Principal\": {\n      \"Federated\": \"arn:aws:iam:saml-provider\"\n    },\n    \"Action\": \"sts:AssumeRoleWithSAML\",\n    \"Condition\": {\n      \"StringEquals\": {\n        \"SAML:iss\": \"issuer\"\n      }\n    }\n  }]\n}\n```\n\nReplace the \"issuer\" value for the \"SAML:iss\" key in the policy document with\nthe issuer URL for your application. Replace the \"arn:aws:iam:saml-provider\"\nvalue for the \"Federated\" key in the policy document with the ARN for your\nSAML identity provider.\n\nSave the ARN for the role so you can configure it in your application.\n\n### 4. Update the SAML application with ARNs\n\nNow that you have ARNs for the AWS identity provider and role, you can go back\ninto Okta and add them to your application. Edit your application to include the\nfollowing attributes.\n\n#### Attribute Statements\n\n| Name                                                   | Name Format | Value                                 |\n|--------------------------------------------------------|-------------|---------------------------------------|\n| https://aws.amazon.com/SAML/Attributes/Role            | Unspecified | arn:aws:iam:role,arn:aws:iam:provider |\n| https://aws.amazon.com/SAML/Attributes/RoleSessionName | Unspecified | ${user.email}                         |\n\nReplace the \"arn:aws:iam:role\" value with the ARN of the role in AWS you\ncreated. Replace the \"arn:aws:iam:provider\" value with the ARN of the identity\nprovider in AWS your created.\n\n\n##### Multiple Role Support\n\nTo support multiple roles, add multiple values to the `https://aws.amazon.com/SAML/Attributes/Role`\nattribute.  For example:\n\n```\narn:aws:iam:role1,arn:aws:iam:provider\narn:aws:iam:role2,arn:aws:iam:provider\narn:aws:iam:role3,arn:aws:iam:provider\n```\n\n*Special note for Okta users*:  Multiple roles must be passed as multiple values to a single\nattribute key.  By default, Okta serializes multiple values into a single value using commas.\nTo support multiple roles, you must contact Okta support and request that the\n`SAML_SUPPORT_ARRAY_ATTRIBUTES` feature flag be enabled on your Okta account.  For more details\nsee [this post](https://devforum.okta.com/t/multivalued-attributes/179).\n\n\n### 5. Run Awsaml and give it your application's metadata\n\nYou can find a prebuilt binary for Awsaml on [the releases page][releases]. Grab\nthe appropriate binary for your architecture and run the Awsaml application. It\nwill prompt you for a SAML metadata URL. Enter the URL you saved in step 1. If\nthe URL's valid, it will prompt you to log in to your identity provider. If the\nlogin's successful, you'll see temporary AWS credentials in the UI.\n\n## Building\n\nAwsaml is built using [Node][] and [Yarn 3][], so\nmake sure you've got a compatible versions installed. Then run Yarn to install dependencies and build Awsaml.\n\n```bash\nrm -rf node_modules/\nyarn install\nyarn build\n```\n\nThose commands will create a \"out\" folder with zipped binaries. If you only want to create binaries for specific platforms, you can set a `PLATFORM` environment\nvariable before building.\n\n```bash\nexport PLATFORM=linux\nyarn build\n```\n\nAllowed values for `PLATFORM` are `darwin`, `linux` and `win32`. You can build\nbinaries for multiple platforms by using a comma separated list.\n\n```bash\nexport PLATFORM=darwin,linux\nyarn build\n```\n\nSimilarly, if you want to\nspecify the build architecture, you can set a `ARCH`\nenvironment variable before building.\n\n```bash\nexport ARCH=universal\nexport PLATFORM=darwin\nyarn build\n```\n\nSupported architectures are `ia32`, `x64` , `armv7l`,\n`arm64`, `mips64el`, `universal`, or `all`.\n\n## Setup on macOS with Homebrew\n\nA caskfile is bundled with the repository, to install Awsaml with [Homebrew][] simply run:\n\n```\nwget https://raw.githubusercontent.com/rapid7/awsaml/master/brew/cask/awsaml.rb\nbrew install --cask awsaml.rb\n```\n\nThere might be an error and warning prompt but it should start succesfully downloading right after\nWhen download is succesfully installed, a `awsaml was successfully installed!` prompt is displayed\n\n## License\n\nAwsaml is licensed under a MIT License. See the \"LICENSE.md\" file for more\ndetails.\n\n## Special Thanks\n\n* [Tristan Harward] for the app icon.\n\n[AWS]: https://aws.amazon.com\n[AssumeRoleWithSAML]: http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html\n[releases]: https://github.com/rapid7/awsaml/releases\n[Okta]: https://www.okta.com\n[Node]: https://nodejs.org\n[Yarn 3]: https://yarnpkg.com\n[saml-provider]: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html\n[iam-role]: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html\n[Homebrew]: http://brew.sh/\n[Tristan Harward]: https://github.com/trisweb\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fawsaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapid7%2Fawsaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fawsaml/lists"}