misc: added description to native auth properties

2026-09-22 13:39:35 +00:00 · 2024-07-10 15:17:23 +08:00
parent 899757ab7c
commit 4fab746b95
5 changed files with 235 additions and 73 deletions
--- a/backend/src/lib/api-docs/constants.ts
+++ b/backend/src/lib/api-docs/constants.ts
@@ -119,24 +119,149 @@ export const AWS_AUTH = {
      "The base64-encoded body of the signed request. Most likely, the base64-encoding of Action=GetCallerIdentity&Version=2011-06-15.",
    iamRequestHeaders: "The base64-encoded headers of the sts:GetCallerIdentity signed request."
  },
+  ATTACH: {
+    identityId: "The ID of the identity to attach the configuration onto.",
+    allowedPrincipalArns:
+      "The comma-separated list of trusted IAM principal ARNs that are allowed to authenticate with Infisical.",
+    allowedAccountIds:
+      "The comma-separated list of trusted AWS account IDs that are allowed to authenticate with Infisical.",
+    accessTokenTTL: "The lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The maximum lifetime for an acccess token in seconds.",
+    stsEndpoint: "The endpoint URL for the AWS STS API.",
+    accessTokenNumUsesLimit: "The maximum number of times that an access token can be used.",
+    accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from."
+  },
+  UPDATE: {
+    identityId: "The ID of the identity to be updated.",
+    allowedPrincipalArns:
+      "The new comma-separated list of trusted IAM principal ARNs that are allowed to authenticate with Infisical.",
+    allowedAccountIds:
+      "The new comma-separated list of trusted AWS account IDs that are allowed to authenticate with Infisical.",
+    accessTokenTTL: "The new lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The new maximum lifetime for an acccess token in seconds.",
+    stsEndpoint: "The new endpoint URL for the AWS STS API.",
+    accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used.",
+    accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from."
+  },
+  RETRIEVE: {
+    identityId: "The ID of the identity to retrieve."
+  },
  REVOKE: {
    identityId: "The ID of the identity to revoke."
  }
 } as const;

 export const AZURE_AUTH = {
+  LOGIN: {
+    identityId: "The ID of the identity to login."
+  },
+  ATTACH: {
+    identityId: "The ID of the identity to attach the configuration onto.",
+    tenantId: "The tenant ID for the Azure AD organization.",
+    resource: "The resource URL for the application registered in Azure AD.",
+    allowedServicePrincipalIds:
+      "The comma-separated list of Azure AD service principal IDs that are allowed to authenticate with Infisical.",
+    accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
+  },
+  UPDATE: {
+    identityId: "The new ID of the identity to be updated.",
+    tenantId: "The new tenant ID for the Azure AD organization.",
+    resource: "The new resource URL for the application registered in Azure AD.",
+    allowedServicePrincipalIds:
+      "The new comma-separated list of Azure AD service principal IDs that are allowed to authenticate with Infisical.",
+    accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The new lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The new maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
+  },
+  RETRIEVE: {
+    identityId: "The ID of the identity to retrieve."
+  },
  REVOKE: {
    identityId: "The ID of the identity to revoke."
  }
 } as const;

 export const GCP_AUTH = {
+  LOGIN: {
+    identityId: "The ID of the identity to login."
+  },
+  ATTACH: {
+    identityId: "The ID of the identity to attach the configuration onto.",
+    allowedServiceAccounts:
+      "The comma-separated list of trusted service account emails corresponding to the GCE resource(s) allowed to authenticate with Infisical.",
+    allowedProjects:
+      "The comma-separated list of trusted GCP projects that the GCE instance must belong to authenticate with Infisical.",
+    allowedZones:
+      "The comma-separated list of trusted zones that the GCE instances must belong to authenticate with Infisical.",
+    accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
+  },
+  UPDATE: {
+    identityId: "The ID of the identity to be updated.",
+    allowedServiceAccounts:
+      "The new comma-separated list of trusted service account emails corresponding to the GCE resource(s) allowed to authenticate with Infisical.",
+    allowedProjects:
+      "The new comma-separated list of trusted GCP projects that the GCE instance must belong to authenticate with Infisical.",
+    allowedZones:
+      "The new comma-separated list of trusted zones that the GCE instances must belong to authenticate with Infisical.",
+    accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The new lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The new maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
+  },
+  RETRIEVE: {
+    identityId: "The ID of the identity to retrieve."
+  },
  REVOKE: {
    identityId: "The ID of the identity to revoke."
  }
 } as const;

 export const KUBERNETES_AUTH = {
+  LOGIN: {
+    identityId: "The ID of the identity to login."
+  },
+  ATTACH: {
+    identityId: "The ID of the identity to attach the configuration onto.",
+    kubernetesHost: "The host string, host:port pair, or URL to the base of the Kubernetes API server.",
+    caCert: "The PEM-encoded CA cert for the Kubernetes API server.",
+    tokenReviewerJwt:
+      "The long-lived service account JWT token for Infisical to access the TokenReview API to validate other service account JWT tokens submitted by applications/pods.",
+    allowedNamespaces:
+      "The comma-separated list of trusted namespaces that service accounts must belong to authenticate with Infisical.",
+    allowedNames: "The comma-separated list of trusted service account names that can authenticate with Infisical.",
+    allowedAudience:
+      "The optional audience claim that the service account JWT token must have to authenticate with Infisical.",
+    accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
+  },
+  UPDATE: {
+    identityId: "The ID of the identity to be updated.",
+    kubernetesHost: "The new host string, host:port pair, or URL to the base of the Kubernetes API server.",
+    caCert: "The new PEM-encoded CA cert for the Kubernetes API server.",
+    tokenReviewerJwt:
+      "The new long-lived service account JWT token for Infisical to access the TokenReview API to validate other service account JWT tokens submitted by applications/pods.",
+    allowedNamespaces:
+      "The new comma-separated list of trusted namespaces that service accounts must belong to authenticate with Infisical.",
+    allowedNames: "The new comma-separated list of trusted service account names that can authenticate with Infisical.",
+    allowedAudience:
+      "The new optional audience claim that the service account JWT token must have to authenticate with Infisical.",
+    accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The new lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The new maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
+  },
+  RETRIEVE: {
+    identityId: "The ID of the identity to retrieve."
+  },
  REVOKE: {
    identityId: "The ID of the identity to revoke."
  }
--- a/backend/src/server/routes/v1/identity-aws-iam-auth-router.ts
+++ b/backend/src/server/routes/v1/identity-aws-iam-auth-router.ts
@@ -77,19 +77,25 @@ export const registerIdentityAwsAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(AWS_AUTH.ATTACH.identityId)
      }),
      body: z.object({
-        stsEndpoint: z.string().trim().min(1).default("https://sts.amazonaws.com/"),
-        allowedPrincipalArns: validatePrincipalArns,
-        allowedAccountIds: validateAccountIds,
+        stsEndpoint: z
+          .string()
+          .trim()
+          .min(1)
+          .default("https://sts.amazonaws.com/")
+          .describe(AWS_AUTH.ATTACH.stsEndpoint),
+        allowedPrincipalArns: validatePrincipalArns.describe(AWS_AUTH.ATTACH.allowedPrincipalArns),
+        allowedAccountIds: validateAccountIds.describe(AWS_AUTH.ATTACH.allowedAccountIds),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]),
+          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }])
+          .describe(AWS_AUTH.ATTACH.accessTokenTrustedIps),
        accessTokenTTL: z
          .number()
          .int()
