AWS eks: Add AWS PrivateLink support for EKS cluster OIDC endpoint with security guidance
Summary
Documented new AWS PrivateLink endpoint for EKS cluster OIDC discovery/JWKS, including security considerations about VPC endpoint policies and authorization boundaries.
Security assessment
The evidence explicitly addresses security limitations of the OIDC endpoint, explaining why VPC endpoint policies can't be applied and how authorization is enforced via IAM trust policies instead of network controls.
Evidence
+ * **This endpoint does not support VPC endpoint policies.** The OIDC discovery and JWKS documents are served anonymously. This is required by the OpenID Connect specification and is how IRSA works: validators fetch public keys without presenting credentials.
Diff
diff --git a/eks/latest/userguide/vpc-interface-endpoints.md b/eks/latest/userguide/vpc-interface-endpoints.md index 92f1bdfeb..968545dd2 100644 --- a//eks/latest/userguide/vpc-interface-endpoints.md +++ b//eks/latest/userguide/vpc-interface-endpoints.md @@ -7 +7 @@ -Before you beginConsiderationsCreate an interface endpoint for Amazon EKSPrivate DNS feature for Amazon EKS interface endpoints +Before you beginConsiderationsCreate an interface endpoint for Amazon EKSPrivate DNS feature for Amazon EKS interface endpointsAccess the cluster OIDC endpoint using AWS PrivateLink @@ -32 +32 @@ Before you start, make sure you have performed the following tasks: - * **Support and Limitations** : Amazon EKS interface endpoints enable secure access to all Amazon EKS API actions from your VPC but come with specific limitations: they do not support access to Kubernetes APIs, as these have a separate private endpoint, you cannot configure Amazon EKS to be accessible only through the interface endpoint. + * **Support and Limitations** : Amazon EKS interface endpoints enable secure access to all Amazon EKS API actions from your VPC but come with specific limitations: they do not support access to Kubernetes APIs, as these have a separate private endpoint, you cannot configure Amazon EKS to be accessible only through the interface endpoint. The cluster OIDC discovery and JWKS endpoint used by IAM roles for service accounts (IRSA) is also served from a separate interface endpoint with its own service name and access-control behavior; see Access the cluster OIDC endpoint using AWS PrivateLink. @@ -42 +42 @@ Before you start, make sure you have performed the following tasks: - * **Regional Availability** : AWS PrivateLink for the EKS API is not available in Asia Pacific (Malaysia) (ap-southeast-5), Asia Pacific (Thailand) (ap-southeast-7), Mexico (Central) (mx-central-1), and Asia Pacific (Taipei) (ap-east-2) regions. AWS PrivateLink support for eks-auth (EKS Pod Identity) is available in the Asia Pacific (Malaysia) (ap-southeast-5) region. + * **Regional Availability** : AWS PrivateLink for the EKS API is not available in Asia Pacific (Malaysia) (ap-southeast-5), Asia Pacific (Thailand) (ap-southeast-7), Mexico (Central) (mx-central-1), and Asia Pacific (Taipei) (ap-east-2) regions. AWS PrivateLink support for eks-auth (EKS Pod Identity) is available in the Asia Pacific (Malaysia) (ap-southeast-5) region. AWS PrivateLink for the cluster OIDC endpoint (`com.amazonaws.region-code.oidc-eks`) is available in most AWS Regions. @@ -68,0 +69,9 @@ Create an interface endpoint for Amazon EKS using the following service names: +### EKS cluster OIDC endpoint (IRSA discovery / JWKS) + + * com.amazonaws.region-code.oidc-eks + + + + +This endpoint has access-control behavior that differs from the EKS API endpoints. For more information, see Access the cluster OIDC endpoint using AWS PrivateLink. + @@ -111,0 +121,32 @@ Once configured, the private DNS feature can be integrated into your workflows, +## Access the cluster OIDC endpoint using AWS PrivateLink + +Each Amazon EKS cluster publishes a public OpenID Connect (OIDC) discovery document and JSON Web Key Set (JWKS) at its OIDC issuer URL. IAM roles for service accounts (IRSA) uses this endpoint to publish the cluster’s public signing keys. Tools that set up IRSA or validate tokens directly retrieve keys from this endpoint. + +You can use AWS PrivateLink to reach this OIDC endpoint privately from your VPC, without internet egress. This is useful for private or no-egress VPCs where in-VPC tooling needs to reach the OIDC endpoint, for example, creating the cluster’s IAM OIDC identity provider (`eksctl`, Terraform, or the AWS CLI), or running your own token validators inside the VPC. Previously, reaching this endpoint required internet access or DNS workarounds (see [containers-roadmap#2038](https://github.com/aws/containers-roadmap/issues/2038) on GitHub). + +Create an interface endpoint for the cluster OIDC endpoint using the following service name: + + * `com.amazonaws.region-code.oidc-eks` + + + + +### Considerations + + * **This endpoint does not support VPC endpoint policies.** The OIDC discovery and JWKS documents are served anonymously. This is required by the OpenID Connect specification and is how IRSA works: validators fetch public keys without presenting credentials. Because requests carry no IAM principal or action, a VPC endpoint policy has nothing to evaluate against. This endpoint accepts only the default full-access policy. Control who can reach the endpoint with the security groups on the endpoint network interfaces and with subnet routing. + + * **Private connectivity is not an authorization boundary.** Reaching the OIDC endpoint over AWS PrivateLink keeps this traffic on the AWS network — it does not, by itself, control who can assume an IAM role. The data served is public key material. The trust policy of the assumed role enforces IRSA authorization, not the network path used to reach the OIDC endpoint. This enforcement happens when a workload calls `sts:AssumeRoleWithWebIdentity`. Control which workloads can assume a role with the `aud` and `sub` conditions in the role’s trust policy; see [Assign IAM roles to Kubernetes service accounts](./associate-service-account-role.html). + + * **AWS STS validates tokens on its own path.** This endpoint does not affect how AWS STS validates IRSA tokens. When a workload calls `AssumeRoleWithWebIdentity`, STS fetches the cluster’s JWKS from within AWS, not through your VPC or this endpoint. Creating this endpoint, or overriding OIDC DNS in your VPC, does not change token validation. To also keep the workload’s `AssumeRoleWithWebIdentity` call private, create an AWS STS interface endpoint and configure the regional STS endpoint separately; see [Configure the AWS Security Token Service endpoint for a service account](https://docs.aws.amazon.com/eks/latest/userguide/configure-sts-endpoint.html). + + * **Pricing:** Standard AWS PrivateLink charges apply. See [AWS PrivateLink pricing](https://aws.amazon.com/privatelink/pricing/). + + + + +### Private DNS and dual-stack names + +Each cluster has one OIDC issuer hostname, determined by the cluster’s IP family. IPv4 clusters, which are the default, use `oidc.eks.region-code.amazonaws.com`. IPv6 clusters use the dual-stack hostname `oidc-eks.region-code.api.aws`, which resolves to both IPv4 and IPv6 addresses. In the AWS China Regions, the dual-stack hostname is `oidc-eks.region-code.api.amazonwebservices.com.cn`. + +The interface endpoint registers both hostnames. With private DNS enabled (the default), each hostname resolves to your interface endpoint. Your cluster’s issuer URL therefore resolves to the endpoint whether the cluster uses the `oidc.eks.region-code.amazonaws.com` hostname or the dual-stack hostname. A client that follows a token’s issuer URL to fetch the discovery document and JWKS reaches the endpoint privately in either case. +