improvement(kubernetes-auth): k8s auth validation and errors

[victorvhs017]

Context

This PR adds validation to the Kubernetes URL and token when adding a Kubernetes auth to a machine identity. It also adds more detailed error messages and centralizes error handling.

https://linear.app/infisical/issue/ENG-4209/improve-kubernetes-auth-error-handling-and-validation-steps

Steps to verify the change

• Test with an invalid Kubernetes host url
• Test with a valid URL but unaccessible (for example, trying to use the ip instead of https://host.docker.internal/ for a cluster running inside docker)
• Test with a valid accessible URL
• Test with a valid accessible URL with an invalid token
• Test with a valid accessible URL with a valid token but without permission (a service account without auth-delegator cluster role)
• Test with a valid accessible URL with a valid token and permission
• Test with an invalid CA cert
• Test with a valid CA cert
• Test with a gateway and manual token reviewer
• Test with a gateway and the gateway as reviewer

Type

• Fix
• Feature
• Improvement
• Breaking
• Docs
• Chore

Checklist

• Title follows the conventional commit format: type(scope): short description (scope is optional, e.g., fix: prevent crash on sync or fix(api): handle null response).
• Tested locally
• Updated docs (if needed)
• Read the contributing guide

[maidul98]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds validation for Kubernetes authentication configuration by introducing connectivity checks and token permission validation. The implementation includes:

• New validation module (identity-kubernetes-auth-validators.ts) with two key functions:
  • validateKubernetesHostConnectivity: Checks host reachability via /version endpoint
  • validateTokenReviewerJwtPermissions: Verifies JWT has TokenReview permissions using a test request
• Centralized error handling (identity-kubernetes-auth-error-handlers.ts) providing context-aware error messages for network errors (connection refused, timeouts, certificate failures) and HTTP errors (401/403 with actionable guidance)
• SSRF protection: Both validators call blockLocalAndPrivateIpAddresses before making requests to prevent attacks against internal infrastructure
• Integration: Validators are called during attachKubernetesAuth and updateKubernetesAuth when token review mode is API and no gateway is configured
• Improved error messages: Better user guidance for common issues like missing ClusterRole bindings

Key improvements:

• Users receive immediate feedback when configuring invalid Kubernetes hosts or insufficient JWT permissions
• Clear, actionable error messages guide users to fix configuration issues
• Security hardened against SSRF attacks via existing validation utilities
• Proper use of RE2 library for regex operations (no ReDoS vulnerabilities)

Issues found:

• In updateKubernetesAuth, when updating kubernetesHost or tokenReviewerJwt without updating caCert, the validation doesn't retrieve the existing CA cert from the database, potentially causing validation failures for hosts that require it

Confidence Score: 4/5

• This PR is largely safe to merge with one logical issue that needs attention
• Score of 4 reflects solid security practices (SSRF protection, RE2 regex usage, centralized error handling) and good architecture, but there's a logic bug in the update flow where the existing CA cert isn't used during validation when only updating the host or JWT. This could cause validation failures for legitimate configurations that require CA certs.
• backend/src/services/identity-kubernetes-auth/identity-kubernetes-auth-service.ts requires attention for the CA cert validation logic in the update flow (lines 907-934)

Important Files Changed

File Analysis

Filename	Score	Overview
backend/src/services/identity-kubernetes-auth/identity-kubernetes-auth-validators.ts	5/5	Added two validation functions: validateKubernetesHostConnectivity checks host reachability and validateTokenReviewerJwtPermissions verifies JWT permissions by attempting a test TokenReview. Both properly use blockLocalAndPrivateIpAddresses to prevent SSRF attacks.
backend/src/services/identity-kubernetes-auth/identity-kubernetes-auth-error-handlers.ts	5/5	New centralized error handling module with context-aware error messages for network errors (ECONNREFUSED, ETIMEDOUT, certificate errors) and HTTP errors (401/403). Provides clear, actionable error messages for different contexts (Kubernetes host, API server, gateway proxy).
backend/src/services/identity-kubernetes-auth/identity-kubernetes-auth-service.ts	5/5	Integrated validation functions into attachKubernetesAuth and updateKubernetesAuth to validate connectivity and JWT permissions when creating/updating auth methods. Enhanced error handling in token review callbacks using centralized error handlers.
backend/src/services/identity-kubernetes-auth/identity-kubernetes-auth-fns.ts	5/5	Improved extractK8sUsername error handling to throw UnauthorizedError with clear message format instead of generic Error.

[greptile-apps]

_{4 files reviewed, 6 comments}

_{Edit Code Review Agent Settings | Greptile}

[victorvhs017]

@greptileai re-review the code and update the first comment

[greptile-apps]

_{4 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}