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

docs, grammar fixes, frontend tweak

Browse Source
This commit is contained in:
x032205
2025-05-09 01:29:11 -04:00
parent b21c17572d
commit a6ee6fc4ea
29 changed files with 251 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/documentation/getting-started/api.mdx
View File

@@ -10,15 +10,15 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
<Step title="Create a project with a secret">
To create a project, head to your Organization Overview and press **Add New Project**; we'll call the project **Demo App**.
![create project](../../images/getting-started/api/org-create-project-1.png)
![create project](../../images/getting-started/api/org-create-project-2.png)
Next, let's head to the **Development** environment of the project and add a secret `FOO=BAR` to it.
![explore project env](../../images/getting-started/api/project-explore-env.png)
![create secret](../../images/getting-started/api/project-create-secret.png)
![project dashboard](../../images/getting-started/api/project-dashboard.png)
<Note>
@@ -29,13 +29,13 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
Next, we need to create an identity to represent your application. To create one, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
![identities organization](../../images/platform/identities/identities-org.png)
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.
![identities organization create](../../images/platform/identities/identities-org-create.png)
Once you've created an identity, you'll be prompted to configure the **Universal Auth** authentication method for it.
![identities organization create auth method](../../images/platform/identities/identities-org-create-auth-method.png)
</Step>
@@ -44,7 +44,7 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
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.
![identities client secret create](../../images/platform/identities/identities-org-client-secret.png)
![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-1.png)
![identities client secret create](../../images/platform/identities/identities-org-client-secret-create-2.png)
@@ -55,14 +55,14 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
Next, select the identity you want to add to the project and the role you want to assign it.
![identities project](../../images/platform/identities/identities-project.png)
![identities project create](../../images/platform/identities/identities-project-create.png)
</Step>
<Step title="Get an access token for the Infisical API">
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
```
@@ -71,9 +71,9 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
--data-urlencode 'clientSecret=<client_secret>' \
--data-urlencode 'clientId=<client_id>'
```
#### Sample response
```
{
"accessToken": "...",
@@ -83,9 +83,9 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
```
Next, we can use the access token to authenticate with the [Infisical API](/api-reference/overview/introduction) to read/write secrets
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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,
@@ -96,12 +96,12 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
Finally, you can fetch the secret `FOO=BAR` back from **Step 1** by including the access token in the previous step in another request to the `/api/v3/secrets/raw/{secretName}` endpoint.
### Sample request
```
curl --location --request GET 'http://localhost:8080/api/v3/secrets/raw/FOO?workspaceId=657830d579cfc8415d06ce5b&environment=dev' \
--header 'Authorization: Bearer <access_token>'
```
### Sample response
```
@@ -118,11 +118,11 @@ In this brief, we'll explore how to fetch a secret back from a project on [Infis
}
}
```
Note that you can fetch a list of secrets back by making a request to the `/api/v3/secrets/raw` endpoint.
</Step>
</Steps>
See also:
- [API Reference](/api-reference/overview/introduction)
- [API Reference](/api-reference/overview/introduction)

2
docs/documentation/platform/identities/aws-auth.mdx
View File

@@ -311,7 +311,7 @@ access the Infisical API using the AWS Auth authentication method.
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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,

2
docs/documentation/platform/identities/azure-auth.mdx
View File

@@ -173,7 +173,7 @@ access the Infisical API using the Azure Auth authentication method.
We recommend using one of Infisical's clients like SDKs or the Infisical Agent to authenticate with Infisical using Azure Auth as they handle the authentication process including retrieving the client access token.
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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 by performing another login operation.

8
docs/documentation/platform/identities/gcp-auth.mdx
View File

