Using the InfisicalAuth CRD

Learn how to configure the InfisicalAuth CRD to define how the operator authenticates with Infisical.

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)

1. Create a machine identity

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

   

   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.

   

   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.

   
2. 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.

   
3. 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
   
4. 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
   
5. 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.

6. 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
   
7. 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 [e-mail] to purchase an enterprise license.

1. Deploying a gateway

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

2. 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.

   
3. 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>"
   
4. 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.

5. 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.

1. 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.

2. 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>"
   
3. 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.