{"id":13472110,"url":"https://github.com/kubernetes-sigs/aws-iam-authenticator","last_synced_at":"2026-04-01T20:38:29.593Z","repository":{"id":37759416,"uuid":"99036030","full_name":"kubernetes-sigs/aws-iam-authenticator","owner":"kubernetes-sigs","description":"A tool to use AWS IAM credentials to authenticate to a Kubernetes cluster","archived":false,"fork":false,"pushed_at":"2026-03-24T02:05:20.000Z","size":40156,"stargazers_count":2311,"open_issues_count":9,"forks_count":440,"subscribers_count":40,"default_branch":"master","last_synced_at":"2026-03-27T03:22:41.670Z","etag":null,"topics":["auth","aws","iam","k8s-sig-aws","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubernetes-sigs.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":null,"security":"SECURITY_CONTACTS","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-08-01T19:29:39.000Z","updated_at":"2026-03-24T05:51:57.000Z","dependencies_parsed_at":"2023-12-07T20:22:47.502Z","dependency_job_id":"d5789ed8-5df4-42cf-8a15-8313624980f2","html_url":"https://github.com/kubernetes-sigs/aws-iam-authenticator","commit_stats":{"total_commits":429,"total_committers":92,"mean_commits":4.663043478260869,"dds":0.8018648018648018,"last_synced_commit":"e9aa152ce7893bc76766783324af39b5882e588b"},"previous_names":["heptiolabs/kubernetes-aws-authenticator","heptio/authenticator","heptio/aws-iam-authenticator"],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/kubernetes-sigs/aws-iam-authenticator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-iam-authenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-iam-authenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-iam-authenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-iam-authenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubernetes-sigs","download_url":"https://codeload.github.com/kubernetes-sigs/aws-iam-authenticator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes-sigs%2Faws-iam-authenticator/sbom","scorecard":{"id":461772,"data":{"date":"2025-08-11","repo":{"name":"github.com/kubernetes-sigs/aws-iam-authenticator","commit":"e3ebae373b0104e2801eba207ab735656d8a9368"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":6.9,"checks":[{"name":"Maintained","score":10,"reason":"30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","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":"Token-Permissions","score":9,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/create-release.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/deps.yml:6","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":"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":"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":"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":"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":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/create-release.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/create-release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/create-release.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/create-release.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/create-release.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/create-release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deps.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/deps.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deps.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/deps.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deps.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/deps.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/deps.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/kubernetes-sigs/aws-iam-authenticator/deps.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:17","Warn: containerImage not pinned by hash: Dockerfile:26","Warn: containerImage not pinned by hash: Dockerfile:28","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   2 third-party GitHubAction dependencies pinned","Info:   0 out of   3 containerImage dependencies pinned","Info:   1 out of   1 goCommand 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":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache 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":"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":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/kubernetes-sigs/.github/SECURITY.md:1","Info: Found linked content: github.com/kubernetes-sigs/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/kubernetes-sigs/.github/SECURITY.md:1","Info: Found text in security policy: github.com/kubernetes-sigs/.github/SECURITY.md:1"],"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":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/create-release.yml:12"],"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":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v0.7.5 not signed: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/236670122","Warn: release artifact v0.7.4 not signed: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/230622297","Warn: release artifact v0.7.3 not signed: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/226293816","Warn: release artifact v0.7.2 not signed: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/215559411","Warn: release artifact v0.7.1 not signed: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/213209977","Warn: release artifact v0.7.5 does not have provenance: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/236670122","Warn: release artifact v0.7.4 does not have provenance: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/230622297","Warn: release artifact v0.7.3 does not have provenance: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/226293816","Warn: release artifact v0.7.2 does not have provenance: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/215559411","Warn: release artifact v0.7.1 does not have provenance: https://api.github.com/repos/kubernetes-sigs/aws-iam-authenticator/releases/213209977"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 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"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3521","Warn: Project is vulnerable to: GO-2025-3547"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T11:18:31.958Z","repository_id":37759416,"created_at":"2025-08-19T11:18:31.958Z","updated_at":"2025-08-19T11:18:31.958Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: 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":["auth","aws","iam","k8s-sig-aws","kubernetes"],"created_at":"2024-07-31T16:00:51.987Z","updated_at":"2026-04-01T20:38:29.583Z","avatar_url":"https://github.com/kubernetes-sigs.png","language":"Go","funding_links":[],"categories":["Go","HarmonyOS","Projects","aws","Security","Security \u0026 Compliance"],"sub_categories":["Windows Manager","Identity and Access Management","[Jenkins](#jenkins)"],"readme":"# AWS IAM Authenticator for Kubernetes\n\nA tool to use AWS IAM credentials to authenticate to a Kubernetes cluster.\nThe initial work on this tool was driven by Heptio. The project receives contributions from multiple community engineers and is currently maintained by Heptio and Amazon EKS OSS Engineers.\n\n## Table of Contents\n\n- [Why do I want this?](#why-do-i-want-this)\n- [How do I use it?](#how-do-i-use-it)\n- [Kops Usage](#kops-usage)\n- [How does it work?](#how-does-it-work)\n- [What is a cluster ID?](#what-is-a-cluster-id)\n- [Specifying Credentials \u0026 Using AWS Profiles](#specifying-credentials--using-aws-profiles)\n- [API Authorization from Outside a Cluster](#api-authorization-from-outside-a-cluster)\n- [Troubleshooting](#troubleshooting)\n- [Full Configuration Format](#full-configuration-format)\n- [Development](#development)\n- [Community, discussion, contribution, and support](#community-discussion-contribution-and-support)\n\n## Why do I want this?\nIf you are an administrator running a Kubernetes cluster on AWS, you already need to manage AWS IAM credentials to provision and update the cluster.\nBy using AWS IAM Authenticator for Kubernetes, you avoid having to manage a separate credential for Kubernetes access.\nAWS IAM also provides a number of nice properties such as an out of band audit trail (via CloudTrail) and 2FA/MFA enforcement.\n\nIf you are building a Kubernetes installer on AWS, AWS IAM Authenticator for Kubernetes can simplify your bootstrap process.\nYou won't need to somehow smuggle your initial admin credential securely out of your newly installed cluster.\nInstead, you can create a dedicated `KubernetesAdmin` role at cluster provisioning time and set up Authenticator to allow cluster administrator logins.\n\n## How do I use it?\nAssuming you have a cluster running in AWS and you want to add AWS IAM Authenticator for Kubernetes support, you need to:\n 1. Create an IAM role you'll use to identify users.\n 2. Run the Authenticator server as a DaemonSet.\n 3. Configure your API server to talk to Authenticator.\n 4. Set up kubectl to use Authenticator tokens.\n\n### 1. Create an IAM role\nFirst, you must create one or more IAM roles that will be mapped to users/groups inside your Kubernetes cluster.\nThe easiest way to do this is to log into the AWS Console:\n - Choose the \"Role for cross-account access\" / \"Provide access between AWS accounts you own\" option.\n - Paste in your AWS account ID number (available in the top right in the console).\n - Your role does not need any additional policies attached.\n\nThis will create an IAM role with no permissions that can be assumed by authorized users/roles in your account.\nNote the Amazon Resource Name (ARN) of your role, which you will need below.\n\nYou can also do this in a single step using the AWS CLI instead of the AWS Console:\n```sh\n# get your account ID\nACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')\n\n# define a role trust policy that opens the role to users in your account (limited by IAM policy)\nPOLICY=$(echo -n '{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::'; echo -n \"$ACCOUNT_ID\"; echo -n ':root\"},\"Action\":\"sts:AssumeRole\",\"Condition\":{}}]}')\n\n# create a role named KubernetesAdmin (will print the new role's ARN)\naws iam create-role \\\n  --role-name KubernetesAdmin \\\n  --description \"Kubernetes administrator role (for AWS IAM Authenticator for Kubernetes).\" \\\n  --assume-role-policy-document \"$POLICY\" \\\n  --output text \\\n  --query 'Role.Arn'\n```\n\nYou can also skip this step and use:\n - An existing role (such as a cross-account access role).\n - An IAM user (see `mapUsers` below).\n - An EC2 instance or a federated role (see `mapRoles` below).\n\n### 2. Run the server\nThe server is meant to run on each of your master nodes as a DaemonSet with host networking so it can expose a localhost port.\n\nFor a sample ConfigMap and DaemonSet configuration, see [`deploy/example.yaml`](./deploy/example.yaml).\nBefore applying it, update these values for your cluster:\n - Replace placeholder IAM ARNs (`arn:aws:iam::000000000000:...`) in `config.yaml`.\n - Set `clusterID` to a unique value for your cluster.\n - Verify the DaemonSet scheduling rules match your control-plane node labels/taints.\n\nThen deploy it:\n```sh\nkubectl apply -f deploy/example.yaml\nkubectl -n kube-system rollout status daemonset/aws-iam-authenticator\nkubectl -n kube-system get pods -l k8s-app=aws-iam-authenticator\n```\n\nOnce the pod is running on a control-plane node, the `aws-iam-authenticator server` will create the webhook kubeconfig on the host at `/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml` (or the path configured via `--generate-kubeconfig`).\n\n#### (Optional) Pre-generate a certificate, key, and kubeconfig\nIf you're building an automated installer, you can also pre-generate the certificate, key, and webhook kubeconfig files easily using `aws-iam-authenticator init`.\nThis command will generate files and place them in the configured output directories.\n\nYou can run this on each master node prior to starting the API server.\nYou could also generate them before provisioning master nodes and install them in the appropriate host paths.\n\nIf you do not pre-generate files, `aws-iam-authenticator server` will generate them on demand.\nThis works but requires that you restart your Kubernetes API server after installation.\n\n### 3. Configure your API server to talk to the server\nThe Kubernetes API integrates with AWS IAM Authenticator for Kubernetes using a [token authentication webhook](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).\nWhen you run `aws-iam-authenticator server`, it will generate a webhook configuration file and save it onto the host filesystem.\nYou'll need to add a single additional flag to your API server configuration:\n```\n--authentication-token-webhook-config-file=/etc/kubernetes/aws-iam-authenticator/kubeconfig.yaml\n```\n\nOn many clusters, the API server runs as a static pod.\nYou can add the flag to `/etc/kubernetes/manifests/kube-apiserver.yaml`.\nMake sure the host directory `/etc/kubernetes/aws-iam-authenticator/` is mounted into your API server pod.\nYou may also need to restart the kubelet daemon on your master node to pick up the updated static pod definition:\n```\nsystemctl restart kubelet.service\n```\n\n### 4. Create IAM role/user to kubernetes user/group mappings\nThe default behavior of the server is to source mappings exclusively from the\n`mapUsers` and `mapRoles` fields of its configuration file. See [Full\nConfiguration Format](#full-configuration-format) below for details.\n\nUsing the `--backend-mode` flag, you can configure the server to source\nmappings from two additional backends: an EKS-style ConfigMap\n(`--backend-mode=EKSConfigMap`) or `IAMIdentityMapping` custom resources\n(`--backend-mode=CRD`). The default backend, the server configuration file\nthat's mounted by the server pod, corresponds to `--backend-mode=MountedFile`.\n\nYou can pass a comma-separated list of these backends to have the server search\nthem in order. For example, with `--backend-mode=EKSConfigMap,MountedFile`, the\nserver will search the EKS-style ConfigMap for mappings then, if it doesn't\nfind a mapping for the given IAM role/user, the server configuration file. If a\nmapping for the same IAM role/user exists in multiple backends, the server will\nuse the mapping in the backend that occurs first in the comma-separated list.\nIn this example, if a mapping is found in the EKS ConfigMap then it will be\nused whether or not a duplicate or conflicting mapping exists in the server\nconfiguration file.\n\nNote that when setting a single backend, the server will *only* source from\nthat one and ignore the others even if they exist. For example, with\n`--backend-mode=CRD`, the server will *only* source from `IAMIdentityMappings`\nand ignore the mounted file and EKS ConfigMap.\n\n#### `MountedFile`\nThis is the default backend of mappings and sufficient for most users. See\n[Full Configuration Format](#full-configuration-format) below for details.\n\n#### `CRD` (alpha)\nThis backend models each IAM mapping as an `IAMIdentityMapping` [Kubernetes\nCustom\nResource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).\nThis approach enables you to maintain mappings in a Kubernetes-native way using\nkubectl or the API. Plus, syntax errors (like misaligned YAML) can be more\neasily caught and won't affect all mappings.\n\nTo setup an `IAMIdentityMapping` CRD you'll first need to `apply` the CRD\nmanifest:\n\n```\nkubectl apply -f deploy/iamidentitymapping.yaml\n```\n\nWith the CRDs deployed you can then create Custom Resources which model your\nIAM Identities. See\n[`./deploy/example-iamidentitymapping.yaml`](deploy/example-iamidentitymapping.yaml):\n\n```\n---\napiVersion: iamauthenticator.k8s.aws/v1alpha1\nkind: IAMIdentityMapping\nmetadata:\n  name: kubernetes-admin\nspec:\n  # Arn of the User or Role to be allowed to authenticate\n  arn: arn:aws:iam::XXXXXXXXXXXX:user/KubernetesAdmin\n  # Username that Kubernetes will see the user as, this is useful for setting\n  # up allowed specific permissions for different users\n  username: kubernetes-admin\n  # Groups to be attached to your users/roles. For example `system:masters` to\n  # create cluster admin, or `system:nodes`, `system:bootstrappers` for nodes to\n  # access the API server.\n  groups:\n  - system:masters\n```\n\n#### `EKSConfigMap`\nThe EKS-style `kube-system/aws-auth` ConfigMap serves as the backend. The\nConfigMap is expected to be in exactly the same format as in EKS clusters:\nhttps://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html. This is\nuseful if you're migrating from/to EKS and want to keep your mappings, or are\nrunning EKS in addition to some other AWS cluster(s) and want to have the same\nmappings in each.\n\n#### `DynamicFile`\nA local file specified by cfg.dynamicfilepath can serve as the backend. The file\ncontent is expected to be in exactly the same format as the EKSConfigMap. Whenever\nthis file content changes, authenticator will automatically reload it.  This\nprovides more flexibility on managing the ARN mappings.\n\nCheck https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml\nabout how to configure the DynamicFile mode.\n\nRun `make e2e RUNNER=kind` to play with a kind cluster with DynamicFile mode enable.\n### 5. How to configure reservedPrefixConfig for Kubernetes usernames\nThe aws-iam-authenticator can support reserved prefix for k8s username. If the reserved prefix is\nset, then the username with the reserved prefix will not be authenticated with the error\n\"username must not begin with with the following prefixes:\".\n\nCheck https://github.com/kubernetes-sigs/aws-iam-authenticator/blob/master/hack/dev/authenticator_with_dynamicfile_mode.yaml\nabout how to configure the reserved prefix.\n\n\n### 6. Set up kubectl to use authentication tokens provided by AWS IAM Authenticator for Kubernetes\n\nFinally, once the server is set up you'll want to authenticate.\nYou will still need a `kubeconfig` that has the public data about your cluster (cluster CA certificate, endpoint address).\nThe `users` section of your configuration, however, should include an exec section ([refer to the kubectl credential plugin docs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins)):\n```yaml\n# [...]\nusers:\n- name: kubernetes-admin\n  user:\n    exec:\n      apiVersion: client.authentication.k8s.io/v1beta1\n      command: aws-iam-authenticator\n      args:\n        - \"token\"\n        - \"-i\"\n        - \"REPLACE_ME_WITH_YOUR_CLUSTER_ID\"\n        - \"-r\"\n        - \"REPLACE_ME_WITH_YOUR_ROLE_ARN\"\n  # no client certificate/key needed here!\n```\n\nThis means the `kubeconfig` is entirely public data and can be shared across all Authenticator users.\nIt may make sense to upload it to a trusted public location such as AWS S3.\n\nMake sure you have the `aws-iam-authenticator` binary installed.\nYou can install it with `go install sigs.k8s.io/aws-iam-authenticator/cmd/aws-iam-authenticator@latest`.\n\nTo authenticate, run `kubectl --kubeconfig /path/to/kubeconfig\" [...]`.\nkubectl will `exec` the `aws-iam-authenticator` binary with the supplied params in your kubeconfig which will generate a token and pass it to the apiserver.\nThe token is valid for 15 minutes (the shortest value AWS permits) and can be reused multiple times.\n\nYou can also specify session name when generating the token by including `--session-name or -s` parameter. This parameter cannot be used along with `--forward-session-name`.\n\nYou can also omit `-r ROLE_ARN` to sign the token with your existing credentials without assuming a dedicated role.\nThis is useful if you want to authenticate as an IAM user directly or if you want to authenticate using an EC2 instance role or a federated role.\n\n## Kops Usage\nClusters managed by [Kops](https://github.com/kubernetes/kops) can be configured to use Authenticator. For usage instructions see the [Kops documentation](https://kops.sigs.k8s.io/authentication/#aws-iam-authenticator).\n\n## How does it work?\nIt works using the AWS [`sts:GetCallerIdentity`](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) API endpoint.\nThis endpoint returns information about whatever AWS IAM credentials you use to connect to it.\n\n#### Client side (`aws-iam-authenticator token`)\nWe use this API in a somewhat unusual way by having the Authenticator client generate and pre-sign a request to the endpoint.\nWe serialize that request into a token that can pass through the Kubernetes authentication system.\n\n#### Server side (`aws-iam-authenticator server`)\nThe token is passed through the Kubernetes API server and into the Authenticator server's `/authenticate` endpoint via a webhook configuration.\nThe Authenticator server validates all the parameters of the pre-signed request to make sure nothing looks funny.\nIt then submits the request to the real `https://sts.amazonaws.com` server, which validates the client's HMAC signature and returns information about the user.\nNow that the server knows the AWS identity of the client, it translates this identity into a Kubernetes user and groups via a simple static mapping.\n\nThis mechanism is borrowed with a few changes from [Vault](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method).\n\n## What is a cluster ID?\nThe Authenticator cluster ID is a unique-per-cluster identifier that prevents certain replay attacks.\nSpecifically, it prevents one Authenticator server (e.g., in a dev environment) from using a client's token to authenticate to another Authenticator server in another cluster.\n\nThe cluster ID does need to be unique per-cluster, but it doesn't need to be a secret.\nSome good choices are:\n - A random ID such as from `openssl rand 16 -hex`\n - The domain name of your Kubernetes API server\n\nThe [Vault documentation](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method) also explains this attack (see `X-Vault-AWS-IAM-Server-ID`).\n\n## Specifying Credentials \u0026 Using AWS Profiles\nCredentials can be specified for use with `aws-iam-authenticator` via any of the methods available to the\n[AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).\nThis includes specifying AWS credentials with enviroment variables or by utilizing a credentials file.\n\nAWS [named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html) are supported by `aws-iam-authenticator`\nvia the `AWS_PROFILE` environment variable. For example, to authenticate with credentials specified in the _dev_ profile the `AWS_PROFILE` can\nbe exported or specified explictly (e.g., `AWS_PROFILE=dev kubectl get all`). If no `AWS_PROFILE` is set, the _default_ profile is used.\n\nThe `AWS_PROFILE` can also be specified directly in the kubeconfig file\n[as part of the `exec` flow](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuration). For example, to specify\nthat credentials from the _dev_ named profile should always be used by `aws-iam-authenticator`, your kubeconfig would include an `env`\nkey thats sets the profile:\n\n```yaml\napiVersion: v1\nclusters:\n- cluster:\n    server: ${server}\n    certificate-authority-data: ${cert}\n  name: kubernetes\ncontexts:\n- context:\n    cluster: kubernetes\n    user: aws\n  name: aws\ncurrent-context: aws\nkind: Config\npreferences: {}\nusers:\n- name: aws\n  user:\n    exec:\n      apiVersion: client.authentication.k8s.io/v1beta1\n      command: aws-iam-authenticator\n      env:\n      - name: \"AWS_PROFILE\"\n        value: \"dev\"\n      args:\n        - \"token\"\n        - \"-i\"\n        - \"mycluster\"\n```\n\nThis method allows the appropriate profile to be used implicitly. Note that any environment variables set as part of the `exec` flow will\ntake precedence over what's already set in your environment.\n\n#### Note for federated users:\nFederated AWS users often will have a \"meaningful\" attribute mapped onto their assumed role, such as an email address, through the account's AWS configuration.\nThese assumed sessions have [a few parts](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#principaltable), the `role id`\nand `caller-specified-role-name`. By default, when a federated user uses the `--role` option of `aws-iam-authenticator` to assume a new role the\n`caller-specified-role-name` will be converted to a random token and the `role id` carries through to the newly assumed role.\n\nUsing `aws-iam-authenticator token ... --forward-session-name` will map the original `caller-specified-role-name` attribute onto the new STS assumed session.\nThis can be helpful for quickly attempting to associate \"who performed action X on the K8 cluster\".\n\nPlease note, **this should not be considered definitive** and needs to be cross referenced via the `role id` (which remains consistent) with CloudTrail logs\nas a user could potentially change this on the client side.\n\n## API Authorization from Outside a Cluster\n\nIt is possible to make requests to the Kubernetes API from a client that is outside the cluster, be that using the\nbare Kubernetes REST API or from one of the language specific Kubernetes clients\n(e.g., [Python](https://github.com/kubernetes-client/python)). In order to do so, you must create a bearer token that\nis included with the request to the API. This bearer token requires you append the string `k8s-aws-v1.` with a\nbase64 encoded string of a signed HTTP request to the STS GetCallerIdentity Query API. This is then sent it in the\n`Authorization`  header of the request.  Something to note though is that the IAM Authenticator explicitly omits\nbase64 padding to avoid any `=` characters thus guaranteeing a string safe to use in URLs. Below is an example in\nPython on how this token would be constructed:\n\n```python\nimport base64\nimport boto3\nimport re\nfrom botocore.signers import RequestSigner\n\ndef get_bearer_token(cluster_id, region):\n    STS_TOKEN_EXPIRES_IN = 60\n    session = boto3.session.Session()\n\n    client = session.client('sts', region_name=region)\n    service_id = client.meta.service_model.service_id\n\n    signer = RequestSigner(\n        service_id,\n        region,\n        'sts',\n        'v4',\n        session.get_credentials(),\n        session.events\n    )\n\n    params = {\n        'method': 'GET',\n        'url': 'https://sts.{}.amazonaws.com/?Action=GetCallerIdentity\u0026Version=2011-06-15'.format(region),\n        'body': {},\n        'headers': {\n            'x-k8s-aws-id': cluster_id\n        },\n        'context': {}\n    }\n\n    signed_url = signer.generate_presigned_url(\n        params,\n        region_name=region,\n        expires_in=STS_TOKEN_EXPIRES_IN,\n        operation_name=''\n    )\n\n    base64_url = base64.urlsafe_b64encode(signed_url.encode('utf-8')).decode('utf-8')\n\n    # remove any base64 encoding padding:\n    return 'k8s-aws-v1.' + re.sub(r'=*', '', base64_url)\n\n# If making a HTTP request you would create the authorization headers as follows:\n\nheaders = {'Authorization': 'Bearer ' + get_bearer_token('my_cluster', 'us-east-1')}\n\n```\n\n\n## Troubleshooting\n\nIf your client fails with an error like `could not get token: AccessDenied [...]`, you can try assuming the role with the AWS CLI directly:\n\n```sh\n# AWS CLI version of `aws-iam-authenticator token -r arn:aws:iam::ACCOUNT:role/ROLE`:\n$ aws sts assume-role --role-arn arn:aws:iam::ACCOUNT:role/ROLE --role-session-name test\n```\n\nIf that fails, there are a few possible problems to check for:\n\n - Make sure your base AWS credentials are available in your shell (`aws sts get-caller-identity` can help troubleshoot this).\n\n - Make sure the target role allows your source account access (in the role trust policy).\n\n - Make sure your source principal (user/role/group) has an IAM policy that allows `sts:AssumeRole` for the target role.\n\n - Make sure you don't have any explicit deny policies attached to your user, group, or in AWS Organizations that would prevent the `sts:AssumeRole`.\n\n - Try simulating the `sts:AssumeRole` call in the [Policy Simulator](https://policysim.aws.amazon.com/home/index.jsp).\n\n## Full Configuration Format\nThe client and server have the same configuration format.\nThey can share the same exact configuration file, since there are no secrets stored in the configuration.\n\n```yaml\n# a unique-per-cluster identifier to prevent replay attacks (see above)\nclusterID: my-dev-cluster.example.com\n\n# default IAM role to assume for `aws-iam-authenticator token`\ndefaultRole: arn:aws:iam::000000000000:role/KubernetesAdmin\n\n# server listener configuration\nserver:\n  # localhost port where the server will serve the /authenticate endpoint\n  port: 21362 # (default)\n\n  # state directory for generated TLS certificate and private keys\n  stateDir: /var/aws-iam-authenticator # (default)\n\n  # output `path` where a generated webhook kubeconfig will be stored.\n  generateKubeconfig: /etc/kubernetes/aws-iam-authenticator.kubeconfig # (default)\n\n  # role to assume before querying EC2 API in order to discover metadata like EC2 private DNS Name\n  ec2DescribeInstancesRoleARN: arn:aws:iam::000000000000:role/DescribeInstancesRole\n\n  # AWS Account IDs to scrub from server logs. (Defaults to empty list)\n  scrubbedAccounts:\n  - \"111122223333\"\n  - \"222233334444\"\n\n  # each mapRoles entry maps an IAM role to a username and set of groups\n  # Each username and group can optionally contain template parameters:\n  #  1) \"{{AccountID}}\" is the 12 digit AWS ID.\n  #  2) \"{{SessionName}}\" is the role session name, with `@` characters\n  #     transliterated to `-` characters.\n  #  3) \"{{SessionNameRaw}}\" is the role session name, without character\n  #     transliteration (available in version \u003e= 0.5).\n  mapRoles:\n  # statically map arn:aws:iam::000000000000:role/KubernetesAdmin to cluster admin\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesAdmin\n    username: kubernetes-admin\n    groups:\n    - system:masters\n\n  # map EC2 instances in my \"KubernetesNode\" role to users like\n  # \"aws:000000000000:instance:i-0123456789abcdef0\". Only use this if you\n  # trust that the role can only be assumed by EC2 instances. If an IAM user\n  # can assume this role directly (with sts:AssumeRole) they can control\n  # SessionName.\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesNode\n    username: aws:{{AccountID}}:instance:{{SessionName}}\n    groups:\n    - system:bootstrappers\n    - aws:instances\n\n  # map nodes that should conform to the username \"system:node:\u003cprivate-DNS\u003e\".  This\n  # requires the authenticator to query the EC2 API in order to discover the private\n  # DNS of the EC2 instance originating the authentication request.  Optionally, you\n  # may specify a role that should be assumed before querying the EC2 API with the\n  # key \"server.ec2DescribeInstancesRoleARN\" (see above).\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesNode\n    username: system:node:{{EC2PrivateDNSName}}\n    groups:\n    - system:nodes\n    - system:bootstrappers\n\n  # map federated users in my \"KubernetesAdmin\" role to users like\n  # \"admin:alice-example.com\". The SessionName is an arbitrary role name\n  # like an e-mail address passed by the identity provider. Note that if this\n  # role is assumed directly by an IAM User (not via federation), the user\n  # can control the SessionName.\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesAdmin\n    username: admin:{{SessionName}}\n    groups:\n    - system:masters\n\n  # map federated users in my \"KubernetesOtherAdmin\" role to users like\n  # \"alice-example.com\". The SessionName is an arbitrary role name\n  # like an e-mail address passed by the identity provider. Note that if this\n  # role is assumed directly by an IAM User (not via federation), the user\n  # can control the SessionName.  Note that the \"{{SessionName}}\" macro is\n  # quoted to ensure it is properly parsed as a string.\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesOtherAdmin\n    username: \"{{SessionName}}\"\n    groups:\n    - system:masters\n\n  # If unalterable identification of an IAM User is desirable, you can map against\n  # AccessKeyID.\n  - rolearn: arn:aws:iam::000000000000:role/KubernetesOtherAdmin\n    username: \"admin:{{AccessKeyID}}\"\n    groups:\n    - system:masters\n\n  # each mapUsers entry maps an IAM user to a static username and set of groups\n  mapUsers:\n  # map user IAM user Alice in 000000000000 to user \"alice\" in group \"system:masters\"\n  - userarn: arn:aws:iam::000000000000:user/Alice\n    username: alice\n    groups:\n    - system:masters\n\n  # automatically map IAM ARN from these accounts to username.\n  # NOTE: Always use quotes to avoid the account numbers being recognized as numbers\n  # instead of strings by the yaml parser.\n  mapAccounts:\n  - \"012345678901\"\n  - \"456789012345\"\n\n  # source mappings from this file (mapUsers, mapRoles, \u0026 mapAccounts)\n  backendMode:\n  - MountedFile\n```\n\n## Development\n\nSee the [development](./docs/development.md) page.\n\n\n## Community, discussion, contribution, and support\n\nLearn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).\n\nYou can reach the maintainers of this project at:\n\n- [Slack](https://kubernetes.slack.com/messages/sig-aws)\n- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-aws)\n\n### Code of conduct\n\nParticipation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes-sigs%2Faws-iam-authenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubernetes-sigs%2Faws-iam-authenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes-sigs%2Faws-iam-authenticator/lists"}