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

# Authorize an Astro Deployment to cloud resources using workload identity

When you create an Airflow connection from a Deployment to access cloud resources, Airflow uses your connection details to access those services. You can add credentials to your Airflow connections to authenticate, but it can be risky to add secrets like passwords to your Airflow environment.

To avoid adding secrets to your Airflow connection, you can directly authorize your Astro Deployment to access AWS, GCP, and Azure cloud services using workload identity. Astronomer recommends using a workload identity in most cases to improve security and avoid managing credentials across your Deployments. If you have less strict security requirements, you can still use any of the methods described in [Airflow connection guides](/docs/learn/connections) to manage your connection authorization.
This guide explains how to authorize your Deployment to a cloud using workload identity. For each Deployment, you will:

* Authorize your Deployment to your cloud services.
* Create an Airflow connection to access your cloud services.

<Tip>Watch the Astro Academy [Customer Workload Managed Identity](https://academy.astronomer.io/learning-bytes-customer-workload-managed-identity) Learning Byte video to learn more about managed identities and how to set up passwordless authentication for GCP.</Tip>

## Prerequisites

The Astro cluster running your Deployment must be connected to your cloud's network. See [Networking overview](/docs/astro/networking-overview).

## What is workload identity?

A workload identity is a Kubernetes service account that provides an identity to your Deployment. The Deployment can use this identity to authenticate to a cloud's API server, and the cloud can use this identity to authorize the Deployment to access different resources.

<Tip>
  **A new Astro UI is here**

  Astronomer has redesigned the Astro UI. Try the new experience and switch your instructions using the **New Astro UI** and **Legacy UI** tabs on this page. Your selection is remembered across the docs.
</Tip>

## Setup

<Tabs>
  <Tab title="AWS" language="aws">
    <Tip>
      You can also use either the Astro CLI or the Astro API to configure workload identity when you create or update a Deployment by providing the AWS ARN value.

      See the following pages for more detail:

      * [`astro deployment create`](/docs/cli/v1.43/astro-deployment-create#options) CLI reference
      * [`astro deployment update`](/docs/cli/v1.43/astro-deployment-update#options) CLI reference
      * [Create Deployment with the Astro API](/docs/astro/api/v-1/deployment/create-a-deployment)
      * [Update Deployment with the Astro API](/docs/astro/api/v-1/deployment/update-a-deployment)
    </Tip>

    ### Attach an IAM role to your Deployment

    You can attach an AWS IAM role to your Deployment to grant the Deployment all of the role's permissions.

    Using IAM roles provides the greatest amount of flexibility for authorizing Deployments to your cloud. For example, you can use existing IAM roles on new Deployments, or your can attach a single IAM role to multiple Deployments that all require the same level of access to your cloud.

    #### Prerequisites

    * Minimum Astro Runtime version:
      * 9.15.0
      * 10.9.0
      * 11.5.0
    * A new or existing IAM role in your data sources with the required permissions you want your Deployment to have.
    * If using [AWS CloudShell](https://aws.amazon.com/cloudshell/),
      the required CLIs are enabled by default.
    * If you use a local terminal, the following CLIs are required:
      * [AWS CLI](https://aws.amazon.com/cli/)
      * [jq](https://jqlang.github.io/jq/)
      * [openSSL](https://www.openssl.org/source/)

    #### Step 1: Authorize the Deployment to your IAM role

    To authorize your Deployment, create an IAM role to assign as your Deployment's workload identity:

    1. [Create an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) to delegate permissions to in an AWS service. Grant the role any permission that the Deployment will need in your AWS account. Copy the IAM role ARN to use later in this setup.
    2. In the Astro UI, select your Deployment and then click **Details**. In the **Advanced** section, click **Edit**.
    3. In the **Workload Identity** menu, select **Customer Managed Identity**.
    4. Enter your IAM role ARN when prompted, then copy and run the provided CLI command. Click **Save Configuration** to save the IAM role as a selectable configuration.

           <Info>
             **About the AWS CLI command**

             The command performs the following actions in your AWS account:

             * Creates an [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) for the Astro cluster's EKS OIDC issuer URL, if one doesn't already exist. You can view existing providers in the AWS console at **IAM** > **Identity providers**.
             * Updates the trust policy of the IAM role you specified to allow the Astro cluster's service accounts to assume the role through `sts:AssumeRoleWithWebIdentity`. You can view the updated trust policy in the AWS console at **IAM** > **Roles** > *your role* > **Trust relationships**.

             The IAM principal that runs the command needs permissions to create OIDC providers and update IAM role trust policies, such as `iam:CreateOpenIDConnectProvider`, `iam:GetRole`, and `iam:UpdateAssumeRolePolicy`. If the command fails, verify these permissions and check the resources listed previously in the AWS console.
           </Info>
    5. Click **Update Deployment** to apply the selected IAM role to the Deployment.
    6. (Optional) Repeat these steps for each Astro Deployment that needs to access your AWS resources. Or, you can edit the `<DeploymentNamespace>` value in `Condition` when setting up the Workload Identity for one of the following scenarios to apply to multiple Deployments.

    <AccordionGroup>
      <Accordion title="Specify Kubernetes service accounts">
        Available for both Standard and Dedicated clusters. If your organization doesn't allow you to use a wildcards in your IAM Trust Policies, change the `<DeploymentNamespace>` value in `Condition` to specify the Kubernetes service accounts. The following shows an example:

        ```json wrap theme={null}
        {
          "Condition": {
            "StringLike": {
              "<cluster-oidc-issuer-url>:aud": "sts.amazonaws.com",
              "<cluster-oidc-issuer-url>:sub": [
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-kpo",
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-dag-processor-serviceaccount",
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-scheduler-serviceaccount",
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-triggerer-serviceaccount",
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-apiserver-serviceaccount",
                "system:serviceaccount:<deployment-namespace>:<deployment-namespace>-worker-serviceaccount"
              ]
            }
          }
        }
        ```

        <Note>For Airflow 2 Deployments, `apiserver-serviceaccount` is named `webserver-serviceaccount`.</Note>
      </Accordion>

      <Accordion title="Dedicated clusters only: Share or re-use a managed identity using a wildcard">
        If you want to share or re-use the same customer managed identity on static or ephemeral Deployments for dedicated clusters, without having to update your Trust Policy in your AWS account for every net new Deployment, change the `<DeploymentNamespace>` value in `Condition` to include a wildcard. You should only use a wildcard in dedicated clusters for security purposes. The following shows an example:

        ```json wrap theme={null}
        {
          "Condition": {
            "StringLike": {
              "<cluster-oidc-issuer-url>:aud": "sts.amazonaws.com",
              "<cluster-oidc-issuer-url>:sub": "system:serviceaccount:*:*"
            }
          }
        }
        ```
      </Accordion>
    </AccordionGroup>

    #### Step 2: Create an Airflow connection

    Now that your Deployment is authorized, you can connect it to your cloud using an Airflow connection. Create an **Amazon Web Services** connection in either the [Astro UI](/docs/astro/create-and-link-connections) or the Airflow UI for your Deployment and specify the following fields:

    * **Connection Id**: Enter a name for the connection.

    If you don't see **Amazon Web Services** as a connection type in the Airflow UI, ensure you have installed its provider package in your Astro project's `requirements.txt` file. See **Use Provider** in the [Airflow Registry](https://airflow.apache.org/registry/providers/amazon) for the latest package.

    <Tip>
      If you use a mix of strategies for managing connections and define the same connection in multiple ways, Airflow uses the following order of precedence:

      * Secrets Backend
      * Environment Manager
      * Environment Variables
      * Airflow UI using the Airflow metadata database
    </Tip>

    ### Alternative setup: Authorize your Deployment with AWS IAM roles

    #### Step 1: Authorize the Deployment in your cloud

    To grant a Deployment access to a service that is running in an AWS account not managed by Astronomer, use AWS IAM roles to authorize your Deployment's workload identity. IAM roles on AWS are often used to manage the level of access a specific user, object, or group of users has to a resource, such as Amazon S3 buckets, Redshift instances, and secrets backends.

    To authorize your Deployment, create an IAM role that is assumed by the Deployment's workload identity:

    1. In the Astro UI, select your Deployment and then click **Details**. Copy the Deployment's **Workload Identity**.

    2. In the AWS account that contains your AWS service, create an IAM role. See [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).

    3. In the AWS Management Console, go to the Identity and Access Management (IAM) dashboard.

    4. Click **Roles** and in the **Role name** column, select the role you created in Step 2.

    5. Click **Trust relationships**.

    6. Click **Edit trust policy** and paste the workload identity you copied from Step 1 in the trust policy. Your policy should look like the following:

       ```json wrap theme={null}
       {
         "Version": "2012-10-17",
         "Statement": [
           {
             "Effect": "Allow",
             "Principal": {
               "AWS": ["<default-workload-identity-role>"]
             },
             "Action": "sts:AssumeRole"
           }
         ]
       }
       ```

    7. Click **Update policy**.

    Repeat these steps for each Astro Deployment that needs to access your AWS resources.

    #### Step 2: Create an Airflow connection

    Now that your Deployment is authorized, you can connect it to your cloud using an Airflow connection. Either create an **Amazon Web Services** connection in the [Astro UI](/docs/astro/create-and-link-connections) or the Airflow UI for your Deployment and specify the following fields:

    * **Connection Id**: Enter a name for the connection.
    * **Extra**:

      ```json wrap theme={null}
      {
        "role_arn": "<your-role-arn>",
        "region_name": "<your-region>"
      }
      ```

    If you don't see **Amazon Web Services** as a connection type in the Airflow UI, ensure you have installed its provider package in your Astro project's `requirements.txt` file. See **Use Provider** in the [Airflow Registry](https://airflow.apache.org/registry/providers/amazon) for the latest package.

    <Tip>
      If you use a mix of strategies for managing connections, if you define the same connection in multiple ways, Airflow uses the following order of precedence:

      * Secrets Backend
      * Environment Manager
      * Environment Variables
      * Airflow UI using the Airflow metadata database
    </Tip>
  </Tab>

  <Tab title="GCP" language="gcp">
    <Tip>
      You can also use either the Astro CLI or the Astro API to configure workload identity when you create or update a Deployment by providing the GCP service account email.

      See the following pages for more detail:

      * [`astro deployment create`](/docs/cli/v1.43/astro-deployment-create#options) CLI reference
      * [`astro deployment update`](/docs/cli/v1.43/astro-deployment-update#options) CLI reference
      * [Create Deployment with the Astro API](/docs/astro/api/v-1/deployment/create-a-deployment)
      * [Update Deployment with the Astro API](/docs/astro/api/v-1/deployment/update-a-deployment)
    </Tip>

    ### Attach a service account to your Deployment

    You can attach a custom GCP service account to your Deployment to grant the Deployment all of the service account's permissions.

    Using service accounts provides the greatest amount of flexibility for authorizing Deployments to your cloud. For example, you can use existing service accounts on new Deployments, or your can attach a single service account to multiple Deployments that all have the same level of access to your cloud.

    1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) in the GCP project that you want your Deployment to access. Grant the service account any permissions that the Deployment will need in your GCP project. Copy the service account ID to use later in this setup.

    2. In the Astro UI, select your Deployment, then click **Details**. In the **Advanced** section, click **Edit**.

    3. In the **Workload Identity** menu, select **Customer Managed Identity**

    4. Enter your GCP service account ID when prompted, then copy and run the provided gcloud CLI command.

           <Info>
             **About the gcloud CLI command**

             The command adds an IAM policy binding to your GCP service account that grants the `roles/iam.workloadIdentityUser` role to each of the Deployment's Kubernetes service accounts (`scheduler`, `triggerer`, `worker`, `apiserver`, `dag-processor`, and `kpo`). This allows those workloads to impersonate your GCP service account through workload identity federation.

             You can view the updated bindings in the Google Cloud console at **IAM & Admin** > **Service Accounts** > *your service account* > **Permissions**.

             The principal that runs the command needs the `iam.serviceAccountAdmin` role, or equivalent permissions including `iam.serviceAccounts.setIamPolicy`, on the GCP service account. If the command fails, verify these permissions and check the service account's IAM policy in the Google Cloud console.
           </Info>

    5. Click **Update Deployment**. The service account is now selectable as a workload identity for the Deployment.

    6. Complete one of the following options for your Deployment to access your cloud resources:

       * Create a **Google Cloud** connection type in Airflow and configure the following values:

         * **Connection Id**: Enter a name for the connection.
         * **Impersonation Chain**: Enter the ID of the service account that your Deployment should impersonate.

       * To access resources in a secrets backend, run the following command to create an environment variable that grants access to the secrets backend:

       ```bash wrap theme={null}
       astro deployment variable create \
         --deployment-id <your-deployment-id> \
         'AIRFLOW__SECRETS__BACKEND_KWARGS={"connections_prefix": "airflow-connections", "variables_prefix": "airflow-variables", "project_id": "<your-secret-manager-project-id>", "impersonation_chain": "<your-gcp-service-account>"}'
       ```

    #### Dedicated clusters only: Share or reuse a managed identity using a wildcard

    <Warning>You can only use wildcard `principalSet` bindings with hosted dedicated clusters. Never use wildcard bindings with standard Deployments, which run on shared clusters.</Warning>

    If you want to share or reuse the same customer managed identity across multiple Deployments, for example with ephemeral Deployments, on a dedicated cluster without creating a per-Deployment IAM policy binding, you can use a wildcard `principalSet` binding. This authorizes all service accounts across all namespaces in the cluster to use your GCP service account, so you can specify the same custom workload identity on any Deployment in the cluster, including at Deployment creation time.

    You can find the GKE project number and project ID for your cluster. Go to **Settings** > **Clusters** in the Astro UI and click the **Details** tab. You can also use a [GET cluster API call](https://www.astronomer.io/docs/astro/api/v-1/cluster/get-a-cluster) with your cluster ID.

    ```sh wrap theme={null}
    gcloud iam service-accounts add-iam-policy-binding <service-account> \
      --role roles/iam.workloadIdentityUser \
      --member "principalSet://iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<project-id>.svc.id.goog/kubernetes.cluster/https://container.googleapis.com/v1/projects/<project-id>/locations/<location>/clusters/<cluster-id>" \
      --project <service-account-project>
    ```

    Replace the following values:

    * `<LOCATION>`: The cluster's region.
    * `<CLUSTER_ID>`: ID of the cluster.
    * `<SERVICE_ACCOUNT>`: ID of the serviceAccount or fully qualified identifier for the serviceAccount you want your Deployments to use.
    * `<PROJECT_NUMBER>`: The GCP project number for the Astro-managed GKE cluster.
    * `<PROJECT_ID>`: The GCP project ID for the Astro-managed GKE cluster.
    * `<SERVICE_ACCOUNT_PROJECT>`: The GCP project that contains your service account.

    ### Alternative setup: Authorize your Deployment through GCP service account impersonation

    If your organization has requirements over how service accounts are managed outside of your cloud, you can manually configure [GCP service account impersonation](https://cloud.google.com/docs/authentication/use-service-account-impersonation) to allow your Deployment's default workload identity to impersonate a service account in your GCP project.

    1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) in the GCP project that you want your Deployment to access. Grant the service account any permissions that the Deployment will need in your GCP project. Copy the service account ID to use later in this setup.
    2. In the Astro UI, select your Deployment, then click **Details**. Copy the Deployment's **Workload Identity**.
    3. In the Google Cloud Console, open the **IAM & Admin > Service Accounts** menu, then open the service account you just created.
    4. In the **Actions** column, click **Manage Permissions**, then click **Grant Access**. In the modal that appears, enter your Deployment's workload identity service account in the **Add Principals** field and select the [`Service Account Token Creator`](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountTokenCreator) in the **Assign Roles** field.
    5. Complete one of the following options for your Deployment to access your cloud resources:

       * Create a **Google Cloud** connection type in Airflow and configure the following values:
         * **Connection Id**: Enter a name for the connection.
         * **Impersonation Chain**: Enter the ID of the service account that your Deployment should impersonate.

       Note that this implementation requires `apache-airflow-providers-google >= 10.8.0`. See [Add Python, OS-level packages, and Airflow providers](/docs/cli/v1.43/add-providers-packages).

       * Specify the impersonation chain in code when you instantiate a Google Cloud operator. See [Airflow documentation](https://airflow.apache.org/docs/apache-airflow-providers-google/stable/connections/gcp.html#direct-impersonation-of-a-service-account). Note that if you configure both a connection type and an operator, the operator-level configuration takes precedence.
       * To access resources in a secrets backend, run the following command to create an environment variable that grants access to the secrets backend:

       ```bash wrap theme={null}
       astro deployment variable create \
         --deployment-id <your-deployment-id> \
         'AIRFLOW__SECRETS__BACKEND_KWARGS={"connections_prefix": "airflow-connections", "variables_prefix": "airflow-variables", "project_id": "<your-secret-manager-project-id>", "impersonation_chain": "<your-gcp-service-account>"}'
       ```

    ### Alternative setup: Grant an IAM role to your Deployment workload identity

    Complete this alternative setup if you don't have an existing Google service account that your Deployment workload identity can impersonate.

    #### Step 1: Authorize the Deployment in your cloud

    To grant a Deployment access to a service that is running in a GCP account not managed by Astronomer, use your Deployment's workload identity. Workload identity is a service account in GCP that's used to manage the level of access for a specific user, object, or group of users to a resource, such as Google BigQuery or a GCS bucket.

    To authorize your Deployment, grant the required access to your Deployment's workload identity:

    1. In the Astro UI, select your Deployment, then click **Details**. In the **Workload Identity** dropdown menu, select **Default Identity**. Then, copy the workload identity that appears next to the dropdown menu.

    2. Grant your Deployment's workload identity an IAM role that has access to your external data service. To do this with the Google Cloud CLI, run:

       ```bash wrap theme={null}
       gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
         --member=serviceAccount:<workload-identity> \
         --role=<your-role>
       ```

       To grant your workload identity an IAM role using the Google Cloud console, see [Grant an IAM role](https://cloud.google.com/iam/docs/grant-role-console#grant_an_iam_role).

    Repeat these steps for each Deployment that needs to access your GCP resources.

    #### Step 2: Create an Airflow connection

    Now that your Deployment is authorized, you can connect it to your cloud using an Airflow connection. Either create a **Google Cloud** connection in the [Astro UI](/docs/astro/create-and-link-connections) or the Airflow UI for your Deployment and specify the following fields:

    * **Connection Id**: Enter a name for the connection.
    * **Project Id**: Enter the ID of your Google Cloud Project where your services are running.

    If you don't see **Google Cloud** as a connection type in the Airflow UI, ensure you have installed its provider package in your Astro project's `requirements.txt` file. See **Use Provider** in the [Airflow Registry](https://airflow.apache.org/registry/providers/google/) for the latest package.

    <Tip>
      If you use a mix of strategies for managing connections, if you define the same connection in multiple ways, Airflow uses the following order of precedence:

      * Secrets Backend
      * Environment Manager
      * Environment Variables
      * Airflow UI using the Airflow metadata database
    </Tip>
  </Tab>

  <Tab title="Azure" language="azure">
    In this setup, you'll authorize an existing user-assigned managed identity to a resource on Azure, then give permissions to your Deployment to assume that managed identity.

    #### Prerequisites

    * A [Microsoft Entra ID tenant](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant) with Global Administrator or Application Administrator privileges.
    * A user-assigned managed identity on Azure. See [Azure documentation](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?source=recommendations\&pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity).
    * The [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).

    <Warning>You can only use the same user-assigned managed identity for up to four Deployments. If you need to authorize more than four Deployments to Azure, you need to create more than one user-managed identity. For more information, see [Microsoft Entra documentation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-considerations#general-federated-identity-credential-considerations).</Warning>

    #### Step 1: Authorize the managed identity in Azure

    1. In your Azure portal, open the resource that your managed identity needs access to. Then, select **Access control (IAM)**.
    2. Click **Add** > **Add role assignment**.
    3. Select the role for your managed identity, then click **Next**.
    4. In the **Assign access to** section, select **Managed identity**. Click **+ Select Members** and choose your managed identity. After you add your managed identity, click **Next**.
    5. Review and finalize the assignment.

    #### Step 2: Configure your Deployment

    1. In your Azure portal, open the **Managed Identities** menu.

    2. Search for your managed identity, click **Properties**, then copy its **Name**, **Client ID**, **Tenant ID**, and **Resource group** name.

    3. In the Astro UI, select your Deployment, click **Details**, then click **How to Configure...** under **Workload Identity**.

    4. In **Managed Identity**, enter the Name of the managed identity you assigned to the resource.

    5. In **Resource Group**, enter the **Resource group** name that your managed identity belongs to.

    6. Using the Azure CLI, copy and run the provided command in your local terminal.

           <Info>
             **About the Azure CLI command**

             The command creates [federated identity credentials](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) on your user-assigned managed identity, one for each of the Deployment's Kubernetes service accounts (`scheduler`, `triggerer`, `worker`, `apiserver`, `dag-processor`, and `kpo`). Each federated credential trusts the Astro cluster's OIDC issuer and maps a specific Kubernetes service account to your managed identity.

             You can view the created credentials in the Azure portal at **Managed Identities** > *your managed identity* > **Settings** > **Federated credentials**.

             The principal that runs the command needs the [Contributor](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#contributor) or [Owner](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner) role on the managed identity. If the command fails, verify these permissions and check the **Federated credentials** page in the Azure portal.
           </Info>

    7. After the command completes, click **Close** on the window in the Astro UI.

    8. (Optional) repeat Steps 4 - 8 for any other Deployments that need to be authorized to Azure.

    #### Step 3: Create an Airflow connection

    <Tabs>
      <Tab title="New Astro UI" language="astro-next-ui">
        1. In the Astro UI, go to **Environment** > **Connections**.
        2. Click **+ New Connection** to add a new connection for your Workspace.
        3. Search for **Azure**, then select the **Managed identity** option.
        4. Configure your Airflow connection with the information you copied in the previous steps.
        5. Link the connection to the Deployment(s) where you configured your managed identity.
      </Tab>

      <Tab title="Legacy UI" language="legacy-ui">
        1. In the Astro UI, click **Environment** in the main menu to open the **Connections** page.
        2. Click **+ Connection** to add a new connection for your Workspace.
        3. Search for **Azure**, then select the **Managed identity** option.
        4. Configure your Airflow connection with the information you copied in the previous steps.
        5. Link the connection to the Deployment(s) where you configured your managed identity.
      </Tab>
    </Tabs>

    Any Dag that uses your connection will now be authorized to Azure through your managed identity.

    <Tip>
      If you use a mix of strategies for managing connections, if you define the same connection in multiple ways, Airflow uses the following order of precedence:

      * Secrets Backend
      * Environment Manager
      * Environment Variables
      * Airflow UI using the Airflow metadata database
    </Tip>
  </Tab>
</Tabs>

## See also

* [Manage Airflow connections and variables](/docs/astro/manage-connections-variables)
* [Deploy code to Astro](/docs/astro/deploy-code)