mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-09 23:48:05 -05:00
57 lines
3.0 KiB
Plaintext
57 lines
3.0 KiB
Plaintext
---
|
||
title: "Machine identities"
|
||
description: "Understanding machine identities and their best practices"
|
||
---
|
||
|
||
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 MIs, the new and improved authentication method.
|
||
|
||
## Anatomy
|
||
|
||
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 MI contains the following notable data:
|
||
|
||
- 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.
|
||
|
||
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
|
||
creating and assigning roles to MIs.
|
||
|
||
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 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 MI to restrict its usage to specific IP addresses or CIDR-notated range of addresses.
|
||
|
||
### Storage
|
||
|
||
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 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. |