{"id":37187632,"url":"https://github.com/vend/authenticator","last_synced_at":"2026-01-14T21:48:50.949Z","repository":{"id":35067367,"uuid":"122148520","full_name":"vend/authenticator","owner":"vend","description":"A tool for using AWS IAM credentials to authenticate to a Kubernetes cluster","archived":true,"fork":true,"pushed_at":"2022-03-24T03:40:39.000Z","size":18658,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-06-20T00:26:42.789Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"kubernetes-sigs/aws-iam-authenticator","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vend.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":null,"support":null}},"created_at":"2018-02-20T02:53:34.000Z","updated_at":"2023-01-28T02:08:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vend/authenticator","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/vend/authenticator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vend%2Fauthenticator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vend%2Fauthenticator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vend%2Fauthenticator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vend%2Fauthenticator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vend","download_url":"https://codeload.github.com/vend/authenticator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vend%2Fauthenticator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28436201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T21:32:52.117Z","status":"ssl_error","status_checked_at":"2026-01-14T21:32:33.442Z","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":[],"created_at":"2026-01-14T21:48:50.240Z","updated_at":"2026-01-14T21:48:50.928Z","avatar_url":"https://github.com/vend.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heptio Authenticator for AWS\n\nA tool for using AWS IAM credentials to authenticate to a Kubernetes cluster.\n\n## Why do I want this?\nIf you are an administrator running a Kubernetes cluster on AWS, you already need to manage AWS credentials for provisioning and updating the cluster.\nBy using Heptio Authenticator for AWS, 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, Heptio Authenticator for AWS 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 Heptio Authenticator for AWS 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 Heptio Authenticator for AWS).\" \\\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 [`example.yaml`](./example.yaml).\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 `heptio-authenticator-aws 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, `heptio-authenticator-aws 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 Heptio Authenticator for AWS using a [token authentication webhook](https://kubernetes.io/docs/admin/authentication/#webhook-token-authentication).\nWhen you run `heptio-authenticator-aws 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/heptio-authenticator-aws/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/heptio-authenticator-aws/` 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. Set up kubectl to use Heptio Authenticator for AWS tokens\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, can be mostly blank:\n```yaml\n# [...]\nusers:\n- name: kubernetes-admin\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 `heptio-authenticator-aws` binary installed.\nYou can install it with `go get -u -v github.com/heptio/authenticator/cmd/heptio-authenticator-aws`.\n\nTo authenticate, run `kubectl --kubeconfig /path/to/kubeconfig --token \"$(heptio-authenticator-aws token -i CLUSTER_ID -r ROLE_ARN)\" [...]`.\nYou can simplify this with an alias or shell wrapper.\nThe token is valid for 15 minutes (the shortest value AWS permits) and can be reused multiple times.\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## 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 (`heptio-authenticator-aws token`)\nWe use this API in a somewhat unusual way by having the Heptio Authenticator for AWS 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 (`heptio-authenticator-aws server`)\nThe token is passed through the Kubernetes API server and into the Heptio Authenticator for AWS server's `/authenticate` endpoint via a webhook configuration.\nThe Heptio Authenticator for AWS 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## 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 `heptio-authenticator-aws 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## 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 `heptio-authenticator-aws 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/heptio-authenticator-aws # (default)\n\n  # output `path` where a generated webhook kubeconfig will be stored.\n  generateKubeconfig: /etc/kubernetes/heptio-authenticator-aws.kubeconfig # (default)\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.\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 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  # each mapUsers entry maps an IAM role 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvend%2Fauthenticator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvend%2Fauthenticator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvend%2Fauthenticator/lists"}