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 #1192 from Infisical/stv3-org-roles

Browse Source 
Add Identities + Universal Auth Authentication Method
This commit is contained in:
Maidul Islam
2023-12-10 16:57:39 -05:00
committed by GitHub
parent aabd896c37 4f6adb50d1
commit f3e8ef1537
152 changed files with 6739 additions and 3052 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
docs/documentation/platform/identity.mdx Normal file
View File

@@ -0,0 +1,168 @@
---
title: Identity
description: "Programmatically interact with Infisical"
---
A (machine) identity is an entity that you can create in Infisical.
Each identity represents a workload that wishes to access the Infisical API via an authentication method; this is similar to an IAM user in AWS or service account in GCP.
An identity can be provisioned scoped access to resources at the organization or project-level via [role-based access controls (RBAC)](/documentation/platform/role-based-access-controls). For instance, you may create a identity with scoped access to
fetch secrets back from the `/` path of the `development` environment in some project.
<Note>
The identity feature is in beta.
Currently, an identity can only be used to make authenticated requests to the Infisical API and does not work with any clients such as [Node SDK](https://github.com/Infisical/infisical-node)
, [Python SDK](https://github.com/Infisical/infisical-python), CLI, K8s operator, Terraform Provider, etc.
We will be releasing compatibility with it across clients in the coming quarter.
</Note>
Each identity can be configured an authentication method. The only supported method at the moment is **Universal Auth (UA)**
which has the following properties:
- In UA, each identity is assigned 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 (i.e. login operation) to authenticate with the Infisical API.
- UA supports restrictions on the number of times that the **Client Secret(s)** and access token(s) can be used.
- UA supports token renewal that is the ability to extend the lifetime of a token by its TTL up to its maximum TTL since its creation.
- UA supports IP allowlisting; this means you can restrict the usage of **Client Secret(s)** and access token to a specific IP or CIDR range.
- UA support expiration, so, if specified, the client secret of the identity will automatically be defunct after a period of time.
- UA tracks most recent usage of their client secrets and access tokens; it also keeps track of each token's usage count.
## Using identities
In the following steps, we explore how to create and use identities for your applications to access the Infisical API.
<Steps>
<Step title="Creating an identity">
To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**.
![machine identities organization](../../images/platform/machine-identity/machine-identity-org.png)
![machine identities organization create](../../images/platform/machine-identity/machine-identity-org-create.png)
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.
- 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 team@infisical.com 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.
![machine identities client secret create](../../images/platform/machine-identity/machine-identity-org-client-secret.png)
![machine identities client secret create](../../images/platform/machine-identity/machine-identity-org-client-secret-create-1.png)
![machine identities client secret create](../../images/platform/machine-identity/machine-identity-org-client-secret-create-2.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.
</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.
![machine identities project](../../images/platform/machine-identity/machine-identity-project.png)
![machine identities project create](../../images/platform/machine-identity/machine-identity-project-create.png)
</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 MI 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="What is the difference between an identity and service token?">
A service token is a project-level authentication method that is being phased out in favor of identities.
Amongst many differences, identities provide broader access over the Infisical API, utilizes the same role-based
permission system used by users, and comes with ample more configurable security measures.
</Accordion>
<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>
<Accordion title="Why can I not create, read, update, or delete an identity?">
There are a few reasons for why this might happen:
- You have insufficient organization permissions to create, read, update, delete identities.
- The identity you are trying to read, update, or delete is more privileged than yourself.
- The role you are trying to create an identity for or update an identity to is more privileged than yours.
</Accordion>
<Accordion title="Can you provide examples for using glob patterns?">
1. `/**`: This pattern matches all folders at any depth in the directory structure. For example, it would match folders like `/folder1/`, `/folder1/subfolder/`, and so on.
2. `/*`: This pattern matches all immediate subfolders in the current directory. It does not match any folders at a deeper level. For example, it would match folders like `/folder1/`, `/folder2/`, but not `/folder1/subfolder/`.
3. `/*/*`: This pattern matches all subfolders at a depth of two levels in the current directory. It does not match any folders at a shallower or deeper level. For example, it would match folders like `/folder1/subfolder/`, `/folder2/subfolder/`, but not `/folder1/` or `/folder1/subfolder/subsubfolder/`.
4. `/folder1/*`: This pattern matches all immediate subfolders within the `/folder1/` directory. It does not match any folders outside of `/folder1/`, nor does it match any subfolders within those immediate subfolders. For example, it would match folders like `/folder1/subfolder1/`, `/folder1/subfolder2/`, but not `/folder2/subfolder/`.
</Accordion>
</AccordionGroup>

4
docs/documentation/platform/token.mdx
View File

@@ -14,10 +14,6 @@ You can manage service tokens in Project Settings > Service Tokens.
Service Token (ST) is the current widely-used authentication method for managing secrets.
<Note>
We're soon releasing ST V3, a revised version of this Service Token, so stay tuned.
</Note>
Here's a few pointers to get you acquainted with it:
- When you create a ST, you get a token prefixed with `st`. The part after the last `.` delimiter is a symmetric key; everything

105
docs/documentation/platform/token3.mdx
View File

@@ -1,105 +0,0 @@
---
title: "Service token"
description: "Infisical service tokens allows you to programmatically interact with Infisical"
---
Service tokens are authentication credentials that services can use to access designated endpoints in the Infisical API to manage project resources like secrets.
Each service token can be provisioned scoped access to select environment(s) and path(s) within them.
## Service Tokens
Infisical currently offers Service Token V3 and Service Token; you can manage both types of tokens in Project Settings > Service Tokens.
### Service Token V3 (Beta)
Service Token V3 (ST V3) is a new and improved authentication method that is in beta.
<Note>
Currently, the Service Token V3 authentication method can only be used with the latest [Node SDK](https://github.com/Infisical/infisical-node) and [Python SDK](https://github.com/Infisical/infisical-python).
You can also make an API call with it to create, read, update, or delete secrets.
We will be releasing compatibility for it with the CLI and K8s operator in the coming month.
That said, we recommend using ST V3 whenever possible.
</Note>
Here's a few pointers to get you acquainted with it:
- When you create a ST V3, you export a `JSON` file containing 3 components: `publicKey`, `privateKey`, and `serviceToken` where
`serviceToken` is a JWT token prefixed with `stv3`. The token provides access to the Infisical API and the public-private key
pairs are to support cryptographic operations for the client whenever E2EE is needed.
- ST V3 supports IP allowlisting; this means you can restrict the usage of a ST V3 to a specific IP or CIDR range.
- ST V3 supports provisioning granular `read` or `readWrite` access down to each path.
- ST V3 supports toggling on/off active states, so you can render a ST V3 inactive without deleting it.
- ST V3 supports expiration, so, if specified, a token will automatically turn inactive after a period of time.
- ST V3 tracks most recent usage; it also keeps track of each token's usage count.
- ST V3 is editable.
### Service Token (Current)
Service Token (ST) is the current widely-used authentication method.
<Note>
We recently released ST V3, a revised version of this Service Token, which you can read about above.
Whenever possible, you should use ST V3 because we will be deprecating ST sometime Q4 2023.
</Note>
Here's a few pointers to get you acquainted with it:
- When you create a ST, you get a token prefixed with `st`. The part after the last `.` delimiter is a symmetric key; everything
before it is an access token. When authenticating with the Infisical API, it is important to send in only the access token portion
of the token.
- ST supports expiration; it gets deleted automatically upon expiration.
- ST supports provisioning `read` and/or `write` permissions broadly applied to all accessible environment(s) and path(s).
- ST is not editable.
## Creating a service token
To create a service token, head to Project Settings > Service Tokens as shown below and press **Create token**.
![token add](../../images/project-token-add.png)
Now input any token configuration details such as which environment(s) and path(s) you'd like to provision
the token access to. Here's some guidance for each field:
- Name: A friendly name for the token.
- Scopes: The environment(s) and path(s) the token should have access to.
If using ST V3, you can also indicate whether or not the token should have `read` or `readWrite` access to each path.
Also, note that Infisical supports [glob patterns](https://www.malikbrowne.com/blog/a-beginners-guide-glob-patterns/) when defining access scopes to path(s).
- Trusted IPs: The IPs or CIDR ranges that the token can be used from. By default, each token is given the `0.0.0.0/0` entry representing all possible IPv4 addresses.
- Expiration: The time when this token should be rendered inactive.
<Warning>
Restricting 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 team@infisical.com to purchase an enterprise license to use it.
</Warning>
![token add](../../images/project-token-permissions.png)
In the above screenshot, you can see that we are creating a token token with `read` access to all subfolders at any depth
of the `/common` path within the development environment of the project; the token expires in 6 months and can be used from any IP address.
**FAQ**
<AccordionGroup>
<Accordion title="Why is the Infisical API rejecting my service token?">
There are a few reasons for why this might happen:
- The service token has expired.
- The service token is insufficently permissioned to interact with the secrets in the given environment and path.
- You are attempting to access a `/raw` secrets endpoint that requires your project to disable E2EE.
- (If using ST V3) The service token has not been activated yet.
- (If using ST V3) The service token is being used from an untrusted IP.
</Accordion>
<Accordion title="Can you provide examples for using glob patterns?">
1. `/**`: This pattern matches all folders at any depth in the directory structure. For example, it would match folders like `/folder1/`, `/folder1/subfolder/`, and so on.
2. `/*`: This pattern matches all immediate subfolders in the current directory. It does not match any folders at a deeper level. For example, it would match folders like `/folder1/`, `/folder2/`, but not `/folder1/subfolder/`.
3. `/*/*`: This pattern matches all subfolders at a depth of two levels in the current directory. It does not match any folders at a shallower or deeper level. For example, it would match folders like `/folder1/subfolder/`, `/folder2/subfolder/`, but not `/folder1/` or `/folder1/subfolder/subsubfolder/`.
4. `/folder1/*`: This pattern matches all immediate subfolders within the `/folder1/` directory. It does not match any folders outside of `/folder1/`, nor does it match any subfolders within those immediate subfolders. For example, it would match folders like `/folder1/subfolder1/`, `/folder1/subfolder2/`, but not `/folder2/subfolder/`.
</Accordion>
</AccordionGroup>