From 8fdd82a335bc2d7c4a7614a81b5785b9f095d02e Mon Sep 17 00:00:00 2001 From: Tuan Dang Date: Wed, 10 Jul 2024 23:37:36 +0700 Subject: [PATCH] Add token auth to api reference --- backend/src/lib/api-docs/constants.ts | 69 +++++++++++++++---- .../routes/v1/identity-token-auth-router.ts | 61 ++++++++-------- .../endpoints/token-auth/attach.mdx | 4 ++ .../endpoints/token-auth/create-token.mdx | 4 ++ .../endpoints/token-auth/get-tokens.mdx | 4 ++ .../endpoints/token-auth/retrieve.mdx | 4 ++ .../endpoints/token-auth/revoke-token.mdx | 4 ++ .../endpoints/token-auth/revoke.mdx | 4 ++ .../endpoints/token-auth/update-token.mdx | 4 ++ .../endpoints/token-auth/update.mdx | 4 ++ docs/mint.json | 13 ++++ 11 files changed, 128 insertions(+), 47 deletions(-) create mode 100644 docs/api-reference/endpoints/token-auth/attach.mdx create mode 100644 docs/api-reference/endpoints/token-auth/create-token.mdx create mode 100644 docs/api-reference/endpoints/token-auth/get-tokens.mdx create mode 100644 docs/api-reference/endpoints/token-auth/retrieve.mdx create mode 100644 docs/api-reference/endpoints/token-auth/revoke-token.mdx create mode 100644 docs/api-reference/endpoints/token-auth/revoke.mdx create mode 100644 docs/api-reference/endpoints/token-auth/update-token.mdx create mode 100644 docs/api-reference/endpoints/token-auth/update.mdx diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts index 1d11d1e59..a7c1b4c3b 100644 --- a/backend/src/lib/api-docs/constants.ts +++ b/backend/src/lib/api-docs/constants.ts @@ -70,13 +70,13 @@ export const UNIVERSAL_AUTH = { "The maximum number of times that an access token can be used; a value of 0 implies infinite number of uses." }, RETRIEVE: { - identityId: "The ID of the identity to retrieve." + identityId: "The ID of the identity to retrieve the auth method for." }, REVOKE: { - identityId: "The ID of the identity to revoke." + identityId: "The ID of the identity to revoke the auth method for." }, UPDATE: { - identityId: "The ID of the identity to update.", + identityId: "The ID of the identity to update the auth method for.", clientSecretTrustedIps: "The new list of IPs or CIDR ranges that the Client Secret can be used from.", accessTokenTrustedIps: "The new list of IPs or CIDR ranges that access tokens can be used from.", accessTokenTTL: "The new lifetime for an access token in seconds.", @@ -132,7 +132,7 @@ export const AWS_AUTH = { accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from." }, UPDATE: { - identityId: "The ID of the identity to be updated.", + identityId: "The ID of the identity to update the auth method for.", allowedPrincipalArns: "The new comma-separated list of trusted IAM principal ARNs that are allowed to authenticate with Infisical.", allowedAccountIds: @@ -144,10 +144,10 @@ export const AWS_AUTH = { accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from." }, RETRIEVE: { - identityId: "The ID of the identity to retrieve." + identityId: "The ID of the identity to retrieve the auth method for." }, REVOKE: { - identityId: "The ID of the identity to revoke." + identityId: "The ID of the identity to revoke the auth method for." } } as const; @@ -167,7 +167,7 @@ export const AZURE_AUTH = { accessTokenNumUsesLimit: "The maximum number of times that an access token can be used." }, UPDATE: { - identityId: "The ID of the identity to be updated.", + identityId: "The ID of the identity to update the auth method for.", tenantId: "The new tenant ID for the Azure AD organization.", resource: "The new resource URL for the application registered in Azure AD.", allowedServicePrincipalIds: @@ -178,10 +178,10 @@ export const AZURE_AUTH = { accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used." }, RETRIEVE: { - identityId: "The ID of the identity to retrieve." + identityId: "The ID of the identity to retrieve the auth method for." }, REVOKE: { - identityId: "The ID of the identity to revoke." + identityId: "The ID of the identity to revoke the auth method for." } } as const; @@ -203,7 +203,7 @@ export const GCP_AUTH = { accessTokenNumUsesLimit: "The maximum number of times that an access token can be used." }, UPDATE: { - identityId: "The ID of the identity to be updated.", + identityId: "The ID of the identity to update the auth method for.", allowedServiceAccounts: "The new comma-separated list of trusted service account emails corresponding to the GCE resource(s) allowed to authenticate with Infisical.", allowedProjects: @@ -216,10 +216,10 @@ export const GCP_AUTH = { accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used." }, RETRIEVE: { - identityId: "The ID of the identity to retrieve." + identityId: "The ID of the identity to retrieve the auth method for." }, REVOKE: { - identityId: "The ID of the identity to revoke." + identityId: "The ID of the identity to revoke the auth method for." } } as const; @@ -244,7 +244,7 @@ export const KUBERNETES_AUTH = { accessTokenNumUsesLimit: "The maximum number of times that an access token can be used." }, UPDATE: { - identityId: "The ID of the identity to be updated.", + identityId: "The ID of the identity to update the auth method for.", 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: @@ -260,10 +260,49 @@ export const KUBERNETES_AUTH = { accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used." }, RETRIEVE: { - identityId: "The ID of the identity to retrieve." + identityId: "The ID of the identity to retrieve the auth method for." }, REVOKE: { - identityId: "The ID of the identity to revoke." + identityId: "The ID of the identity to revoke the auth method for." + } +} as const; + +export const TOKEN_AUTH = { + ATTACH: { + identityId: "The ID of the identity to attach the configuration onto.", + 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 update the auth method for.", + 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 the auth method for." + }, + REVOKE: { + identityId: "The ID of the identity to revoke the auth method for." + }, + GET_TOKENS: { + identityId: "The ID of the identity to list token metadata for.", + offset: "The offset to start from. If you enter 10, it will start from the 10th token.", + limit: "The number of tokens to return" + }, + CREATE_TOKEN: { + identityId: "The ID of the identity to create the token for.", + name: "The name of the token to create" + }, + UPDATE_TOKEN: { + tokenId: "The ID of the token to update metadata for", + name: "The name of the token to update to" + }, + REVOKE_TOKEN: { + tokenId: "The ID of the token to revoke" } } as const; diff --git a/backend/src/server/routes/v1/identity-token-auth-router.ts b/backend/src/server/routes/v1/identity-token-auth-router.ts index ac36c3c58..752447538 100644 --- a/backend/src/server/routes/v1/identity-token-auth-router.ts +++ b/backend/src/server/routes/v1/identity-token-auth-router.ts @@ -2,6 +2,7 @@ import { z } from "zod"; import { IdentityAccessTokensSchema, IdentityTokenAuthsSchema } from "@app/db/schemas"; import { EventType } from "@app/ee/services/audit-log/audit-log-types"; +import { TOKEN_AUTH } from "@app/lib/api-docs"; import { readLimit, writeLimit } from "@app/server/config/rateLimiter"; import { verifyAuth } from "@app/server/plugins/auth/verify-auth"; import { AuthMode } from "@app/services/auth/auth-type"; @@ -23,7 +24,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider } ], params: z.object({ - identityId: z.string().trim() + identityId: z.string().trim().describe(TOKEN_AUTH.ATTACH.identityId) }), body: z.object({ accessTokenTrustedIps: z @@ -32,7 +33,8 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }) .array() .min(1) - .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]), + .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]) + .describe(TOKEN_AUTH.ATTACH.accessTokenTrustedIps), accessTokenTTL: z .number() .int() @@ -40,15 +42,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider .refine((value) => value !== 0, { message: "accessTokenTTL must have a non zero number" }) - .default(2592000), + .default(2592000) + .describe(TOKEN_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(TOKEN_AUTH.ATTACH.accessTokenMaxTTL), + accessTokenNumUsesLimit: z.number().int().min(0).default(0).describe(TOKEN_AUTH.ATTACH.accessTokenNumUsesLimit) }), response: { 200: z.object({ @@ -102,7 +106,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider } ], params: z.object({ - identityId: z.string().trim() + identityId: z.string().trim().describe(TOKEN_AUTH.UPDATE.identityId) }), body: z.object({ accessTokenTrustedIps: z @@ -111,9 +115,10 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }) .array() .min(1) - .optional(), - accessTokenTTL: z.number().int().min(0).optional(), - accessTokenNumUsesLimit: z.number().int().min(0).optional(), + .optional() + .describe(TOKEN_AUTH.UPDATE.accessTokenTrustedIps), + accessTokenTTL: z.number().int().min(0).optional().describe(TOKEN_AUTH.UPDATE.accessTokenTTL), + accessTokenNumUsesLimit: z.number().int().min(0).optional().describe(TOKEN_AUTH.UPDATE.accessTokenNumUsesLimit), accessTokenMaxTTL: z .number() .int() @@ -121,6 +126,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider message: "accessTokenMaxTTL must have a non zero number" }) .optional() + .describe(TOKEN_AUTH.UPDATE.accessTokenMaxTTL) }), response: { 200: z.object({ @@ -174,7 +180,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider } ], params: z.object({ - identityId: z.string() + identityId: z.string().describe(TOKEN_AUTH.RETRIEVE.identityId) }), response: { 200: z.object({ @@ -221,7 +227,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider } ], params: z.object({ - identityId: z.string() + identityId: z.string().describe(TOKEN_AUTH.REVOKE.identityId) }), response: { 200: z.object({ @@ -253,15 +259,6 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider } }); - // proposed - // update token by id: PATCH /token-auth/tokens/:tokenId - // revoke token by id: POST /token-auth/tokens/:tokenId/revoke - - // current - // revoke token by id: POST /token/revoke-by-id - - // token-auth/identities/:identityId/tokens - server.route({ method: "POST", url: "/token-auth/identities/:identityId/tokens", @@ -270,17 +267,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }, onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]), schema: { - description: "Create token for identity with Token Auth configured", + description: "Create token for identity with Token Auth", security: [ { bearerAuth: [] } ], params: z.object({ - identityId: z.string() + identityId: z.string().describe(TOKEN_AUTH.CREATE_TOKEN.identityId) }), body: z.object({ - name: z.string().optional() + name: z.string().optional().describe(TOKEN_AUTH.CREATE_TOKEN.name) }), response: { 200: z.object({ @@ -331,18 +328,18 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }, onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]), schema: { - description: "Get tokens for identity with Token Auth configured", + description: "Get tokens for identity with Token Auth", security: [ { bearerAuth: [] } ], params: z.object({ - identityId: z.string() + identityId: z.string().describe(TOKEN_AUTH.GET_TOKENS.identityId) }), querystring: z.object({ - offset: z.coerce.number().min(0).max(100).default(0), - limit: z.coerce.number().min(1).max(100).default(20) + offset: z.coerce.number().min(0).max(100).default(0).describe(TOKEN_AUTH.GET_TOKENS.offset), + limit: z.coerce.number().min(1).max(100).default(20).describe(TOKEN_AUTH.GET_TOKENS.limit) }), response: { 200: z.object({ @@ -383,17 +380,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }, onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]), schema: { - description: "Update token for identity with Token Auth configured", + description: "Update token for identity with Token Auth", security: [ { bearerAuth: [] } ], params: z.object({ - tokenId: z.string() + tokenId: z.string().describe(TOKEN_AUTH.UPDATE_TOKEN.tokenId) }), body: z.object({ - name: z.string().optional() + name: z.string().optional().describe(TOKEN_AUTH.UPDATE_TOKEN.name) }), response: { 200: z.object({ @@ -436,14 +433,14 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider }, onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]), schema: { - description: "Revoke token for identity with Token Auth configured", + description: "Revoke token for identity with Token Auth", security: [ { bearerAuth: [] } ], params: z.object({ - tokenId: z.string() + tokenId: z.string().describe(TOKEN_AUTH.REVOKE_TOKEN.tokenId) }), response: { 200: z.object({ diff --git a/docs/api-reference/endpoints/token-auth/attach.mdx b/docs/api-reference/endpoints/token-auth/attach.mdx new file mode 100644 index 000000000..a53855db3 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/attach.mdx @@ -0,0 +1,4 @@ +--- +title: "Attach" +openapi: "POST /api/v1/auth/token-auth/identities/{identityId}" +--- diff --git a/docs/api-reference/endpoints/token-auth/create-token.mdx b/docs/api-reference/endpoints/token-auth/create-token.mdx new file mode 100644 index 000000000..e147a4e12 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/create-token.mdx @@ -0,0 +1,4 @@ +--- +title: "Create Token" +openapi: "POST /api/v1/auth/token-auth/identities/{identityId}/tokens" +--- diff --git a/docs/api-reference/endpoints/token-auth/get-tokens.mdx b/docs/api-reference/endpoints/token-auth/get-tokens.mdx new file mode 100644 index 000000000..5f690a298 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/get-tokens.mdx @@ -0,0 +1,4 @@ +--- +title: "Get Tokens" +openapi: "GET /api/v1/auth/token-auth/identities/{identityId}/tokens" +--- diff --git a/docs/api-reference/endpoints/token-auth/retrieve.mdx b/docs/api-reference/endpoints/token-auth/retrieve.mdx new file mode 100644 index 000000000..ed6bb762c --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/retrieve.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve" +openapi: "GET /api/v1/auth/token-auth/identities/{identityId}" +--- diff --git a/docs/api-reference/endpoints/token-auth/revoke-token.mdx b/docs/api-reference/endpoints/token-auth/revoke-token.mdx new file mode 100644 index 000000000..ca6a0f056 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/revoke-token.mdx @@ -0,0 +1,4 @@ +--- +title: "Revoke Token" +openapi: "POST /api/v1/auth/token-auth/tokens/{tokenId}/revoke" +--- diff --git a/docs/api-reference/endpoints/token-auth/revoke.mdx b/docs/api-reference/endpoints/token-auth/revoke.mdx new file mode 100644 index 000000000..52e295fd0 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/revoke.mdx @@ -0,0 +1,4 @@ +--- +title: "Revoke" +openapi: "DELETE /api/v1/auth/token-auth/identities/{identityId}" +--- diff --git a/docs/api-reference/endpoints/token-auth/update-token.mdx b/docs/api-reference/endpoints/token-auth/update-token.mdx new file mode 100644 index 000000000..cf5e0f568 --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/update-token.mdx @@ -0,0 +1,4 @@ +--- +title: "Update Token" +openapi: "PATCH /api/v1/auth/token-auth/tokens/{tokenId}" +--- diff --git a/docs/api-reference/endpoints/token-auth/update.mdx b/docs/api-reference/endpoints/token-auth/update.mdx new file mode 100644 index 000000000..c9e332e8f --- /dev/null +++ b/docs/api-reference/endpoints/token-auth/update.mdx @@ -0,0 +1,4 @@ +--- +title: "Update" +openapi: "PATCH /api/v1/auth/token-auth/identities/{identityId}" +--- diff --git a/docs/mint.json b/docs/mint.json index bca6e594a..5fc63dd12 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -427,6 +427,19 @@ "api-reference/endpoints/identities/list" ] }, + { + "group": "Token Auth", + "pages": [ + "api-reference/endpoints/token-auth/attach", + "api-reference/endpoints/token-auth/retrieve", + "api-reference/endpoints/token-auth/update", + "api-reference/endpoints/token-auth/revoke", + "api-reference/endpoints/token-auth/get-tokens", + "api-reference/endpoints/token-auth/create-token", + "api-reference/endpoints/token-auth/update-token", + "api-reference/endpoints/token-auth/revoke-token" + ] + }, { "group": "Universal Auth", "pages": [