Machine identities
Understanding machine identities and their best practices
Many clients use machine identities (MIs) to authenticate and read/write secrets from/to Hanzo KMS; they can be created in your organization settings.
On this page, we discuss MIs, the new and improved authentication method.
Anatomy
A MI in Hanzo KMS 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 Hanzo KMS 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 KMS 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.
How is this guide?
Last updated on