Using the InfisicalAuth CRD

Overview

The InfisicalAuth CRD defines how the Infisical Operator authenticates with your Infisical instance. It encapsulates the machine identity authentication method and credentials. Once created, it can be referenced by multiple secret resources, so you only need to define authentication details once per identity. The operator caches authenticated credentials using the token’s TTL (at 70% of the expiration time) so that multiple resources sharing the same InfisicalAuth don’t trigger redundant login calls. The cache is automatically invalidated when the InfisicalAuth spec changes or when the referenced InfisicalConnection is updated.

Prerequisites

The operator is installed on your Kubernetes cluster.
A machine identity configured in Infisical with access to the relevant project(s).
An InfisicalConnection resource created in your cluster.

Example

You can only define one authentication method per InfisicalAuth resource.

Kubernetes Auth (Recommended)

Authenticates using a Kubernetes service account token. This is the recommended method when running inside a Kubernetes cluster. The operator automatically creates short-lived service account tokens (10 minutes) for authentication.Read more about Kubernetes Auth.

Short-lived service account tokens (Recommended)

Create a machine identity

To create an identity, head to your Organization Settings > Access Control > Identities and press Create identity. identities organization

When creating an identity, you specify an organization level role for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles. identities organization create

Now input a few details for your new identity. Here’s some guidance for each field:

Name (required): A friendly name for the identity.
Role (required): A role from the Organization Roles tab for the identity to assume. The organization role assigned will determine what organization level resources this identity can have access to.

Once you’ve created an identity, you’ll be prompted to configure the authentication method for it. Here, select Kubernetes Auth.

To learn more about each field of the Kubernetes native authentication method, see step 2 of guide.

identities organization create auth method

Add the identity to a project

To allow the operator to use the given identity to access secrets, you will need to add the identity to project(s) that you would like to grant it access to.To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press Add identity.Next, select the identity you want to add to the project and the project level role you want to allow it to assume. The project role assigned will determine what project level resources this identity can have access to. identities project

Create a service account

Create a reviewer service account in your Kubernetes cluster. Infisical uses this account to authenticate with the Kubernetes API Server through the TokenReview API.

infisical-service-account.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: infisical-service-account
  namespace: default

kubectl apply -f infisical-service-account.yaml

Bind the reviewer service account

Bind the service account to the system:auth-delegator cluster role. This allows Infisical to perform delegated authentication checks against the TokenReview API.

infisical-cluster-role-binding.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: infisical-service-account-role-binding
  namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
  - kind: ServiceAccount
    name: infisical-service-account
    namespace: default

kubectl apply -f infisical-cluster-role-binding.yaml

Create a generic Kubernetes secret containing the machine identity ID

Create a generic Kubernetes secret containing the machine identity ID. Following this example, we’ll create a secret named kubernetes-credentials in the default namespace, and add the machine identity ID as the value of the identityId key.

kubectl create secret generic kubernetes-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

You can find the machine identity ID in the Infisical UI by going to Access Control > Machine Identities, and clicking on the identity you want to view the details of.

Create the InfisicalAuth resource with your service account details

After you bind the service account to the system:auth-delegator cluster role, you are ready to create the InfisicalAuth resource using the kubernetes auth method.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: kubernetes
  kubernetes:
    identityIdRef:
      name: kubernetes-credentials
      namespace: default
      key: identityId
    serviceAccountRef:
      name: infisical-service-account
      namespace: default

Apply the resource

kubectl apply -f infisical-auth.yaml

Use Gateway as Reviewer

When to use this option: Choose this approach when you have a gateway deployed in your Kubernetes Cluster and wish to eliminate long-lived tokens. This approach simplifies Infisical Kubernetes Auth configuration, and only one service account will need to have the elevated system:auth-delegator ClusterRole binding.

Note: Gateway is a paid feature. - Infisical Cloud users: Gateway is available under the Enterprise Tier. - Self-Hosted Infisical: Please contact sales@infisical.com to purchase an enterprise license.

Deploying a gateway

To deploy a gateway in your Kubernetes cluster, follow our Gateway deployment guide using Helm.

Configure the Kubernetes Auth authentication method for the identity

To configure your Kubernetes Auth method to use the gateway as the token reviewer, set the Review Method to “Gateway as Reviewer”, and select the gateway you want to use as the token reviewer.You can select either an individual gateway or a Gateway Pool for automatic failover. When a pool is selected, the platform routes through a healthy gateway at request time. See Gateway Pools for more details. identities organization create kubernetes auth method

identities organization create kubernetes auth method

Create a generic Kubernetes secret containing the machine identity ID

kubectl create secret generic kubernetes-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

Create the InfisicalAuth resource

After you have set up the Kubernetes Auth prerequisites above, add the identity ID and service account details to your InfisicalAuth resource.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: kubernetes
  kubernetes:
    identityIdRef:
      name: kubernetes-credentials
      namespace: default
      key: identityId
    serviceAccountRef:
      name: infisical-service-account # Change to whichever service account you want the operator to use for authentication.
      namespace: default

Because you are using the gateway as the token reviewer, you are able to use a different service account for authentication. The gateway sits inside your Kubernetes cluster and has permissions to perform token reviews against the Kubernetes API Server. This means you can use any valid service account in the InfisicalAuth resource, as long as it lives inside the same Kubernetes cluster as the gateway configured inside Infisical.

Apply the resource

