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

## Example

You can only define one authentication method per InfisicalAuth resource.

<AccordionGroup>
  <Accordion title="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](/documentation/platform/identities/kubernetes-auth).

    <Accordion title="Short-lived service account tokens (Recommended)">
      <Steps>
        <Step title="Create a machine identity">
          To create an identity, head to your Organization Settings > Access Control > Identities and press **Create identity**.

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org.png" alt="identities organization" />

          When creating an identity, you specify an organization level [role](/documentation/platform/access-controls/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles.

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org-create.png" alt="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**.

          <Info>
            To learn more about each field of the Kubernetes native authentication method, see step 2 of [guide](/documentation/platform/identities/kubernetes-auth#guide).
          </Info>

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-org-create-kubernetes-auth-method.png" alt="identities organization create auth method" />
        </Step>

        <Step title="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.

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-project.png" alt="identities project" />

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-project-create.png" alt="identities project create" />
        </Step>

        <Step title="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
          ```
        </Step>

        <Step title="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
          ```
        </Step>

        <Step title="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.
          </Tip>
        </Step>

        <Step title="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
          ```
        </Step>

        <Step title="Apply the resource">
          ```bash theme={"dark"}
          kubectl apply -f infisical-auth.yaml
          ```
        </Step>
      </Steps>
    </Accordion>

    <Accordion title="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>

      <Info>
        **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.
      </Info>

      <Steps>
        <Step title="Deploying a gateway">
          To deploy a gateway in your Kubernetes cluster, follow our [Gateway deployment guide using Helm](/documentation/platform/gateways/gateway-deployment).
        </Step>

        <Step title="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](/documentation/platform/gateways/gateway-pools) for more details.

          <img src="https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/identities/identities-kubernetes-auth-gateway-as-reviewer.png" alt="identities organization create kubernetes auth method" />
        </Step>

        <Step title="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>"
          ```
        </Step>

        <Step title="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.
          </Tip>
        </Step>

        <Step title="Apply the resource">
          ```bash theme={"dark"}
          kubectl apply -f infisical-auth.yaml
          ```
        </Step>
      </Steps>
    </Accordion>

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

    <KubernetesAuthOperatorSetup apiVersion="v1beta1" />
  </Accordion>

  <Accordion title="Universal Auth">
    Authenticates using a client ID and client secret. Works anywhere, not tied to any cloud provider.

    [Read more about Universal Auth](/documentation/platform/identities/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. |

    <Steps>
      <Step title="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](/documentation/platform/identities/universal-auth).
      </Step>

      <Step title="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>"
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    ```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>

  <Accordion title="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](/documentation/platform/identities/aws-auth).

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

  <Accordion title="Azure Auth">
    Authenticates using Azure managed identity. Can only be used within Azure environments.

    [Read more about Azure Auth](/documentation/platform/identities/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.       |

    ```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>

  <Accordion title="GCP ID Token Auth">
    Authenticates using GCP ID tokens. Can only be used within GCP environments.

    [Read more about GCP ID Token Auth](/documentation/platform/identities/gcp-auth).

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

  <Accordion title="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](/documentation/platform/identities/gcp-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. |

    ```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>

  <Accordion title="LDAP Auth">
    Authenticates using LDAP credentials.

    [Read more about LDAP Auth](/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
    ```
  </Accordion>
</AccordionGroup>

## 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 has not yet reconciled the latest changes to the resource.