Machine Identities

Concept

An Infisical machine identity is an entity that represents a workload or application that require access to various resources in Infisical. This is conceptually similar to an IAM user in AWS or service account in Google Cloud Platform (GCP).

Each identity must authenticate with the Infisical API using a supported authentication method like Token Auth, Universal Auth, Kubernetes Auth, AWS Auth, Azure Auth, or GCP Auth to get back a short-lived access token to be used in subsequent requests.

Key Features:

• Role Assignment: Identities must be assigned roles. These roles determine the scope of access to resources, either at the organization level or project level.
• Auth/Token Configuration: Identities must be configured with corresponding authentication methods and access token properties to securely interact with the Infisical API.

Scopes

Identities can be created either at the organization-level or the project-level. Outside of identity management and scope of operation, organization and project identities are functionally identical.

• Project identities are managed at the project-level and can only operate within their respective project. Project-level identities are useful for organizations that delegate responsibility to autonomous teams via projects.

• Organization identities are managed at the organization-level and can be assigned to one or more projects, as well as perform organization-level operations. Organization-level identities are useful for organizations that have cross-project operations.

Workflow

    1. Creating the identity with a name and [role](/documentation/platform/access-controls/role-based-access-controls) in Project > Access Control > Machine Identities.
    This step also involves configuring an authentication method for it.
    2. Authenticating the identity with the Infisical API based on the configured authentication method on it and receiving a short-lived access token back.
    3. Authenticating subsequent requests with the Infisical API using the short-lived access token.
</Tab>
<Tab title="Organization Identities">
    A typical workflow for using organization identities consists of four steps:

    1. Creating the identity with a name and [role](/documentation/platform/access-controls/role-based-access-controls) in Organization > Access Control > Machine Identities.
    This step also involves configuring an authentication method for it.
    2. Adding the identity to the project(s) you want it to have access to.
    3. Authenticating the identity with the Infisical API based on the configured authentication method on it and receiving a short-lived access token back.
    4. Authenticating subsequent requests with the Infisical API using the short-lived access token.
</Tab>

Authentication Methods

To interact with various resources in Infisical, Machine Identities can authenticate with the Infisical API using:

• Token Auth: A platform-agnostic, simple authentication method suitable to authenticate with Infisical using a token.
• Universal Auth: A platform-agnostic authentication method suitable to authenticate with Infisical using a Client ID and Client Secret.
• Kubernetes Auth: A Kubernetes-native authentication method for applications (e.g. pods).
• AWS Auth: An AWS-native authentication method for AWS services (e.g. EC2, Lambda functions, etc.).
• Azure Auth: An Azure-native authentication method for Azure resources (e.g. Azure VMs, Azure App Services, Azure Functions, Azure Kubernetes Service, etc.).
• GCP Auth: A GCP-native authentication method for GCP resources (e.g. Compute Engine, App Engine, Cloud Run, Google Kubernetes Engine, IAM service accounts, etc.).
• OIDC Auth: A platform-agnostic, JWT-based authentication method for workloads using an OpenID Connect identity provider.
• SPIFFE Auth: A SPIFFE-native authentication method for workloads using JWT-SVIDs issued by SPIRE.

Identity Lockout

Lockout is a feature that prevents brute-force attacks on identity login endpoints. Auth methods that support lockout include: Universal Auth, LDAP Auth.

Supported auth methods have lockout enabled by default. If triggered, lockout temporarily disables the login endpoint for 5 minutes after 3 consecutive failed login attempts within a 30-second window. Lockout can be configured and disabled in the identity auth method settings.

FAQ

Yes - Identities can be used with the CLI.

You can learn more about how to do this in the CLI quickstart here.

Amongst many differences, identities provide broader access over the Infisical API, utilizes the same permission system as user identities, and come with a significantly larger number of configurable authentication and security features.

If you're looking for a simple authentication method, similar to service tokens, that can be bound onto an identity, we recommend checking out Token Auth. </Accordion> <Accordion title="Why can I not create, read, update, or delete an identity?"> There are a few reasons for why this might happen:

• You have insufficient organization permissions to create, read, update, delete identities.
• The identity you are trying to read, update, or delete is more privileged than yourself.
• The role you are trying to create an identity for or update an identity to is more privileged than yours. </Accordion>