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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.3 MiB |
BIN
docs/images/platform/machine-identity/machine-identity-org.png
Normal file
BIN
docs/images/platform/machine-identity/machine-identity-org.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.3 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
@@ -1,72 +1,57 @@
|
||||
---
|
||||
title: "Service tokens"
|
||||
description: "Understanding service tokens and their best practices"
|
||||
title: "Machine identities"
|
||||
description: "Understanding machine identities and their best practices"
|
||||
---
|
||||
|
||||
Many clients use service tokens to authenticate and read/write secrets from/to Infisical; they can be created in your project settings.
|
||||
Many clients use machine identities (MIs) to authenticate and read/write secrets from/to Infisical; they can be created in your organization settings.
|
||||
|
||||
On this page, we discuss Service Token V3, the new and improved authentication method.
|
||||
On this page, we discuss MIs, the new and improved authentication method.
|
||||
|
||||
## Anatomy
|
||||
|
||||
A service token in Infisical exports a `JSON` file containing 3 components: `publicKey`, `privateKey`, and `serviceToken` where
|
||||
`serviceToken` is a JWT token prefixed with `proj_token`. 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.
|
||||
A MI in Infisical comes with a JWT-based refresh token authentication credential. The refresh token can be exchanged for an access token
|
||||
with a time-to-live (TTL) to access the Infisical API.
|
||||
|
||||
### Database model
|
||||
|
||||
The storage backend model for a token contains the following information:
|
||||
The storage backend model for a MI contains the following notable data:
|
||||
|
||||
- ID: The token identifier.
|
||||
- Expiration: The date at which point the token is invalid.
|
||||
- Project: The project that the token is part of.
|
||||
- Status: The active/inactive state of a token.
|
||||
- Scopes: The project environment(s) and path(s) that the token has access to as well as `read` or `readWrite` permissions for them.
|
||||
- ID: The internal ID of the MI.
|
||||
- Name: The name of the MI.
|
||||
- Organization: The organization that the MI belongs to.
|
||||
- Refresh/Access Token last used: The last used dates of the MI refresh and access tokens.
|
||||
- Refresh/Access Token usage count: The number of times the MI refresh and access tokens have been used.
|
||||
- Refresh Token Rotation Enabled: Whether or not a new MI refresh token should be returned when exchanging an existing refresh token for an access token; if enabled, the old refresh token is invalidated at each refresh operation.
|
||||
- Token Version: The token version used to keep track of old/current refresh and access tokens.
|
||||
- Expiration: The date at which point the MI refresh token credential can no longer be used.
|
||||
- Access Token TTL: the time-to-live of each access token issued at each refresh token exchange.
|
||||
- Trusted IPs: The specific (IPv4 or IPv6) IPs or CIDR ranges that the token can be used from.
|
||||
- Last used: The date at which point the token was last used.
|
||||
- Usage count: The number of times that the token has been used.
|
||||
|
||||
### Token
|
||||
|
||||
As mentioned before, a service token consists of three components, exported as a `JSON`, used for authentication and cryptographic purposes.
|
||||
|
||||
Consider the following `JSON`:
|
||||
|
||||
```
|
||||
{
|
||||
"publicKey": "...",
|
||||
"privateKey": "...",
|
||||
"serviceToken": "stv3..."
|
||||
}
|
||||
```
|
||||
|
||||
Here, the `serviceToken` component can be used to authenticate with the API, by including it in the `Authorization` header under `Bearer <serviceToken>` and retrieve (encrypted) secrets as well as a project key back. Meanwhile, the `privateKey` (in the `JSON`), and `publicKey` (returned in the encrypted project key response) can be used to decrypt the project key used to decrypt the secrets.
|
||||
|
||||
Note that when using service tokens via select client methods like SDK or CLI, cryptographic operations are abstracted for you that is the token is parsed and encryption/decryption operations are handled. If using service tokens with the REST API and end-to-end encryption enabled, then you will have to handle the encryption/decryption operations yourself.
|
||||
Separately, another model stores the mapping of a MI and the organization or project-role it is bound to.
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Permissions
|
||||
|
||||
You should consider the [principle of least privilege(PoLP)](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when setting which environment(s) and path(s)
|
||||
should be accessible by a service token; you should also consider whether or not it needs `read` or `readWrite` access.
|
||||
You should consider the [principle of least privilege(PoLP)](https://en.wikipedia.org/wiki/Principle_of_least_privilege) when
|
||||
creating and assigning roles to MIs.
|
||||
|
||||
For example, if the client using the token only requires `read` access to the secrets in the `/config` path of the staging environment, then you should scope the token to the `/config` path of that environment only with `read` permission.
|
||||
For example, if an MI only requires `read` access to the secrets in the `/config` path of the staging environment, then you should scope the role of the MI to the `/config` path of that environment only with `read` permission.
|
||||
|
||||
### Status & Expiration
|
||||
|
||||
We recommend considering whether or not a service token should be able to access secrets indefinitely or within a finite lifetime such as until 6 months or 1 year from now
|
||||
We recommend considering whether or not a MI should be able to access secrets indefinitely or within a finite lifetime such as until 6 months or 1 year from now
|
||||
|
||||
### Network access
|
||||
|
||||
We recommend configuring the IP allowlist configuration of each service token to restrict its usage to specific IP addresses or CIDR-notated range of addresses.
|
||||
We recommend configuring the IP allowlist configuration of each MI to restrict its usage to specific IP addresses or CIDR-notated range of addresses.
|
||||
|
||||
### Storage
|
||||
|
||||
Since service tokens grant access to your secrets, we recommend storing them securely across your development cycle whether it be in a .env file in local development or as an environment variable of your deployment platform.
|
||||
Since MIs grant access to your secrets, we recommend storing the refresh token credential securely across your development cycle whether it be in a .env file in local development or as an environment variable of your deployment platform.
|
||||
|
||||
### Rotation
|
||||
|
||||
We recommend periodically rotating the service token, even in the absence of compromise. Since service tokens are capable of decrypting project keys used to decrypt secrets, they should be rotated before approximately 2^32 encryptions have been performed; this follows the guidance set forth by [NIST publication 800-38D](https://csrc.nist.gov/pubs/sp/800/38/d/final).
|
||||
|
||||
Note that Infisical keeps track of the number of times that service tokens are used and will alert you when you have reached 90% of the recommended capacity.
|
||||
We recommend periodically rotating the MI refresh token, even in the absence of compromise. If using the Infisical Agent, we recommend enabling the **Refresh Token Rotation** option
|
||||
on your MI; this will issue a new refresh token and invalidate the old one upon a refresh token exchange operation — In doing so, the refresh token is kept as a moving target
|
||||
and secret zero risk is mitigated.
|
||||
@@ -118,6 +118,7 @@
|
||||
"documentation/platform/pit-recovery",
|
||||
"documentation/platform/audit-logs",
|
||||
"documentation/platform/token",
|
||||
"documentation/platform/machine-identity",
|
||||
"documentation/platform/mfa",
|
||||
{
|
||||
"group": "Secret Rotation",
|
||||
|
||||
@@ -76,7 +76,7 @@ export const MachineIdentitySection = withProjectPermission(
|
||||
onClick={() => handlePopUpOpen("machineIdentity")}
|
||||
isDisabled={!isAllowed}
|
||||
>
|
||||
Add machine identity
|
||||
Add MI
|
||||
</Button>
|
||||
)}
|
||||
</ProjectPermissionCan>
|
||||
|
||||
Reference in New Issue
Block a user