> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://infisical.com/docs/documentation/platform/identities/machine-identities.md) configured in Infisical with access to the relevant project(s).
* An [InfisicalConnection](https://infisical.com/docs/integrations/platforms/kubernetes/infisical-connection-crd.md) resource created in your cluster.

## Example

You can only define one authentication method per InfisicalAuth resource.

> [accordion] 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](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth.md).
>
> > [accordion] Short-lived service account tokens (Recommended)
> >
> > **1. Create a machine identity**
> >
> > To create an identity, go to **Access Control** > **Machine Identities** in your organization and select **Create**.
> >
> > ![identities organization](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org.png)
> >
> > When creating an identity, you specify an organization level [role](https://infisical.com/docs/documentation/platform/access-controls/role-based-access-controls.md) for it to assume; you can configure roles in **Access Control** > **Roles**.
> >
> > ![identities organization create](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org-create.png)
> >
> > 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**.
> >
> > > [!NOTE]
> > >
> > > To learn more about each field of the Kubernetes native authentication method, see step 2 of [guide](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth.md#guide).
> >
> > ![identities organization create auth method](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org-create-kubernetes-auth-method.png)
> >
> > **2. Add the identity to a project**
> >
> > To allow the operator to use the given identity to access secrets, you'll need to add the identity to project(s) that you would like to grant it access to.
> >
> > To do this, open the project you want to add the identity to, go to **Access Control** > **Machine Identities**, and select **Add Machine Identity to Project**.
> >
> > Next, select **Assign Existing**, choose the identity you want to add, and set the project role it should assume. The project role assigned will determine what project level resources this identity can have access to.
> >
> > ![identities project](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-project.png)
> >
> > ![identities project create](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-project-create.png)
> >
> > **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.
> >
> > ```yaml infisical-service-account.yaml theme={"dark"}
> > apiVersion: v1
> > kind: ServiceAccount
> > metadata:
> >   name: infisical-service-account
> >   namespace: default
> > ```
> >
> > ```bash theme={"dark"}
> > 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.
> >
> > ```yaml infisical-cluster-role-binding.yaml theme={"dark"}
> > 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
> > ```
> >
> > ```bash theme={"dark"}
> > 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.
> >
> > ```bash theme={"dark"}
> > kubectl create secret generic kubernetes-credentials \
> >   --from-literal=identityId="<your-machine-identity-id>"
> > ```
> >
> > > [!TIP]
> > >
> > > 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.
> >
> > ```yaml infisical-auth.yaml theme={"dark"}
> > 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**
> >
> > ```bash theme={"dark"}
> > kubectl apply -f infisical-auth.yaml
> > ```
>
> > [accordion] Use Gateway as Reviewer
> >
> > > [!NOTE]
> > >
> > > **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]
> > >
> > > **Note:** Gateway is a paid feature. - **Infisical Cloud users:** Gateway is
> > > available under the **Enterprise Tier**. - **Self-Hosted Infisical:** Please
> > > contact [sales@infisical.com](mailto:sales@infisical.com) to purchase an
> > > enterprise license.
> >
> > **1. Deploying a gateway**
> >
> > To deploy a gateway in your Kubernetes cluster, follow our [Gateway deployment guide using Helm](https://infisical.com/docs/documentation/platform/gateways/gateway-deployment.md).
> >
> > **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](https://infisical.com/docs/documentation/platform/gateways/gateway-pools.md) for more details.
> >
> > ![identities organization create kubernetes auth method](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-kubernetes-auth-gateway-as-reviewer.png)
> >
> > **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.
> >
> > ```bash theme={"dark"}
> > 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.
> >
> > ```yaml infisical-auth.yaml theme={"dark"}
> > 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
> > ```
> >
> > > [!TIP]
> > >
> > > 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**
> >
> > ```bash theme={"dark"}
> > 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. |

> [accordion] Universal Auth
>
> Authenticates using a client ID and client secret. Works anywhere, not tied to any cloud provider.
>
> [Read more about Universal Auth](https://infisical.com/docs/documentation/platform/identities/universal-auth.md).
>
> | 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](https://infisical.com/docs/documentation/platform/identities/universal-auth.md).
>
> **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.
>
> ```bash theme={"dark"}
>   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.
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

> [accordion] 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](https://infisical.com/docs/documentation/platform/identities/aws-auth.md).
>
> | Field | Required | Description |
> | - | - | - |
> | `identityIdRef` | Yes | Reference to the secret containing the machine identity ID. |
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl create secret generic aws-iam-credentials \
>   --from-literal=identityId="<your-machine-identity-id>"
> ```
>
> Apply the resource:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

> [accordion] Azure Auth
>
> Authenticates using Azure managed identity. Can only be used within Azure environments.
>
> [Read more about Azure Auth](https://infisical.com/docs/documentation/platform/identities/azure-auth.md).
>
> | 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. |
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl create secret generic azure-credentials \
>   --from-literal=identityId="<your-machine-identity-id>"
> ```
>
> Apply the resource:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

> [accordion] GCP ID Token Auth
>
> Authenticates using GCP ID tokens. Can only be used within GCP environments.
>
> [Read more about GCP ID Token Auth](https://infisical.com/docs/documentation/platform/identities/gcp-auth.md).
>
> | Field | Required | Description |
> | - | - | - |
> | `identityIdRef` | Yes | Reference to the secret containing the machine identity ID. |
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl create secret generic gcp-id-token-credentials \
>   --from-literal=identityId="<your-machine-identity-id>"
> ```
>
> Apply the resource:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

> [accordion] 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](https://infisical.com/docs/documentation/platform/identities/gcp-auth.md).
>
> | 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. |
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl create secret generic gcp-iam-credentials \
>   --from-literal=identityId="<your-machine-identity-id>"
> ```
>
> Apply the resource:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

> [accordion] LDAP Auth
>
> Authenticates using LDAP credentials.
>
> [Read more about LDAP Auth](https://infisical.com/docs/documentation/platform/identities/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. |
>
> ```yaml infisical-auth.yaml theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> 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:
>
> ```bash theme={"dark"}
> kubectl apply -f infisical-auth.yaml
> ```

## Troubleshooting

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

```bash theme={"dark"}
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 hasn't yet reconciled the latest changes to the resource.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.