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

Add docs for MIs

Browse Source
This commit is contained in:
Tuan Dang
2023-11-29 15:55:15 +07:00
parent 77e3d10a64
commit 6557d7668e
10 changed files with 158 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/internals/service-tokens-new.mdx
View File

@@ -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.