Machine identities

​ 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) 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.