@@ -168,7 +168,7 @@ access the Infisical API using the GCP ID Token authentication method.
We recommend using one of Infisical's clients like SDKs or the Infisical Agent to authenticate with Infisical using GCP IAM Auth as they handle the authentication process including generating the signed JWT token.
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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 by performing another login operation.
@@ -179,7 +179,7 @@ access the Infisical API using the GCP ID Token authentication method.
</Tab>
<Tab title="GCP IAM Auth">
## Diagram
The following sequence diagram illustrates the GCP IAM Auth workflow for authenticating GCP IAM service accounts with Infisical.
@@ -352,7 +352,7 @@ access the Infisical API using the GCP IAM authentication method.
We recommend using one of Infisical's clients like SDKs or the Infisical Agent to authenticate with Infisical using GCP IAM Auth as they handle the authentication process including generating the signed JWT token.
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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 by performing another login operation.
@@ -361,5 +361,5 @@ access the Infisical API using the GCP IAM authentication method.
</Steps>
</Tab>
</Tabs>

6
docs/documentation/platform/identities/kubernetes-auth.mdx
View File

@@ -56,7 +56,7 @@ In the following steps, we explore how to create and use identities for your app
<Step title="Obtaining the token reviewer JWT for Infisical">
<Tabs>
<Tab title="Option 1: Reviewer JWT Token">
<Note>
**When to use this option**: Choose this approach when you want centralized authentication management. Only one service account needs special permissions, and your application service accounts remain unchanged.
</Note>
@@ -190,7 +190,7 @@ In the following steps, we explore how to create and use identities for your app
Here's some more guidance on each field:
- Kubernetes Host / Base Kubernetes API URL: The host string, host:port pair, or URL to the base of the Kubernetes API server. This can usually be obtained by running `kubectl cluster-info`.
- Token Reviewer JWT: A long-lived service account JWT token for Infisical to access the [TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/) to validate other service account JWT tokens submitted by applications/pods. This is the JWT token obtained from step 1.5(Reviewer Tab). If omitted, the client's own JWT will be used instead, which requires the client to have the `system:auth-delegator` ClusterRole binding.
- Token Reviewer JWT: A long-lived service account JWT token for Infisical to access the [TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/) to validate other service account JWT tokens submitted by applications/pods. This is the JWT token obtained from step 1.5(Reviewer Tab). If omitted, the client's own JWT will be used instead, which requires the client to have the `system:auth-delegator` ClusterRole binding.
This is shown in step 1, option 2.
- Allowed Service Account Names: A comma-separated list of trusted service account names that are allowed to authenticate with Infisical.
- Allowed Namespaces: A comma-separated list of trusted namespaces that service accounts must belong to authenticate with Infisical.
@@ -257,7 +257,7 @@ In the following steps, we explore how to create and use identities for your app
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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 exceeds its max ttl, it can no longer authenticate with the Infisical API. In this case,

163
docs/documentation/platform/identities/oci-auth.mdx Normal file
View File

