mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-10-08 22:28:15 +00:00
140 lines
7.9 KiB
Plaintext
140 lines
7.9 KiB
Plaintext
---
|
||
title: Universal Auth
|
||
description: "Authenticate with Infisical from any platform/environment"
|
||
---
|
||
|
||
**Universal Auth** is the most versatile authentication method that can be configured on an identity from any platform/environment to access Infisical.
|
||
|
||
In this method, each identity is given a **Client ID** for which you can generate one or more **Client Secret(s)**. Together, a **Client ID** and **Client Secret** can be exchanged for an access token to authenticate with the Infisical API.
|
||
|
||
## Properties
|
||
|
||
Universal Auth supports many settings that can be beneficial for tightening your workflow security configuration:
|
||
|
||
- Support for restrictions on the number of times that the **Client Secret(s)** and access token(s) can be used.
|
||
- Support for expiration, so, if specified, the **Client Secret** of the identity will automatically be defunct after a period of time.
|
||
- Support for IP allowlisting; this means you can restrict the usage of **Client Secret(s)** and access token to a specific IP or CIDR range.
|
||
|
||
## Workflow
|
||
|
||
In the following steps, we explore how to create and use identities for your workloads and applications to access the Infisical API
|
||
using the Universal Auth authentication method.
|
||
|
||
<Steps>
|
||
<Step title="Creating an identity">
|
||
To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
|
||
|
||
|
||
|
||
When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.
|
||
|
||
|
||
|
||
Now input a few details for your new identity. Here's some guidance for each field:
|
||
|
||
- Name (required): A friendly name for the identity.
|
||
- Role (required): A role from the **Organization Roles** tab to permit the identity to access certain resources.
|
||
|
||
Once you've created an identity, you'll be prompted to configure the **Universal Auth** authentication method for it.
|
||
|
||
|
||
|
||
Here's some more guidance on each field:
|
||
|
||
- Access Token TTL (default is `7200`): The incremental lifetime for an acccess token in seconds; a value of `0` implies an infinite incremental lifetime.
|
||
- Access Token Max TTL (default is `7200`): The maximum lifetime for an acccess token in seconds; a value of `0` implies an infinite maximum lifetime.
|
||
- 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` entry representing all possible IPv4 addresses.
|
||
- 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` entry representing all possible IPv4 addresses.
|
||
|
||
<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 [email protected] to purchase an enterprise license to use it.
|
||
</Warning>
|
||
|
||
</Step>
|
||
<Step title="Creating a Client Secret">
|
||
In order to use the identity, you'll need the non-sensitive **Client ID**
|
||
of the identity and a **Client Secret** for it; you can think of these credentials akin to a username
|
||
and password used to authenticate with the Infisical API. With that, press on the key icon on the identity to generate a **Client Secret**
|
||
for it.
|
||
|
||
|
||
|
||
|
||
|
||
Feel free to input any (optional) details for the **Client Secret** configuration:
|
||
|
||
- 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.
|
||
|
||
To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**.
|
||
|
||
Next, select the identity you want to add to the project and the role you want to assign it.
|
||
|
||
|
||
|
||
|
||
</Step>
|
||
<Step title="Accessing the Infisical API with the identity">
|
||
To access the Infisical API as the identity, you should first perform a login operation
|
||
that is to exchange the **Client ID** and **Client Secret** of the identity for an access token
|
||
by making a request to the `/api/v1/auth/universal-auth/login` endpoint.
|
||
|
||
#### Sample request
|
||
|
||
```
|
||
curl --location --request POST 'https://app.infisical.com/api/v1/auth/universal-auth/login' \
|
||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||
--data-urlencode 'clientSecret=...' \
|
||
--data-urlencode 'clientId=...'
|
||
```
|
||
|
||
#### Sample response
|
||
|
||
```
|
||
{
|
||
"accessToken": "...",
|
||
"expiresIn": 7200,
|
||
"tokenType": "Bearer"
|
||
}
|
||
```
|
||
|
||
Next, you can use the access token to authenticate with the [Infisical API](/api-reference/overview/introduction)
|
||
|
||
<Note>
|
||
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
|
||
the default TTL is `7200` seconds which can be adjusted.
|
||
|
||
If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
|
||
a new access token should be obtained from the aforementioned login operation.
|
||
</Note>
|
||
</Step>
|
||
</Steps>
|
||
|
||
**FAQ**
|
||
|
||
<AccordionGroup>
|
||
<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 insufficently permissioned to interact with the resources you wish to access.
|
||
- You are attempting to access a `/raw` secrets endpoint that requires your project to disable E2EE.
|
||
- The client secret/access token is being used from an untrusted IP.
|
||
</Accordion>
|
||
<Accordion title="What is token renewal and TTL/Max TTL?">
|
||
A identity access token can have a time-to-live (TTL) or incremental lifetime afterwhich it expires.
|
||
|
||
In certain cases, you may want to extend the lifespan of an access token; to do so, you must use the max TTL parameter.
|
||
When TTL and max TTL are equal, a token is not renewable; when max TTL is greater than TTL, a token is renewable.
|
||
In the latter case, a token still expires at its TTL but its lifetime can be extended/renewed up until its max TLL.
|
||
|
||
Note that the max TTL cannot be less than the TTL for an access token.
|
||
</Accordion>
|
||
</AccordionGroup> |