@@ -97,15 +103,17 @@ export const registerIdentityAwsAuthRouter = async (server: FastifyZodProvider)
          .refine((value) => value !== 0, {
            message: "accessTokenTTL must have a non zero number"
          })
-          .default(2592000),
+          .default(2592000)
+          .describe(AWS_AUTH.ATTACH.accessTokenTTL),
        accessTokenMaxTTL: z
          .number()
          .int()
          .refine((value) => value !== 0, {
            message: "accessTokenMaxTTL must have a non zero number"
          })
-          .default(2592000),
-        accessTokenNumUsesLimit: z.number().int().min(0).default(0)
+          .default(2592000)
+          .describe(AWS_AUTH.ATTACH.accessTokenMaxTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).default(0).describe(AWS_AUTH.ATTACH.accessTokenNumUsesLimit)
      }),
      response: {
        200: z.object({
@@ -160,21 +168,22 @@ export const registerIdentityAwsAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(AWS_AUTH.UPDATE.identityId)
      }),
      body: z.object({
-        stsEndpoint: z.string().trim().min(1).optional(),
-        allowedPrincipalArns: validatePrincipalArns,
-        allowedAccountIds: validateAccountIds,
+        stsEndpoint: z.string().trim().min(1).optional().describe(AWS_AUTH.UPDATE.stsEndpoint),
+        allowedPrincipalArns: validatePrincipalArns.describe(AWS_AUTH.UPDATE.allowedPrincipalArns),
+        allowedAccountIds: validateAccountIds.describe(AWS_AUTH.UPDATE.allowedAccountIds),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .optional(),
-        accessTokenTTL: z.number().int().min(0).optional(),
-        accessTokenNumUsesLimit: z.number().int().min(0).optional(),
+          .optional()
+          .describe(AWS_AUTH.UPDATE.accessTokenTrustedIps),
+        accessTokenTTL: z.number().int().min(0).optional().describe(AWS_AUTH.UPDATE.accessTokenTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).optional().describe(AWS_AUTH.UPDATE.accessTokenNumUsesLimit),
        accessTokenMaxTTL: z
          .number()
          .int()
@@ -182,6 +191,7 @@ export const registerIdentityAwsAuthRouter = async (server: FastifyZodProvider)
            message: "accessTokenMaxTTL must have a non zero number"
          })
          .optional()
+          .describe(AWS_AUTH.UPDATE.accessTokenMaxTTL)
      }),
      response: {
        200: z.object({
@@ -236,7 +246,7 @@ export const registerIdentityAwsAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(AWS_AUTH.RETRIEVE.identityId)
      }),
      response: {
        200: z.object({
--- a/backend/src/server/routes/v1/identity-azure-auth-router.ts
+++ b/backend/src/server/routes/v1/identity-azure-auth-router.ts
@@ -19,7 +19,7 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
    schema: {
      description: "Login with Azure Auth",
      body: z.object({
-        identityId: z.string(),
+        identityId: z.string().describe(AZURE_AUTH.LOGIN.identityId),
        jwt: z.string()
      }),
      response: {
@@ -72,19 +72,20 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(AZURE_AUTH.LOGIN.identityId)
      }),
      body: z.object({
-        tenantId: z.string().trim(),
-        resource: z.string().trim(),
-        allowedServicePrincipalIds: validateAzureAuthField,
+        tenantId: z.string().trim().describe(AZURE_AUTH.ATTACH.tenantId),
+        resource: z.string().trim().describe(AZURE_AUTH.ATTACH.resource),
+        allowedServicePrincipalIds: validateAzureAuthField.describe(AZURE_AUTH.ATTACH.allowedServicePrincipalIds),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]),
+          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }])
+          .describe(AZURE_AUTH.ATTACH.accessTokenTrustedIps),
        accessTokenTTL: z
          .number()
          .int()
@@ -92,15 +93,17 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
          .refine((value) => value !== 0, {
            message: "accessTokenTTL must have a non zero number"
          })
-          .default(2592000),
+          .default(2592000)
+          .describe(AZURE_AUTH.ATTACH.accessTokenTTL),
        accessTokenMaxTTL: z
          .number()
          .int()
          .refine((value) => value !== 0, {
            message: "accessTokenMaxTTL must have a non zero number"
          })
-          .default(2592000),
-        accessTokenNumUsesLimit: z.number().int().min(0).default(0)
+          .default(2592000)
+          .describe(AZURE_AUTH.ATTACH.accessTokenMaxTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).default(0).describe(AZURE_AUTH.ATTACH.accessTokenNumUsesLimit)
      }),
      response: {
        200: z.object({
@@ -154,21 +157,24 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(AZURE_AUTH.UPDATE.identityId)
      }),
      body: z.object({
-        tenantId: z.string().trim().optional(),
-        resource: z.string().trim().optional(),
-        allowedServicePrincipalIds: validateAzureAuthField.optional(),
+        tenantId: z.string().trim().optional().describe(AZURE_AUTH.UPDATE.tenantId),
+        resource: z.string().trim().optional().describe(AZURE_AUTH.UPDATE.resource),
+        allowedServicePrincipalIds: validateAzureAuthField
+          .optional()
+          .describe(AZURE_AUTH.UPDATE.allowedServicePrincipalIds),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .optional(),
-        accessTokenTTL: z.number().int().min(0).optional(),
-        accessTokenNumUsesLimit: z.number().int().min(0).optional(),
+          .optional()
+          .describe(AZURE_AUTH.UPDATE.accessTokenTrustedIps),
+        accessTokenTTL: z.number().int().min(0).optional().describe(AZURE_AUTH.UPDATE.accessTokenTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).optional().describe(AZURE_AUTH.UPDATE.accessTokenNumUsesLimit),
        accessTokenMaxTTL: z
          .number()
          .int()
@@ -176,6 +182,7 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
            message: "accessTokenMaxTTL must have a non zero number"
          })
          .optional()
+          .describe(AZURE_AUTH.UPDATE.accessTokenMaxTTL)
      }),
      response: {
        200: z.object({
@@ -229,7 +236,7 @@ export const registerIdentityAzureAuthRouter = async (server: FastifyZodProvider
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(AZURE_AUTH.RETRIEVE.identityId)
      }),
      response: {
        200: z.object({
--- a/backend/src/server/routes/v1/identity-gcp-auth-router.ts
+++ b/backend/src/server/routes/v1/identity-gcp-auth-router.ts
@@ -19,7 +19,7 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
    schema: {
      description: "Login with GCP Auth",
      body: z.object({
-        identityId: z.string(),
+        identityId: z.string().describe(GCP_AUTH.LOGIN.identityId),
        jwt: z.string()
      }),
      response: {
@@ -72,20 +72,21 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(GCP_AUTH.ATTACH.identityId)
      }),
      body: z.object({
        type: z.enum(["iam", "gce"]),
-        allowedServiceAccounts: validateGcpAuthField,
-        allowedProjects: validateGcpAuthField,
-        allowedZones: validateGcpAuthField,
+        allowedServiceAccounts: validateGcpAuthField.describe(GCP_AUTH.ATTACH.allowedServiceAccounts),
+        allowedProjects: validateGcpAuthField.describe(GCP_AUTH.ATTACH.allowedProjects),
+        allowedZones: validateGcpAuthField.describe(GCP_AUTH.ATTACH.allowedZones),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]),
+          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }])
+          .describe(GCP_AUTH.ATTACH.accessTokenTrustedIps),
        accessTokenTTL: z
          .number()
          .int()
@@ -93,15 +94,17 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
          .refine((value) => value !== 0, {
            message: "accessTokenTTL must have a non zero number"
          })
-          .default(2592000),
+          .default(2592000)
+          .describe(GCP_AUTH.ATTACH.accessTokenTTL),
        accessTokenMaxTTL: z
          .number()
          .int()
          .refine((value) => value !== 0, {
            message: "accessTokenMaxTTL must have a non zero number"
          })
-          .default(2592000),
-        accessTokenNumUsesLimit: z.number().int().min(0).default(0)
+          .default(2592000)
+          .describe(GCP_AUTH.ATTACH.accessTokenMaxTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).default(0).describe(GCP_AUTH.ATTACH.accessTokenNumUsesLimit)
      }),
      response: {
        200: z.object({
@@ -157,22 +160,23 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(GCP_AUTH.UPDATE.identityId)
      }),
      body: z.object({
        type: z.enum(["iam", "gce"]).optional(),
-        allowedServiceAccounts: validateGcpAuthField.optional(),
-        allowedProjects: validateGcpAuthField.optional(),
-        allowedZones: validateGcpAuthField.optional(),
+        allowedServiceAccounts: validateGcpAuthField.optional().describe(GCP_AUTH.UPDATE.allowedServiceAccounts),
+        allowedProjects: validateGcpAuthField.optional().describe(GCP_AUTH.UPDATE.allowedProjects),
+        allowedZones: validateGcpAuthField.optional().describe(GCP_AUTH.UPDATE.allowedZones),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .optional(),
-        accessTokenTTL: z.number().int().min(0).optional(),
-        accessTokenNumUsesLimit: z.number().int().min(0).optional(),
+          .optional()
+          .describe(GCP_AUTH.UPDATE.accessTokenTrustedIps),
+        accessTokenTTL: z.number().int().min(0).optional().describe(GCP_AUTH.UPDATE.accessTokenTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).optional().describe(GCP_AUTH.UPDATE.accessTokenNumUsesLimit),
        accessTokenMaxTTL: z
          .number()
          .int()
@@ -180,6 +184,7 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
            message: "accessTokenMaxTTL must have a non zero number"
          })
          .optional()
+          .describe(GCP_AUTH.UPDATE.accessTokenMaxTTL)
      }),
      response: {
        200: z.object({
@@ -235,7 +240,7 @@ export const registerIdentityGcpAuthRouter = async (server: FastifyZodProvider)
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(GCP_AUTH.RETRIEVE.identityId)
      }),
      response: {
        200: z.object({
--- a/backend/src/server/routes/v1/identity-kubernetes-auth-router.ts
+++ b/backend/src/server/routes/v1/identity-kubernetes-auth-router.ts
@@ -30,7 +30,7 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
    schema: {
      description: "Login with Kubernetes Auth",
      body: z.object({
-        identityId: z.string().trim(),
+        identityId: z.string().trim().describe(KUBERNETES_AUTH.LOGIN.identityId),
        jwt: z.string().trim()
      }),
      response: {
@@ -85,22 +85,23 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
        }
      ],
      params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(KUBERNETES_AUTH.ATTACH.identityId)
      }),
      body: z.object({
-        kubernetesHost: z.string().trim().min(1),
-        caCert: z.string().trim().default(""),
-        tokenReviewerJwt: z.string().trim().min(1),
-        allowedNamespaces: z.string(), // TODO: validation
-        allowedNames: z.string(),
-        allowedAudience: z.string(),
+        kubernetesHost: z.string().trim().min(1).describe(KUBERNETES_AUTH.ATTACH.kubernetesHost),
+        caCert: z.string().trim().default("").describe(KUBERNETES_AUTH.ATTACH.caCert),
+        tokenReviewerJwt: z.string().trim().min(1).describe(KUBERNETES_AUTH.ATTACH.tokenReviewerJwt),
+        allowedNamespaces: z.string().describe(KUBERNETES_AUTH.ATTACH.allowedNamespaces), // TODO: validation
+        allowedNames: z.string().describe(KUBERNETES_AUTH.ATTACH.allowedNames),
+        allowedAudience: z.string().describe(KUBERNETES_AUTH.ATTACH.allowedAudience),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]),
+          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }])
+          .describe(KUBERNETES_AUTH.ATTACH.accessTokenTrustedIps),
        accessTokenTTL: z
          .number()
          .int()
