awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3666 from Infisical/feat/add-token-period-support

Browse Source 
feat: add token period support for ua
This commit is contained in:
Maidul Islam
2025-05-28 17:38:59 -04:00
committed by GitHub
parent 5fe93dc35a e74117b7fd
commit e2c49878c6
26 changed files with 384 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
backend/src/db/migrations/20250527164523_add-mi-access-token-period.ts Normal file
View File

@@ -0,0 +1,139 @@
import { Knex } from "knex";
import { TableName } from "../schemas";
export async function up(knex: Knex): Promise<void> {
if (!(await knex.schema.hasColumn(TableName.IdentityAccessToken, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityAccessToken, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityUniversalAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityUniversalAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityAwsAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityAwsAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityOidcAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityOidcAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityAzureAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityAzureAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityGcpAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityGcpAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityJwtAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityJwtAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityKubernetesAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityKubernetesAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityLdapAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityLdapAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityOciAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityOciAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
if (!(await knex.schema.hasColumn(TableName.IdentityTokenAuth, "accessTokenPeriod"))) {
await knex.schema.alterTable(TableName.IdentityTokenAuth, (t) => {
t.bigInteger("accessTokenPeriod").defaultTo(0).notNullable();
});
}
}
export async function down(knex: Knex): Promise<void> {
if (await knex.schema.hasColumn(TableName.IdentityAccessToken, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityAccessToken, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityUniversalAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityUniversalAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityAwsAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityAwsAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityOidcAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityOidcAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityAzureAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityAzureAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityGcpAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityGcpAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityJwtAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityJwtAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityKubernetesAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityKubernetesAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityLdapAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityLdapAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityOciAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityOciAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
if (await knex.schema.hasColumn(TableName.IdentityTokenAuth, "accessTokenPeriod")) {
await knex.schema.alterTable(TableName.IdentityTokenAuth, (t) => {
t.dropColumn("accessTokenPeriod");
});
}
}

3
backend/src/db/schemas/identity-access-tokens.ts
View File

@@ -21,7 +21,8 @@ export const IdentityAccessTokensSchema = z.object({
createdAt: z.date(),
updatedAt: z.date(),
name: z.string().nullable().optional(),
authMethod: z.string()
authMethod: z.string(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityAccessTokens = z.infer<typeof IdentityAccessTokensSchema>;

3
backend/src/db/schemas/identity-aws-auths.ts
View File

@@ -19,7 +19,8 @@ export const IdentityAwsAuthsSchema = z.object({
type: z.string(),
stsEndpoint: z.string(),
allowedPrincipalArns: z.string(),
allowedAccountIds: z.string()
allowedAccountIds: z.string(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityAwsAuths = z.infer<typeof IdentityAwsAuthsSchema>;

3
backend/src/db/schemas/identity-azure-auths.ts
View File

@@ -18,7 +18,8 @@ export const IdentityAzureAuthsSchema = z.object({
identityId: z.string().uuid(),
tenantId: z.string(),
resource: z.string(),
allowedServicePrincipalIds: z.string()
allowedServicePrincipalIds: z.string(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityAzureAuths = z.infer<typeof IdentityAzureAuthsSchema>;

3
backend/src/db/schemas/identity-gcp-auths.ts
View File

@@ -19,7 +19,8 @@ export const IdentityGcpAuthsSchema = z.object({
type: z.string(),
allowedServiceAccounts: z.string().nullable().optional(),
allowedProjects: z.string().nullable().optional(),
allowedZones: z.string().nullable().optional()
allowedZones: z.string().nullable().optional(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityGcpAuths = z.infer<typeof IdentityGcpAuthsSchema>;

3
backend/src/db/schemas/identity-jwt-auths.ts
View File

@@ -25,7 +25,8 @@ export const IdentityJwtAuthsSchema = z.object({
boundClaims: z.unknown(),
boundSubject: z.string(),
createdAt: z.date(),
updatedAt: z.date()
updatedAt: z.date(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityJwtAuths = z.infer<typeof IdentityJwtAuthsSchema>;

3
backend/src/db/schemas/identity-kubernetes-auths.ts
View File

@@ -30,7 +30,8 @@ export const IdentityKubernetesAuthsSchema = z.object({
allowedAudience: z.string(),
encryptedKubernetesTokenReviewerJwt: zodBuffer.nullable().optional(),
encryptedKubernetesCaCertificate: zodBuffer.nullable().optional(),
gatewayId: z.string().uuid().nullable().optional()
gatewayId: z.string().uuid().nullable().optional(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityKubernetesAuths = z.infer<typeof IdentityKubernetesAuthsSchema>;

3
backend/src/db/schemas/identity-ldap-auths.ts
View File

@@ -24,7 +24,8 @@ export const IdentityLdapAuthsSchema = z.object({
searchFilter: z.string(),
allowedFields: z.unknown().nullable().optional(),
createdAt: z.date(),
updatedAt: z.date()
updatedAt: z.date(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityLdapAuths = z.infer<typeof IdentityLdapAuthsSchema>;

3
backend/src/db/schemas/identity-oci-auths.ts
View File

@@ -18,7 +18,8 @@ export const IdentityOciAuthsSchema = z.object({
identityId: z.string().uuid(),
type: z.string(),
tenancyOcid: z.string(),
allowedUsernames: z.string().nullable().optional()
allowedUsernames: z.string().nullable().optional(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityOciAuths = z.infer<typeof IdentityOciAuthsSchema>;

3
backend/src/db/schemas/identity-oidc-auths.ts
View File

@@ -27,7 +27,8 @@ export const IdentityOidcAuthsSchema = z.object({
createdAt: z.date(),
updatedAt: z.date(),
encryptedCaCertificate: zodBuffer.nullable().optional(),
claimMetadataMapping: z.unknown().nullable().optional()
claimMetadataMapping: z.unknown().nullable().optional(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityOidcAuths = z.infer<typeof IdentityOidcAuthsSchema>;

3
backend/src/db/schemas/identity-token-auths.ts
View File

@@ -15,7 +15,8 @@ export const IdentityTokenAuthsSchema = z.object({
accessTokenTrustedIps: z.unknown(),
createdAt: z.date(),
updatedAt: z.date(),
identityId: z.string().uuid()
identityId: z.string().uuid(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityTokenAuths = z.infer<typeof IdentityTokenAuthsSchema>;

3
backend/src/db/schemas/identity-universal-auths.ts
View File

@@ -17,7 +17,8 @@ export const IdentityUniversalAuthsSchema = z.object({
accessTokenTrustedIps: z.unknown(),
createdAt: z.date(),
updatedAt: z.date(),
identityId: z.string().uuid()
identityId: z.string().uuid(),
accessTokenPeriod: z.coerce.number().default(0)
});
export type TIdentityUniversalAuths = z.infer<typeof IdentityUniversalAuthsSchema>;

7
backend/src/lib/api-docs/constants.ts
View File

@@ -147,7 +147,9 @@ export const UNIVERSAL_AUTH = {
accessTokenMaxTTL:
"The maximum lifetime for an access token in seconds. This value will be referenced at renewal time.",
accessTokenNumUsesLimit:
"The maximum number of times that an access token can be used; a value of 0 implies infinite number of uses."
"The maximum number of times that an access token can be used; a value of 0 implies infinite number of uses.",
accessTokenPeriod:
"The period for an access token in seconds. This value will be referenced at renewal time. Default value is 0."
},
RETRIEVE: {
identityId: "The ID of the identity to retrieve the auth method for."
@@ -161,7 +163,8 @@ export const UNIVERSAL_AUTH = {
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.",
accessTokenMaxTTL: "The new maximum lifetime for an access token in seconds.",
accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used.",
accessTokenPeriod: "The new period for an access token in seconds."
},
CREATE_CLIENT_SECRET: {
identityId: "The ID of the identity to create a client secret for.",

28
backend/src/server/routes/v1/identity-universal-auth-router.ts
View File

@@ -47,8 +47,15 @@ export const registerIdentityUaRouter = async (server: FastifyZodProvider) => {
}
},
handler: async (req) => {
const { identityUa, accessToken, identityAccessToken, validClientSecretInfo, identityMembershipOrg } =
await server.services.identityUa.login(req.body.clientId, req.body.clientSecret, req.realIp);
const {
identityUa,
accessToken,
identityAccessToken,
validClientSecretInfo,
identityMembershipOrg,
accessTokenTTL,
accessTokenMaxTTL
} = await server.services.identityUa.login(req.body.clientId, req.body.clientSecret, req.realIp);
await server.services.auditLog.createAuditLog({
...req.auditLogInfo,
@@ -63,11 +70,12 @@ export const registerIdentityUaRouter = async (server: FastifyZodProvider) => {
}
}
});
return {
accessToken,
tokenType: "Bearer" as const,
expiresIn: identityUa.accessTokenTTL,
accessTokenMaxTTL: identityUa.accessTokenMaxTTL
expiresIn: accessTokenTTL,
accessTokenMaxTTL
};
}
});
@@ -128,7 +136,8 @@ export const registerIdentityUaRouter = async (server: FastifyZodProvider) => {
.int()
.min(0)
.default(0)
.describe(UNIVERSAL_AUTH.ATTACH.accessTokenNumUsesLimit)
.describe(UNIVERSAL_AUTH.ATTACH.accessTokenNumUsesLimit),
accessTokenPeriod: z.number().int().min(0).default(0).describe(UNIVERSAL_AUTH.ATTACH.accessTokenPeriod)
})
.refine(
(val) => val.accessTokenTTL <= val.accessTokenMaxTTL,
@@ -227,7 +236,14 @@ export const registerIdentityUaRouter = async (server: FastifyZodProvider) => {
.min(0)
.max(315360000)
.optional()
.describe(UNIVERSAL_AUTH.UPDATE.accessTokenMaxTTL)
.describe(UNIVERSAL_AUTH.UPDATE.accessTokenMaxTTL),
accessTokenPeriod: z
.number()
.int()
.min(0)
.max(315360000)
.optional()
.describe(UNIVERSAL_AUTH.UPDATE.accessTokenPeriod)
})
.refine(
(val) => (val.accessTokenMaxTTL && val.accessTokenTTL ? val.accessTokenTTL <= val.accessTokenMaxTTL : true),

30
backend/src/services/identity-access-token/identity-access-token-service.ts
View File

@@ -96,10 +96,15 @@ export const identityAccessTokenServiceFactory = ({
}
await validateAccessTokenExp({ ...identityAccessToken, accessTokenNumUses });
const { accessTokenMaxTTL, createdAt: accessTokenCreatedAt, accessTokenTTL } = identityAccessToken;
const {
accessTokenMaxTTL,
createdAt: accessTokenCreatedAt,
accessTokenTTL,
accessTokenPeriod
} = identityAccessToken;
// max ttl checks - will it go above max ttl
if (Number(accessTokenMaxTTL) > 0) {
// Only enforce Max TTL for non-periodic tokens
if (Number(accessTokenMaxTTL) > 0 && Number(accessTokenPeriod) === 0) {
const accessTokenCreated = new Date(accessTokenCreatedAt);
const ttlInMilliseconds = Number(accessTokenMaxTTL) * 1000;
const currentDate = new Date();
@@ -125,6 +130,18 @@ export const identityAccessTokenServiceFactory = ({
accessTokenLastRenewedAt: new Date()
});
const ttl = Number(accessTokenTTL);
const period = Number(accessTokenPeriod);
let expiresIn: number | undefined;
if (period > 0) {
expiresIn = period;
} else if (ttl > 0) {
expiresIn = ttl;
} else {
expiresIn = undefined;
}
const renewedToken = jwt.sign(
{
identityId: decodedToken.identityId,
@@ -133,12 +150,7 @@ export const identityAccessTokenServiceFactory = ({
authTokenType: AuthTokenType.IDENTITY_ACCESS_TOKEN
} as TIdentityAccessTokenJwtPayload,
appCfg.AUTH_SECRET,
// akhilmhdh: for non-expiry tokens you should not even set the value, including undefined. Even for undefined jsonwebtoken throws error
Number(identityAccessToken.accessTokenTTL) === 0
? undefined
: {
expiresIn: Number(identityAccessToken.accessTokenTTL)
}
expiresIn !== undefined ? { expiresIn } : undefined
);
return { accessToken: renewedToken, identityAccessToken: updatedIdentityAccessToken };

38
backend/src/services/identity-ua/identity-ua-service.ts
View File

@@ -114,21 +114,36 @@ export const identityUaServiceFactory = ({
});
}
const accessTokenTTLParams =
Number(identityUa.accessTokenPeriod) === 0
? {
accessTokenTTL: identityUa.accessTokenTTL,
accessTokenMaxTTL: identityUa.accessTokenMaxTTL
}
: {
accessTokenTTL: identityUa.accessTokenPeriod,
// Setting Max TTL to 2 × period ensures that clients can always renew their token
// at least once, and matches client logic that checks if renewing would exceed Max TTL.
accessTokenMaxTTL: 2 * identityUa.accessTokenPeriod
};
const identityAccessToken = await identityUaDAL.transaction(async (tx) => {
const uaClientSecretDoc = await identityUaClientSecretDAL.incrementUsage(validClientSecretInfo!.id, tx);
const newToken = await identityAccessTokenDAL.create(
{
identityId: identityUa.identityId,
isAccessTokenRevoked: false,
identityUAClientSecretId: uaClientSecretDoc.id,
accessTokenTTL: identityUa.accessTokenTTL,
accessTokenMaxTTL: identityUa.accessTokenMaxTTL,
accessTokenNumUses: 0,
accessTokenNumUsesLimit: identityUa.accessTokenNumUsesLimit,
authMethod: IdentityAuthMethod.UNIVERSAL_AUTH
accessTokenPeriod: identityUa.accessTokenPeriod,
authMethod: IdentityAuthMethod.UNIVERSAL_AUTH,
...accessTokenTTLParams
},
tx
);
return newToken;
});
@@ -149,7 +164,14 @@ export const identityUaServiceFactory = ({
}
);
return { accessToken, identityUa, validClientSecretInfo, identityAccessToken, identityMembershipOrg };
return {
accessToken,
identityUa,
validClientSecretInfo,
identityAccessToken,
identityMembershipOrg,
...accessTokenTTLParams
};
};
const attachUniversalAuth = async ({
@@ -163,7 +185,8 @@ export const identityUaServiceFactory = ({
actorAuthMethod,
actor,
actorOrgId,
isActorSuperAdmin
isActorSuperAdmin,
accessTokenPeriod
}: TAttachUaDTO) => {
await validateIdentityUpdateForSuperAdminPrivileges(identityId, isActorSuperAdmin);
@@ -232,7 +255,8 @@ export const identityUaServiceFactory = ({
accessTokenMaxTTL,
accessTokenTTL,
accessTokenNumUsesLimit,
accessTokenTrustedIps: JSON.stringify(reformattedAccessTokenTrustedIps)
accessTokenTrustedIps: JSON.stringify(reformattedAccessTokenTrustedIps),
accessTokenPeriod
},
tx
);
@@ -248,6 +272,7 @@ export const identityUaServiceFactory = ({
accessTokenTTL,
accessTokenTrustedIps,
clientSecretTrustedIps,
accessTokenPeriod,
actorId,
actorAuthMethod,
actor,
@@ -324,6 +349,7 @@ export const identityUaServiceFactory = ({
accessTokenMaxTTL,
accessTokenTTL,
accessTokenNumUsesLimit,
accessTokenPeriod,
accessTokenTrustedIps: reformattedAccessTokenTrustedIps
? JSON.stringify(reformattedAccessTokenTrustedIps)
: undefined

2
backend/src/services/identity-ua/identity-ua-types.ts
View File

@@ -5,6 +5,7 @@ export type TAttachUaDTO = {
accessTokenTTL: number;
accessTokenMaxTTL: number;
accessTokenNumUsesLimit: number;
accessTokenPeriod: number;
clientSecretTrustedIps: { ipAddress: string }[];
accessTokenTrustedIps: { ipAddress: string }[];
isActorSuperAdmin?: boolean;
@@ -15,6 +16,7 @@ export type TUpdateUaDTO = {
accessTokenTTL?: number;
accessTokenMaxTTL?: number;
accessTokenNumUsesLimit?: number;
accessTokenPeriod?: number;
clientSecretTrustedIps?: { ipAddress: string }[];
accessTokenTrustedIps?: { ipAddress: string }[];
} & Omit<TProjectPermission, "projectId">;

61
docs/documentation/platform/identities/universal-auth.mdx
View File

@@ -4,6 +4,7 @@ description: "Learn how to authenticate to Infisical from any platform or enviro
---
**Universal Auth** is a platform-agnostic authentication method that can be configured for a [machine identity](/documentation/platform/identities/machine-identities) to authenticate from any platform/environment using a Client ID and Client Secret.
This authentication method supports setting token periods, which can help [overcome secret zero](#solving-secret-zero-with-periodic-tokens).
## Diagram
@@ -64,7 +65,8 @@ using the Universal Auth authentication method.
By default, the identity has been configured with Universal Auth. If you wish, you can edit the Universal Auth configuration
details by pressing to edit the **Authentication** section.
![identities organization create universal auth method](/images/platform/identities/identities-org-create-universal-auth-method.png)
![identities organization create universal auth method 1](/images/platform/identities/identities-org-create-universal-auth-method-1.png)
![identities organization create universal auth method 2](/images/platform/identities/identities-org-create-universal-auth-method-2.png)
Here's some more guidance on each field:
@@ -73,11 +75,12 @@ using the Universal Auth authentication method.
- Access Token Max Number of Uses (default is `0`): The maximum number of times that an access token can be used; a value of `0` implies infinite number of uses.
- Client Secret Trusted IPs: The IPs or CIDR ranges that the **Client Secret** can be used from together with the **Client ID** to get back an access token. By default, **Client Secrets** are given the `0.0.0.0/0`, allowing usage from any network address.
- Access Token Trusted IPs: The IPs or CIDR ranges that access tokens can be used from. By default, each token is given the `0.0.0.0/0`, allowing usage from any network address.
- Access Token Period (optional, default is `0`): If set, the access token becomes a renewable, non-expiring token for the specified period (in seconds). TTL and Max TTL are ignored when this is set. This is ideal for "secret zero" scenarios, where a workload needs to bootstrap itself securely without hard-coded static secrets.
<Warning>
Restricting **Client Secret** and access token usage to specific trusted IPs is a paid feature.
If you’re using Infisical Cloud, then it is available under the Pro Tier. If you’re self-hosting Infisical, then you should contact sales@infisical.com to purchase an enterprise license to use it.
If you're using Infisical Cloud, then it is available under the Pro Tier. If you're self-hosting Infisical, then you should contact sales@infisical.com to purchase an enterprise license to use it.
</Warning>
</Step>
@@ -96,6 +99,7 @@ using the Universal Auth authentication method.
- Description: A description for the **Client Secret**.
- TTL (default is `0`): The time-to-live for the **Client Secret**. By default, the TTL will be set to 0 which implies that the **Client Secret** will never expire; a value of `0` implies an infinite lifetime.
- Max Number of Uses (default is `0`): The maximum number of times that the **Client Secret** can be used together with the **Client ID** to get back an access token; a value of `0` implies infinite number of uses.
</Step>
<Step title="Adding an identity to a project">
To enable the identity to access project-level resources such as secrets within a specific project, you should add it to that project.
@@ -154,23 +158,50 @@ using the Universal Auth authentication method.
</Step>
</Steps>
## Solving Secret Zero with Periodic Tokens
In many automated, cloud-native, or ephemeral environments (such as VMs, containers, or serverless functions), it is often unsafe or impractical to hard-code long-lived credentials for bootstrapping access to secrets management systems. The "secret zero" problem refers to the challenge of securely providing a workload with its initial credential, without manual intervention or static secrets that could be leaked or reused. Periodic tokens in Universal Auth are designed to solve this problem by enabling secure, automated bootstrapping and ongoing access renewal, even in dynamic or short-lived environments.
A common challenge in cloud-native and automated environments is the "secret zero" problem: how to securely bootstrap a workload (such as a VM, container, or serverless function) with its first credential, without hard-coding static secrets or requiring manual intervention.
**Periodic tokens** in Universal Auth solve this by allowing you to issue an access token that can be continuously renewed by your workload before it expires (i.e., a client-initiated rotation mechanism):
- When you set the **Access Token Period** in the Universal Auth configuration, the issued access token can be renewed by your workload for the specified period (in seconds).
- The token can be renewed any number of times, each time for the same period, with no maximum lifetime (unless you set a use limit).
- As long as the token is renewed before its period expires, it remains valid, so you do not need to re-issue static credentials.
- TTL and Max TTL are ignored when Access Token Period is set.
### Example: Bootstrapping with a Periodic Token
1. Configure Universal Auth for your identity and set **Access Token Period** (e.g., `3600` for 1 hour).
2. For improved security, configure the Client Secret with a low number of uses (e.g., `1`) or a short TTL. This ensures that after the initial login, the Client Secret cannot be reused, and any disruption in token renewal will require manual intervention.
3. Deploy your workload with the **Client Secret** and **Client ID**.
4. The workload authenticates with Infisical using the Client Secret and Client ID to obtain the initial access token (JWT).
5. The workload uses the access token to authenticate and continuously renews it before expiration:
```bash
curl --location --request POST 'https://app.infisical.com/api/v1/auth/universal-auth/renew' \
--header 'Authorization: Bearer <accessToken>'
```
This approach allows your workload to securely bootstrap and maintain access to Infisical without hard-coded secrets, solving the secret zero problem.
**FAQ**
<AccordionGroup>
<Accordion title="Why is the Infisical API rejecting my identity credentials?">
There are a few reasons for why this might happen:
<Accordion title="Why is the Infisical API rejecting my identity credentials?">
There are a few reasons for why this might happen:
- The client secret or access token has expired.
- The identity is insufficiently permissioned to interact with the resources you wish to access.
- The client secret/access token is being used from an untrusted IP.
</Accordion>
<Accordion title="What is access token renewal and TTL/Max TTL?">
A identity access token can have a time-to-live (TTL) or incremental lifetime after which it expires.
- The client secret or access token has expired.
- The identity is insufficiently permissioned to interact with the resources you wish to access.
- The client secret/access token is being used from an untrusted IP.
</Accordion>
<Accordion title="What is access token renewal and TTL/Max TTL?">
A identity access token can have a time-to-live (TTL) or incremental lifetime after which it expires.
In certain cases, you may want to extend the lifespan of an access token; to do so, you must set a max TTL parameter.
In certain cases, you may want to extend the lifespan of an access token; to do so, you must set a max TTL parameter.
A token can be renewed any number of times where each call to renew it can extend the token's lifetime by increments of the access token's TTL.
Regardless of how frequently an access token is renewed, its lifespan remains bound to the maximum TTL determined at its creation.
A token can be renewed any number of times where each call to renew it can extend the token's lifetime by increments of the access token's TTL.
Regardless of how frequently an access token is renewed, its lifespan remains bound to the maximum TTL determined at its creation.
</Accordion>
</Accordion>
</AccordionGroup>

BIN
docs/images/platform/identities/identities-org-create-universal-auth-method-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 568 KiB

BIN
docs/images/platform/identities/identities-org-create-universal-auth-method-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 539 KiB

BIN
docs/images/platform/identities/identities-org-create-universal-auth-method.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 500 KiB

6
frontend/src/hooks/api/identities/mutations.tsx
View File

@@ -163,7 +163,8 @@ export const useUpdateIdentityUniversalAuth = () => {
accessTokenTTL,
accessTokenMaxTTL,
accessTokenNumUsesLimit,
accessTokenTrustedIps
accessTokenTrustedIps,
accessTokenPeriod
}) => {
const {
data: { identityUniversalAuth }
@@ -172,7 +173,8 @@ export const useUpdateIdentityUniversalAuth = () => {
accessTokenTTL,
accessTokenMaxTTL,
accessTokenNumUsesLimit,
accessTokenTrustedIps
accessTokenTrustedIps,
accessTokenPeriod
});
return identityUniversalAuth;
},

3
frontend/src/hooks/api/identities/types.ts
View File

@@ -107,6 +107,7 @@ export type IdentityUniversalAuth = {
accessTokenMaxTTL: number;
accessTokenNumUsesLimit: number;
accessTokenTrustedIps: IdentityTrustedIp[];
accessTokenPeriod: number;
};
export type AddIdentityUniversalAuthDTO = {
@@ -118,6 +119,7 @@ export type AddIdentityUniversalAuthDTO = {
accessTokenTTL: number;
accessTokenMaxTTL: number;
accessTokenNumUsesLimit: number;
accessTokenPeriod: number;
accessTokenTrustedIps: {
ipAddress: string;
}[];
@@ -132,6 +134,7 @@ export type UpdateIdentityUniversalAuthDTO = {
accessTokenTTL?: number;
accessTokenMaxTTL?: number;
accessTokenNumUsesLimit?: number;
accessTokenPeriod?: number;
accessTokenTrustedIps?: {
ipAddress: string;
}[];

3
frontend/src/pages/organization/AccessManagementPage/components/OrgIdentityTab/components/IdentitySection/IdentityModal.tsx
View File

@@ -138,7 +138,8 @@ export const IdentityModal = ({ popUp, handlePopUpToggle }: Props) => {
accessTokenTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }],
accessTokenTTL: 2592000,
accessTokenMaxTTL: 2592000,
accessTokenNumUsesLimit: 0
accessTokenNumUsesLimit: 0,
accessTokenPeriod: 0
});
handlePopUpToggle("identity", false);

105
frontend/src/pages/organization/AccessManagementPage/components/OrgIdentityTab/components/IdentitySection/IdentityUniversalAuthForm.tsx
View File

@@ -41,6 +41,13 @@ const schema = z
(value) => Number(value) <= 315360000,
"Access Max Token TTL cannot be greater than 315360000"
),
accessTokenPeriod: z
.string()
.optional()
.refine(
(value) => !value || Number(value) <= 315360000,
"Access Token Period cannot be greater than 315360000"
),
accessTokenNumUsesLimit: z.string(),
clientSecretTrustedIps: z
.object({
@@ -90,7 +97,8 @@ export const IdentityUniversalAuthForm = ({
control,
handleSubmit,
reset,
formState: { isSubmitting }
formState: { isSubmitting },
watch
} = useForm<FormData>({
resolver: zodResolver(schema),
defaultValues: {
@@ -98,10 +106,13 @@ export const IdentityUniversalAuthForm = ({
accessTokenMaxTTL: "2592000",
accessTokenNumUsesLimit: "0",
clientSecretTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }],
accessTokenTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]
accessTokenTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }],
accessTokenPeriod: "0"
}
});
const accessTokenPeriodValue = Number(watch("accessTokenPeriod"));
const {
fields: clientSecretTrustedIpsFields,
append: appendClientSecretTrustedIp,
@@ -119,6 +130,7 @@ export const IdentityUniversalAuthForm = ({
accessTokenTTL: String(data.accessTokenTTL),
accessTokenMaxTTL: String(data.accessTokenMaxTTL),
accessTokenNumUsesLimit: String(data.accessTokenNumUsesLimit),
accessTokenPeriod: String(data.accessTokenPeriod),
clientSecretTrustedIps: data.clientSecretTrustedIps.map(
({ ipAddress, prefix }: IdentityTrustedIp) => {
return {
@@ -139,6 +151,7 @@ export const IdentityUniversalAuthForm = ({
accessTokenTTL: "2592000",
accessTokenMaxTTL: "2592000",
accessTokenNumUsesLimit: "0",
accessTokenPeriod: "0",
clientSecretTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }],
accessTokenTrustedIps: [{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]
});
@@ -150,7 +163,8 @@ export const IdentityUniversalAuthForm = ({
accessTokenMaxTTL,
accessTokenNumUsesLimit,
clientSecretTrustedIps,
accessTokenTrustedIps
accessTokenTrustedIps,
accessTokenPeriod
}: FormData) => {
try {
if (!identityId) return;
@@ -164,7 +178,8 @@ export const IdentityUniversalAuthForm = ({
accessTokenTTL: Number(accessTokenTTL),
accessTokenMaxTTL: Number(accessTokenMaxTTL),
accessTokenNumUsesLimit: Number(accessTokenNumUsesLimit),
accessTokenTrustedIps
accessTokenTrustedIps,
accessTokenPeriod: Number(accessTokenPeriod)
});
} else {
// create new universal auth configuration
@@ -176,7 +191,8 @@ export const IdentityUniversalAuthForm = ({
accessTokenTTL: Number(accessTokenTTL),
accessTokenMaxTTL: Number(accessTokenMaxTTL),
accessTokenNumUsesLimit: Number(accessTokenNumUsesLimit),
accessTokenTrustedIps
accessTokenTrustedIps,
accessTokenPeriod: Number(accessTokenPeriod)
});
}
@@ -214,34 +230,42 @@ export const IdentityUniversalAuthForm = ({
<Tab value={IdentityFormTab.Advanced}>Advanced</Tab>
</TabList>
<TabPanel value={IdentityFormTab.Configuration}>
<Controller
control={control}
defaultValue="2592000"
name="accessTokenTTL"
render={({ field, fieldState: { error } }) => (
<FormControl
label="Access Token TTL (seconds)"
isError={Boolean(error)}
errorText={error?.message}
>
<Input {...field} placeholder="2592000" type="number" min="0" step="1" />
</FormControl>
)}
/>
<Controller
control={control}
defaultValue="2592000"
name="accessTokenMaxTTL"
render={({ field, fieldState: { error } }) => (
<FormControl
label="Access Token Max TTL (seconds)"
isError={Boolean(error)}
errorText={error?.message}
>
<Input {...field} placeholder="2592000" type="number" min="0" step="1" />
</FormControl>
)}
/>
{accessTokenPeriodValue > 0 ? (
<div className="mb-4 text-xs text-bunker-400">
When Access Token Period is set, TTL and Max TTL are ignored.
</div>
) : (
<>
<Controller
control={control}
defaultValue="2592000"
name="accessTokenTTL"
render={({ field, fieldState: { error } }) => (
<FormControl
label="Access Token TTL (seconds)"
isError={Boolean(error)}
errorText={error?.message}
>
<Input {...field} placeholder="2592000" type="number" min="0" step="1" />
</FormControl>
)}
/>
<Controller
control={control}
defaultValue="2592000"
name="accessTokenMaxTTL"
render={({ field, fieldState: { error } }) => (
<FormControl
label="Access Token Max TTL (seconds)"
isError={Boolean(error)}
errorText={error?.message}
>
<Input {...field} placeholder="2592000" type="number" min="0" step="1" />
</FormControl>
)}
/>
</>
)}
<Controller
control={control}
defaultValue="0"
@@ -256,6 +280,21 @@ export const IdentityUniversalAuthForm = ({
</FormControl>
)}
/>
<Controller
control={control}
defaultValue="0"
name="accessTokenPeriod"
render={({ field, fieldState: { error } }) => (
<FormControl
label="Access Token Period (seconds)"
isError={Boolean(error)}
errorText={error?.message}
helperText="For periodic tokens: set a period (in seconds) to allow indefinite renewal. Set to 0 to disable periodic tokens and use TTL-based expiration."
>
<Input {...field} placeholder="0" type="number" min="0" step="1" />
</FormControl>
)}
/>
</TabPanel>
<TabPanel value={IdentityFormTab.Advanced}>
{clientSecretTrustedIpsFields.map(({ id }, index) => (

20
frontend/src/pages/organization/IdentityDetailsByIDPage/components/ViewIdentityAuthModal/ViewIdentityUniversalAuthContent.tsx
View File

@@ -62,12 +62,20 @@ export const ViewIdentityUniversalAuthContent = ({
onEdit={() => handlePopUpOpen("identityAuthMethod")}
onDelete={onDelete}
>
<IdentityAuthFieldDisplay label="Access Token TTL (seconds)">
{data.accessTokenTTL}
</IdentityAuthFieldDisplay>
<IdentityAuthFieldDisplay label="Access Token Max TTL (seconds)">
{data.accessTokenMaxTTL}
</IdentityAuthFieldDisplay>
{Number(data.accessTokenPeriod) > 0 ? (
<IdentityAuthFieldDisplay label="Access Token Period (seconds)">
{data.accessTokenPeriod}
</IdentityAuthFieldDisplay>
) : (
<>
<IdentityAuthFieldDisplay label="Access Token TTL (seconds)">
{data.accessTokenTTL}
</IdentityAuthFieldDisplay>
<IdentityAuthFieldDisplay label="Access Token Max TTL (seconds)">
{data.accessTokenMaxTTL}
</IdentityAuthFieldDisplay>
</>
)}
<IdentityAuthFieldDisplay label="Access Token Max Number of Uses">
{data.accessTokenNumUsesLimit}
</IdentityAuthFieldDisplay>