{"id":13682230,"url":"https://github.com/segmentio/aws-okta","last_synced_at":"2025-04-30T07:31:01.779Z","repository":{"id":44406592,"uuid":"91728685","full_name":"segmentio/aws-okta","owner":"segmentio","description":"aws-vault like tool for Okta authentication","archived":true,"fork":false,"pushed_at":"2021-01-04T16:56:37.000Z","size":12984,"stargazers_count":537,"open_issues_count":0,"forks_count":227,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-08-02T13:33:51.688Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/segmentio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2017-05-18T19:07:59.000Z","updated_at":"2024-06-20T14:56:55.000Z","dependencies_parsed_at":"2022-07-12T18:20:45.402Z","dependency_job_id":null,"html_url":"https://github.com/segmentio/aws-okta","commit_stats":null,"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Faws-okta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Faws-okta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Faws-okta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Faws-okta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/segmentio","download_url":"https://codeload.github.com/segmentio/aws-okta/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224201908,"owners_count":17272663,"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":[],"created_at":"2024-08-02T13:01:42.581Z","updated_at":"2024-11-12T01:31:22.898Z","avatar_url":"https://github.com/segmentio.png","language":"Go","funding_links":[],"categories":["Go","Security Enabling Tools"],"sub_categories":[],"readme":"# aws-okta\n\n`aws-okta` allows you to authenticate with AWS using your Okta credentials.\n\n⚠️ As per [#278](https://github.com/segmentio/aws-okta/issues/278), development and maintenance of `aws-okta` is halted. If you're not already using it, now would be a bad time to start. ⚠️\n\n## Installing\n\n[See the wiki for more installation options.](https://github.com/segmentio/aws-okta/wiki/Installation)\n\n### MacOS\n\nYou can install with `brew`:\n\n```bash\n$ brew install aws-okta\n```\n\nShout-out to the fine maintainers of [the core formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aws-okta.rb).\n\n### Linux\n\n[Download a binary from our release page](https://github.com/segmentio/aws-okta/releases), or [see the wiki for more installation options like deb/rpm packages](https://github.com/segmentio/aws-okta/wiki/Installation).\n\n### Windows\n\nSee [docs/windows.md](docs/windows.md) for information on getting this working with Windows.\n\n## Usage\n\n### Adding Okta credentials\n\n```bash\n$ aws-okta add\n```\n\nThis will prompt you for your Okta organization, custom domain, region, username, and password. These credentials will then be stored in your keyring for future use.\n\n### Exec\n\n```bash\n$ aws-okta exec \u003cprofile\u003e -- \u003ccommand\u003e\n```\n\nExec will assume the role specified by the given aws config profile and execute a command with the proper environment variables set.  This command is a drop-in replacement for `aws-vault exec` and accepts all of the same command line flags:\n\n```bash\n$ aws-okta help exec\nexec will run the command specified with aws credentials set in the environment\n\nUsage:\n  aws-okta exec \u003cprofile\u003e -- \u003ccommand\u003e\n\nFlags:\n  -a, --assume-role-ttl duration   Expiration time for assumed role (default 1h0m0s)\n  -h, --help                       help for exec\n  -t, --session-ttl duration       Expiration time for okta role session (default 1h0m0s)\n\nGlobal Flags:\n  -b, --backend string   Secret backend to use [kwallet secret-service file] (default \"file\")\n  -d, --debug            Enable debug logging\n```\n\n### Exec for EKS and Kubernetes\n\n`aws-okta` can also be used to authenticate `kubectl` to your AWS EKS cluster. Assuming you have [installed `kubectl`](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html), [setup your kubeconfig](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html) and [installed `aws-iam-authenticator`](https://docs.aws.amazon.com/eks/latest/userguide/configure-kubectl.html), you can now access your EKS cluster with `kubectl`. Note that on a new cluster, your Okta CLI user needs to be using the same assumed role as the one who created the cluster. Otherwise, your cluster needs to have been configured to allow your assumed role.\n\n```bash\n$ aws-okta exec \u003cprofile\u003e -- kubectl version --short\n```\n\nLikewise, most Kubernetes projects should work, like Helm and Ark.\n\n```bash\n$ aws-okta exec \u003cprofile\u003e -- helm version --short\n```\n\n### Configuring your aws config\n\n`aws-okta` assumes that your base role is one that has been configured for Okta's SAML integration by your Okta admin. Okta provides a guide for setting up that integration [here](https://support.okta.com/help/servlet/fileField?retURL=%2Fhelp%2Farticles%2FKnowledge_Article%2FAmazon-Web-Services-and-Okta-Integration-Guide\u0026entityId=ka0F0000000MeyyIAC\u0026field=File_Attachment__Body__s).  During that configuration, your admin should be able to grab the AWS App Embed URL from the General tab of the AWS application in your Okta org.  You will need to set that value in your `~/.aws/config` file, for example:\n\n```ini\n[okta]\naws_saml_url = home/amazon_aws/0ac4qfegf372HSvKF6a3/965\n```\n\nNext, you need to set up your base Okta role.  This will be one your admin created while setting up the integration.  It should be specified like any other aws profile:\n\n```ini\n[profile okta-dev]\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\nregion = \u003cregion\u003e\n```\n\nYour setup may require additional roles to be configured if your admin has set up a more complicated role scheme like cross account roles.  For more details on the authentication process, see the internals section.\n\n#### A more complex example\n\nThe `aws_saml_url` can be set in the \"okta\" ini section, or on a per profile basis. This is useful if, for example, your organization has several Okta Apps (i.e. one for dev/qa and one for prod, or one for internal use and one for integrations with third party providers). For example:\n\n```ini\n[okta]\n# This is the \"default\" Okta App\naws_saml_url = home/amazon_aws/cuZGoka9dAIFcyG0UllG/214\n\n[profile dev]\n# This profile uses the default Okta app\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\n\n[profile integrations-auth]\n# This is a distinct Okta App\naws_saml_url = home/amazon_aws/woezQTbGWUaLSrYDvINU/214\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\n\n[profile vendor]\n# This profile uses the \"integrations-auth\" Okta app combined with secondary role assumption\nsource_profile = integrations-auth\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003csecondary-role-name\u003e\n\n[profile testaccount]\n# This stores the Okta session in a separate item in the Keyring.\n# This is useful if the Okta session is used or modified by other applications\n# and needs to be isolated from other sessions. It is also useful for\n# development versions or multiple versions of aws-okta running.\nokta_session_cookie_key = okta-session-cookie-test\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\n```\n\nThe configuration above means that you can use multiple Okta Apps at the same time and switch between them easily.\n\n#### Multiple Okta accounts\nsetup accounts:\n```ini\naws-okta add --account=account-a\naws-okta add --account=account-b\n```\n\ndefine keyring key for each profile:\n```ini\n[profile account-a]\n# This is a distinct Okta App\naws_saml_url = home/amazon_aws/woezQTbGWUaLSrYDvINU/214\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\nokta_account_name = account-a\n\n[profile account-b]\naws_saml_url = home/amazon_aws/woezQTbGaDAA4rYDvINU/123\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\nokta_account_name = account-b\n```\n\n#### Configuring Okta assume role and AWS assume role TTLs\n\nThe default TTLs for both the initial SAML assumed role and secondary AWS assumed roles are 1 hour.  This means that AWS credentials will expire every hour.\n\n* *session-ttl*: Duration of initial role assumed by Okta\n* *assume-role-ttl*: Duration of second role assumed\n\nIn addition to specifying session and AWS assume role TTLs with command-line flags, they can be set using environment variables.\n\n```bash\nexport AWS_SESSION_TTL=1h\nexport AWS_ASSUME_ROLE_TTL=1h\n```\n\nThe AWS assume role TTL can also be set per-profile in the aws config:\n\n```ini\n# Example with an initial and secondary role that are configured with a max session duration of 12 hours\n[profile ttldemo]\naws_saml_url = home/amazon_aws/cuZGoka9dAIFcyG0UllG/214\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003cokta-role-name\u003e\nsession_ttl = 12h\n\n[profile ttldemo-role]\nsource_profile = ttldemo\nrole_arn = arn:aws:iam::\u003caccount-id\u003e:role/\u003csecondary-role-name\u003e\nassume_role_ttl = 12h\n```\n\n#### Multi-factor Authentication (MFA) configuration\n\nIf you have a single MFA factor configured, that factor will be automatically selected.  By default, if you have multiple available MFA factors, then you will be prompted to select which one to use.  However, if you have multiple factors and want to specify which factor to use, you can do one of the following:\n\n* Specify on the command line with `--mfa-provider` and `--mfa-factor-type`\n* Specify with environment variables `AWS_OKTA_MFA_PROVIDER` and `AWS_OKTA_MFA_FACTOR_TYPE`\n* Specify in your aws config with `mfa_provider` and `mfa_factor_type`\n\n### Shell completion\n\n`aws-okta` provides shell completion support for BASH and ZSH via the `aws-okta completion` command.\n\n## Backends\n\nWe use 99design's keyring package that they use in `aws-vault`.  Because of this, you can choose between different pluggable secret storage backends just like in `aws-vault`.  You can either set your backend from the command line as a flag, or set the `AWS_OKTA_BACKEND` environment variable.\n\nFor Linux / Ubuntu add the following to your bash config / zshrc etc:\n```\nexport AWS_OKTA_BACKEND=secret-service\n```\n\n## --session-cache-single-item aka AWS_OKTA_SESSION_CACHE_SINGLE_ITEM (alpha)\n\nThis flag enables a new secure session cache that stores all sessions in the same keyring item. For macOS users, this means drastically fewer authorization prompts when upgrading or running local builds.\n\nNo provision is made to migrate sessions between session caches.\n\nImplemented in [https://github.com/segmentio/aws-okta/issues/146](#146).\n\n## Local Development\n\nIf you're developing in Linux, you'll need to get `libusb`. For Ubuntu, install the libusb-1.0-0-dev or use the `Dockerfile` provided in the repo.\n\n## Running Tests\n\n`make test`\n\n## Releasing\n\nPushing a new tag will cause Circle to automatically create and push a linux release.  After this is done, you should run (from a mac):\n\n```bash\n$ export CIRCLE_TAG=`git describe --tags`\n$ make release-mac\n```\n\n## Analytics\n\n`aws-okta` includes some usage analytics code which Segment uses internally for tracking usage of internal tools.  This analytics code is turned off by default, and can only be enabled via a linker flag at build time, which we do not set for public github releases.\n\n## Internals\n\n### Authentication process\n\nWe use the following multiple step authentication:\n\n- Step 1 : Basic authentication against Okta\n- Step 2 : MFA challenge if required\n- Step 3 : Get AWS SAML assertion from Okta\n- Step 4 : Assume base okta role from profile with the SAML Assertion\n- Step 5 : Assume the requested AWS Role from the targeted AWS account to generate STS credentials\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsegmentio%2Faws-okta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsegmentio%2Faws-okta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsegmentio%2Faws-okta/lists"}