@@ -108,15 +109,22 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
          .refine((value) => value !== 0, {
            message: "accessTokenTTL must have a non zero number"
          })
-          .default(2592000),
+          .default(2592000)
+          .describe(KUBERNETES_AUTH.ATTACH.accessTokenTTL),
        accessTokenMaxTTL: z
          .number()
          .int()
          .refine((value) => value !== 0, {
            message: "accessTokenMaxTTL must have a non zero number"
          })
-          .default(2592000),
-        accessTokenNumUsesLimit: z.number().int().min(0).default(0)
+          .default(2592000)
+          .describe(KUBERNETES_AUTH.ATTACH.accessTokenMaxTTL),
+        accessTokenNumUsesLimit: z
+          .number()
+          .int()
+          .min(0)
+          .default(0)
+          .describe(KUBERNETES_AUTH.ATTACH.accessTokenNumUsesLimit)
      }),
      response: {
        200: z.object({
@@ -171,24 +179,30 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(KUBERNETES_AUTH.UPDATE.identityId)
      }),
      body: z.object({
-        kubernetesHost: z.string().trim().min(1).optional(),
-        caCert: z.string().trim().optional(),
-        tokenReviewerJwt: z.string().trim().min(1).optional(),
-        allowedNamespaces: z.string().optional(), // TODO: validation
-        allowedNames: z.string().optional(),
-        allowedAudience: z.string().optional(),
+        kubernetesHost: z.string().trim().min(1).optional().describe(KUBERNETES_AUTH.UPDATE.kubernetesHost),
+        caCert: z.string().trim().optional().describe(KUBERNETES_AUTH.UPDATE.caCert),
+        tokenReviewerJwt: z.string().trim().min(1).optional().describe(KUBERNETES_AUTH.UPDATE.tokenReviewerJwt),
+        allowedNamespaces: z.string().optional().describe(KUBERNETES_AUTH.UPDATE.allowedNamespaces), // TODO: validation
+        allowedNames: z.string().optional().describe(KUBERNETES_AUTH.UPDATE.allowedNames),
+        allowedAudience: z.string().optional().describe(KUBERNETES_AUTH.UPDATE.allowedAudience),
        accessTokenTrustedIps: z
          .object({
            ipAddress: z.string().trim()
          })
          .array()
          .min(1)
-          .optional(),
-        accessTokenTTL: z.number().int().min(0).optional(),
-        accessTokenNumUsesLimit: z.number().int().min(0).optional(),
+          .optional()
+          .describe(KUBERNETES_AUTH.UPDATE.accessTokenTrustedIps),
+        accessTokenTTL: z.number().int().min(0).optional().describe(KUBERNETES_AUTH.UPDATE.accessTokenTTL),
+        accessTokenNumUsesLimit: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe(KUBERNETES_AUTH.UPDATE.accessTokenNumUsesLimit),
        accessTokenMaxTTL: z
          .number()
          .int()
@@ -196,6 +210,7 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
            message: "accessTokenMaxTTL must have a non zero number"
          })
          .optional()
+          .describe(KUBERNETES_AUTH.UPDATE.accessTokenMaxTTL)
      }),
      response: {
        200: z.object({
@@ -250,7 +265,7 @@ export const registerIdentityKubernetesRouter = async (server: FastifyZodProvide
        }
      ],
      params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(KUBERNETES_AUTH.RETRIEVE.identityId)
      }),
      response: {
        200: z.object({