@@ -0,0 +1,163 @@
---
title: OCI Auth
description: "Learn how to authenticate with Infisical using OCI user accounts."
---
**OCI Auth** is an OCI-native authentication method that verifies Oracle Cloud Infrastructure users through signature validation, allowing secure access to Infisical resources.
## Diagram
The following sequence diagram illustrates the OCI Auth workflow for authenticating OCI users with Infisical.
```mermaid
sequenceDiagram
participant Client
participant Infisical
participant OCI
Note over Client,Client: Step 1: Sign user identity request
Note over Client,Infisical: Step 2: Login Operation
Client->>Infisical: Send signed request details to /api/v1/auth/oci-auth/login
Note over Infisical,OCI: Step 3: Request verification
Infisical->>OCI: Forward signed request
OCI-->>Infisical: Return user details
Note over Infisical: Step 4: Identity property validation
Infisical->>Client: Return short-lived access token
Note over Client,Infisical: Step 5: Access Infisical API with token
Client->>Infisical: Make authenticated requests using the short-lived access token
```
## Concept
At a high level, Infisical authenticates an OCI user by verifying its identity and checking that it meets specific requirements (e.g., its username is authorized) at the `/api/v1/auth/oci-auth/login` endpoint. If successful,
then Infisical returns a short-lived access token that can be used to make authenticated requests to the Infisical API.
To be more specific:
1. The client [signs](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/signingrequests.htm) a `/20160918/users/{userId}` request using an OCI user's [private key](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#Required_Keys_and_OCIDs); this is done using the [OCI SDK](https://infisical.com/docs/documentation/platform/identities/oci-auth#accessing-the-infisical-api-with-the-identity) or API.
2. The client sends the signed request's headers and their user OCID to Infisical at the `/api/v1/auth/oci-auth/login` endpoint.
3. Infisical reconstructs the request and sends it to OCI via the [Get User](https://docs.oracle.com/en/engineered-systems/private-cloud-appliance/3.0-latest/ceapi/op-20160918-users-user_id-get.html) endpoint for verification and obtains the identity associated with the OCI user.
4. Infisical checks the user's properties against set criteria such as **Allowed Usernames**.
5. If all checks pass, Infisical returns a short-lived access token that the client can use to make authenticated requests to the Infisical API.
## Guide
In the following steps, we explore how to create and use identities for your workloads and applications on OCI to
access the Infisical API using the OCI request signing authentication method.
### Creating an identity
To create an identity, head to your Organization Settings > Access Control > [Identities](https://app.infisical.com/organization/access-management?selectedTab=identities) and press **Create identity**.
![identities organization](/images/platform/identities/identities-org.png)
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](https://app.infisical.com/organization/access-management?selectedTab=roles).
![identities organization create](/images/platform/identities/identities-org-create.png)
Input some details for your new identity:
- **Name (required):** A friendly name for the identity.
- **Role (required):** A role from the [**Organization Roles**](https://app.infisical.com/organization/access-management?selectedTab=roles) tab for the identity to assume. The organization role assigned will determine what organization-level resources this identity can have access to.
Once you've created an identity, you'll be redirected to a page where you can manage the identity.
![identities page](/images/platform/identities/identities-page.png)
Since the identity has been configured with [Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth) by default, you should reconfigure it to use OCI Auth instead. To do this, click the cog next to **Universal Auth** and then select **Delete** in the options dropdown.
![identities press cog](/images/platform/identities/identities-press-cog.png)
![identities page remove default auth](/images/platform/identities/identities-page-remove-default-auth.png)
Now create a new OCI Auth Method.
![identities create oci auth method](/images/platform/identities/identities-org-create-oci-auth-method.png)
Here's some information about each field:
- **Allowed Usernames:** A comma-separated list of trusted OCI users that are allowed to authenticate with Infisical.
- **Access Token TTL (default is `2592000` equivalent to 30 days):** The lifetime for an access token in seconds. This value will be referenced at renewal time.
- **Access Token Max TTL (default is `2592000` equivalent to 30 days):** The maximum lifetime for an access token in seconds. This value will be referenced at renewal time.
- **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 an infinite number of uses.
- **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.
### Adding an identity to a project
In order to allow an identity to access project-level resources such as secrets, you must add it to the relevant projects.
To do this, head over to the project you want to add the identity to and navigate to Project Settings > Access Control > Machine Identities and press **Add Identity**.
![identities project](/images/platform/identities/identities-project.png)
Select the identity you want to add to the project and the project-level role you want it to assume. The project role given to the identity will determine what project-level resources this identity can access.
![identities project create](/images/platform/identities/identities-project-create.png)
### Accessing the Infisical API with the identity
To access the Infisical API as the identity, you need to construct a signed [Get User](https://docs.oracle.com/en/engineered-systems/private-cloud-appliance/3.0-latest/ceapi/op-20160918-users-user_id-get.html) request using [OCI Signature v1](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/signingrequests.htm#Request_Signatures) and then make a request to the `/api/v1/auth/oci-auth/login` endpoint passing the signed header data and user OCID.
Below is an example of how you can authenticate with Infisical using the `oci-sdk` for NodeJS.
```typescript
import { common } from "oci-sdk";
// Change these credentials to match your OCI user
const tenancyId = "ocid1.tenancy.oc1..example";
const userId = "ocid1.user.oc1..example";
const fingerprint = "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00";
const region = "us-ashburn-1";
const privateKey = "..."; // Must be PEM format
const provider = new common.SimpleAuthenticationDetailsProvider(
tenancyId,
userId,
fingerprint,
privateKey,
null,
common.Region.fromRegionId(region),
);
// Build request
const headers = new Headers({
host: `identity.${region}.oraclecloud.com`,
});
const request: common.HttpRequest = {
method: "GET",
uri: `/20160918/users/${userId}`,
headers,
body: null,
};
// Sign request
const signer = new common.DefaultRequestSigner(provider);
await signer.signHttpRequest(request);
// Forward signed request to Infisical
const requestAsJson = {
identityId: "2dd11664-68e3-471d-b366-907206ab1bff",
userOcid: userId,
headers: Object.fromEntries(request.headers.entries()),
};
const res = await fetch("https://tunnel.util.lol/api/v1/auth/oci-auth/login", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(requestAsJson),
});
const json = await res.json();
console.log("Infisical Response:", json);
```
<Note>
Each identity access token has a time-to-live (TTL) 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 access the Infisical API. A new access token should be obtained by performing another login operation.
</Note>

2
docs/documentation/platform/identities/oidc-auth/circleci.mdx
View File

@@ -163,7 +163,7 @@ In the following steps, we explore how to create and use identities to access th
}
```
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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,

2
docs/documentation/platform/identities/oidc-auth/general.mdx
View File

@@ -159,7 +159,7 @@ In the following steps, we explore how to create and use identities to access th
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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,

2
docs/documentation/platform/identities/oidc-auth/github.mdx
View File

@@ -159,7 +159,7 @@ In the following steps, we explore how to create and use identities to access th
</Tip>
<Note>
Each identity access token has a time-to-live (TLL) which you can infer from the response of the login operation;
Each identity access token has a time-to-live (TTL) 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,

10
docs/documentation/platform/identities/token-auth.mdx
View File

@@ -77,9 +77,9 @@ using the Token Auth authentication method.
</Step>
<Step title="Creating a Token">
In order to use the identity with Token Auth, you'll need to create an (access) token; you can think of this token akin
In order to use the identity with Token Auth, you'll need to create an (access) token; you can think of this token akin
to an API Key used to authenticate with the Infisical API. With that, press **Create Token**.
![identities client secret create](/images/platform/identities/identities-token-auth-create-1.png)
![identities client secret create](/images/platform/identities/identities-token-auth-create-2.png)
@@ -106,7 +106,7 @@ using the Token Auth authentication method.
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;
Each identity access token has a time-to-live (TTL) which you can infer from the response of the login operation;
the default TTL is `7200` seconds which can be adjusted in the Token Auth configuration.
If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
@@ -121,14 +121,14 @@ using the Token Auth authentication method.
<AccordionGroup>
<Accordion title="Why is the Infisical API rejecting my access token?">
There are a few reasons for why this might happen:
- The access token has expired. If this is the case, you should obtain a new access token or consider extending the token's TTL.
- The identity is insufficently permissioned to interact with the resources you wish to access.
- The 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.
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.

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

@@ -84,15 +84,15 @@ using the Universal Auth authentication method.
<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.
and password used to authenticate with the Infisical API.
With that, press **Create Client Secret**.
![identities client secret create](/images/platform/identities/identities-universal-auth-create-1.png)
![identities client secret create](/images/platform/identities/identities-universal-auth-create-2.png)
![identities client secret create](/images/platform/identities/identities-universal-auth-create-3.png)
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.
@@ -113,10 +113,10 @@ using the Universal Auth authentication method.
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.
<Tip>
Choose the correct base URL based on your region:
- For Infisical Cloud US users: `https://app.infisical.com`
- For Infisical Cloud EU users: `https://eu.infisical.com`
</Tip>
@@ -144,7 +144,7 @@ using the Universal Auth authentication method.
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;
Each identity access token has a time-to-live (TTL) which you can infer from the response of the login operation;
the default TTL is `7200` seconds which can be adjusted in the Universal Auth configuration.
If an identity access token expires, it can no longer authenticate with the Infisical API. In this case,
@@ -159,14 +159,14 @@ using the Universal Auth authentication method.
<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.
- 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.
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.