mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Add docs for MIs
This commit is contained in:
Tuan Dang
130
docs/documentation/platform/machine-identity.mdx
Normal file
130
docs/documentation/platform/machine-identity.mdx
Normal file
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: "Machine Identity"
|
||||
description: "Programmatically interact with Infisical"
|
||||
---
|
||||
|
||||
A machine identity (MI) is an entity that you can create in Infisical. The MI represents a workload that wishes to access the Infisical API and comes with its own authentication credential.
|
||||
|
||||
Similar to a user, a MI can be provisioned scoped access to resources at the organization or project-level. For instance, you may create a MI with scoped access to
|
||||
fetch secrets back from the `/` path of the `development` environment in some project.
|
||||
|
||||
<Note>
|
||||
The MI feature is in beta.
|
||||
|
||||
Currently, a MI 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>
|
||||
|
||||
Here's a few pointers to get you acquainted with MIs:
|
||||
|
||||
- When you create a MI, you get issued a refresh token that can be exchanged for an access token to authenticate with the Infisical API.
|
||||
- MIs support IP allowlisting; this means you can restrict the usage of a MI access token to a specific IP or CIDR range.
|
||||
- MIs rely on the role-based permission system to provision access to resources like secrets.
|
||||
- MIs support expiration, so, if specified, the refresh token of the MI will automatically be defunct after a period of time.
|
||||
- MIs tracks most recent usage of their refresh and access tokens; they also keeps track of each token's usage count.
|
||||
- MIs are editable.
|
||||
|
||||
## Using machine identities
|
||||
|
||||
In the following steps, we explore how to create and use MIs for your applications to access the Infisical API.
|
||||
|
||||
<Steps>
|
||||
<Step title="Creating a MI">
|
||||
To create a machine identity, head to your Organization Settings > Access Control > Machine Identities and press **Create MI**.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Now input a few details for your new MI; note that only the fields in the **General** tab are required. Here's some guidance for each field:
|
||||
|
||||
- Name (required): A friendly name for the MI
|
||||
- Role (required): A role from the **Organization Roles** tab to permit the MI to access certain resources.
|
||||
- Refresh Token Expires In: The number of days from now to deactivate the MI refresh token
|
||||
- Trusted IPs: The IPs or CIDR ranges that the refresh and access tokens can be used from. By default, each token is given the `0.0.0.0/0` entry representing all possible IPv4 addresses.
|
||||
- Access Token TTL: The time-to-live for each acccess token in seconds.
|
||||
- Refresh Token Rotation: Whether or not to return a new refresh token when exchanging an existing refresh token; if enabled, the existing refresh token is invalidated upon the refresh operation.
|
||||
|
||||
<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>
|
||||
|
||||
Once you've created the MI, you'll be issued a refresh token for it; copy the token and keep it handy.
|
||||
</Step>
|
||||
<Step title="Adding a MI to a project">
|
||||
If you intend the MI 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 MI to and go to Project Settings > Access Control > Machine Identities and press **Add MI**.
|
||||
|
||||
Next, select the MI you want to add to the project and the role you want to assign it.
|
||||
|
||||
|
||||
|
||||
|
||||
</Step>
|
||||
<Step title="Accessing the Infisical API with the MI">
|
||||
To access the Infisical API as the MI, you should first exchange the MI refresh token from **Step 1** for an access token
|
||||
by making a request to the `/api/v3/machines/me/token` endpoint.
|
||||
|
||||
#### Sample request
|
||||
|
||||
```
|
||||
curl --location --request POST 'http://localhost:8080/api/v3/machines/me/token' \
|
||||
--header 'Content-Type: application/x-www-form-urlencoded' \
|
||||
--data-urlencode 'refreshToken=<token>'
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```
|
||||
{
|
||||
"refreshToken": "...",
|
||||
"accessToken": "...",
|
||||
"expiresIn": 7200,
|
||||
"tokenType": "Bearer"
|
||||
}
|
||||
```
|
||||
|
||||
Next, you can use the access token to authenticate with the [Infisical API](/api-reference/overview/introduction)
|
||||
|
||||
<Note>
|
||||
Each MI access token has a time-to-live (TLL) which you can infer from the response of the refresh token exchange;
|
||||
the default TTL is `7200` seconds which can be adjusted in the **Advanced** settings of the MI.
|
||||
|
||||
If a MI access token expires, it can no longer authenticate with the Infisical API. In this case,
|
||||
a new access token should be obtained from the refresh token exchange.
|
||||
</Note>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
**FAQ**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="What is the difference between a machine identity and service token?">
|
||||
A service token is a project-level authentication method that is being phased out in favor of MIs.
|
||||
|
||||
Amongst many differences, MIs provide broader access over the Infisical API with the same role-based
|
||||
permission system used by users.
|
||||
</Accordion>
|
||||
<Accordion title="Why is the Infisical API rejecting my machine identity credentials?">
|
||||
There are a few reasons for why this might happen:
|
||||
|
||||
- The refresh/access token has expired.
|
||||
- The MI 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 refresh/access 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>
|
||||
@@ -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
|
||||
|
||||
@@ -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**.
|
||||
|
||||
|
||||
|
||||
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>
|
||||
|
||||
|
||||
|
||||
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>
|
||||
Reference in New Issue
Block a user