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

doc: added mention of periodic token to ua section

Browse Source
This commit is contained in:
Sheen
2025-05-28 08:10:27 +00:00
parent 98457cdb34
commit 767159bf8f
4 changed files with 41 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -64,7 +64,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 +74,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): 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 +98,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 +157,45 @@ using the Universal Auth authentication method.
</Step>
</Steps>
## Solving Secret Zero with Periodic Tokens
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 a renewable, non-expiring access token to your workload:
- When you set the **Access Token Period** in the Universal Auth configuration, the issued access token becomes renewable 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 and does not require re-issuing 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. Deploy your workload with the initial access token.
3. Your workload uses the access token to authenticate and can renew 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.
</Accordion>
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>
</AccordionGroup>