kubectl apply -f infisical-auth.yaml

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.
`serviceAccountRef.name`	Yes	Name of the Kubernetes service account.
`serviceAccountRef.namespace`	Yes	Namespace of the service account.
`serviceAccountTokenAudiences`	No	Custom audiences for the generated service account token.

Universal Auth

Authenticates using a client ID and client secret. Works anywhere, not tied to any cloud provider.Read more about Universal Auth.

Field	Required	Description
`clientIdRef`	Yes	Reference to the secret containing the universal auth client ID.
`clientSecretRef`	Yes	Reference to the secret containing the universal auth client secret.

Create a machine identity

You need to create a machine identity, and give it access to the project(s) you want to interact with. You can read more about machine identities here.

Create Kubernetes secret containing machine identity credentials

Once you have created your machine identity and added it to your project(s), you will need to create a Kubernetes secret containing the identity credentials. To quickly create a Kubernetes secret containing the identity credentials, you can run the command below.Make sure you replace <your-identity-client-id> with the identity client ID and <your-identity-client-secret> with the identity client secret.

  kubectl create secret generic universal-auth-credentials \
   --from-literal=clientId="<your-identity-client-id>" \
   --from-literal=clientSecret="<your-identity-client-secret>"

Add reference for the Kubernetes secret containing the identity credentials

Once the secret is created, add the secretName and secretNamespace of the secret that was just created under universal.clientIdRef and universal.clientSecretRef fields in the InfisicalAuth resource. See the full example below for reference.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: universal
  universal:
    clientIdRef:
      name: universal-auth-credentials
      namespace: default
      key: clientId
    clientSecretRef:
      name: universal-auth-credentials
      namespace: default
      key: clientSecret

Apply the resource:

kubectl apply -f infisical-auth.yaml

AWS IAM Auth

Authenticates using AWS IAM. Can only be used within AWS environments such as EC2, Lambda, and EKS.Read more about AWS IAM Auth.

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: aws-iam
  awsIam:
    identityIdRef:
      name: aws-iam-credentials
      namespace: default
      key: identityId

The referenced Kubernetes secret must contain the machine identity ID:

kubectl create secret generic aws-iam-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

Apply the resource:

kubectl apply -f infisical-auth.yaml

Azure Auth

Authenticates using Azure managed identity. Can only be used within Azure environments.Read more about Azure Auth.

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.
`resource`	No	The Azure resource (audience) to request a token for.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: azure
  azure:
    identityIdRef:
      name: azure-credentials
      namespace: default
      key: identityId

The referenced Kubernetes secret must contain the machine identity ID:

kubectl create secret generic azure-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

Apply the resource:

kubectl apply -f infisical-auth.yaml

GCP ID Token Auth

Authenticates using GCP ID tokens. Can only be used within GCP environments.Read more about GCP ID Token Auth.

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: gcp-id-token
  gcpIdToken:
    identityIdRef:
      name: gcp-id-token-credentials
      namespace: default
      key: identityId

The referenced Kubernetes secret must contain the machine identity ID:

kubectl create secret generic gcp-id-token-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

Apply the resource:

kubectl apply -f infisical-auth.yaml

GCP IAM Auth

Authenticates using GCP IAM with a service account key file. Works both within and outside GCP environments.Read more about GCP IAM Auth.

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.
`serviceAccountKeyFilePath`	Yes	Path to the GCP service account key file mounted in the operator pod.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: gcp-iam
  gcpIam:
    identityIdRef:
      name: gcp-iam-credentials
      namespace: default
      key: identityId
    serviceAccountKeyFilePath: /path/to/service-account-key.json

The referenced Kubernetes secret must contain the machine identity ID:

kubectl create secret generic gcp-iam-credentials \
  --from-literal=identityId="<your-machine-identity-id>"

Apply the resource:

kubectl apply -f infisical-auth.yaml

LDAP Auth

Authenticates using LDAP credentials.Read more about LDAP Auth.

Field	Required	Description
`identityIdRef`	Yes	Reference to the secret containing the machine identity ID.
`usernameRef`	Yes	Reference to the secret containing the LDAP username.
`passwordRef`	Yes	Reference to the secret containing the LDAP password.

infisical-auth.yaml

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalAuth
metadata:
  name: my-infisical-auth
spec:
  infisicalConnectionRef:
    name: my-infisical-connection
    namespace: default
  method: ldap
  ldap:
    identityIdRef:
      name: ldap-credentials
      namespace: default
      key: identityId
    usernameRef:
      name: ldap-credentials
      namespace: default
      key: username
    passwordRef:
      name: ldap-credentials
      namespace: default
      key: password

The referenced Kubernetes secret must contain identityId, username, and password keys:

kubectl create secret generic ldap-credentials \
  --from-literal=identityId="<your-machine-identity-id>" \
  --from-literal=username="<your-ldap-username>" \
  --from-literal=password="<your-ldap-password>"

Apply the resource:

kubectl apply -f infisical-auth.yaml

Troubleshooting

You can check the status of your InfisicalAuth resource by inspecting its conditions:

kubectl get infisicalauth my-infisical-auth -o jsonpath='{.status.conditions}' | jq

When authentication is healthy, the secrets.infisical.com/IsReady condition will have Status: "True" and Reason: "OK". If authentication is unhealthy, Reason will be set to Error and Message will contain details about what went wrong. The ObservedGeneration field indicates which generation of the resource spec the operator has last processed. If ObservedGeneration is less than metadata.generation, the operator has not yet reconciled the latest changes to the resource.

Documentation Index

​Overview

​Prerequisites

​Example

​Troubleshooting

Overview

Prerequisites

Example

Troubleshooting