> For the complete documentation index, see [llms.txt](https://docs.firefly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md).

# Cloud Credentials for Workflows

> **Related Guides and Examples:**
>
> * [Overview: Firefly Workflows and Guardrails](https://docs.firefly.ai/detailed-guides/workflows.md): High-level concepts and options.
> * [Creating New Firefly Workflows](https://docs.firefly.ai/detailed-guides/workflows/creating-workflows.md): How to set up managed workflows.
> * [Creating Projects](https://docs.firefly.ai/detailed-guides/workflows/creating-projects.md): How to create projects to group IaC orchestration resources and control access.
> * [Creating Variable Sets](https://docs.firefly.ai/detailed-guides/workflows/creating-variable-sets.md): Managing reusable variable collections.
> * [AWS Integration](https://docs.firefly.ai/integrations/data-sources/aws.md) and [Azure Integration](https://docs.firefly.ai/integrations/data-sources/azure.md): Connecting your cloud accounts to Firefly.
> * [Authentication using OIDC Provider](https://docs.firefly.ai/detailed-guides/oidc-provider.md): Project- and workspace-level OIDC authentication.

Firefly Workflows run `plan` and `apply` against your cloud accounts, so every run needs credentials that are allowed to create, change and delete resources. These **write credentials** are separate from the read-only credentials Firefly uses to discover your assets into the Inventory. The same write credentials are used wherever Firefly changes your cloud through a workflow run: workspace `apply`, drift remediation, codify-and-deploy, and Backup & DR restores.

You can now configure write credentials once, on the cloud **Integration** itself, and bind any number of workspaces to that Integration. In AWS an Integration is an account, and in Azure it is a subscription. Before this change, write credentials could only be supplied as variables on a project, a variable set or a workspace, which often meant storing the same account's keys in several places. Variable-based credentials still work, and Firefly resolves them in a fixed [precedence order](#credential-precedence).

> **Supported providers:** Integration-level write credentials are currently available for **AWS** and **Azure**. **Google Cloud** support is under development. For Google Cloud, keep using [OIDC at the project or workspace level](https://docs.firefly.ai/detailed-guides/oidc-provider/google-cloud.md) or variable-based credentials.

## How It Works

Each cloud Integration carries two kinds of access:

| Access               | Purpose                                                                                                                         | Where it is configured                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Discovery (read)** | Scans the account or subscription into the Inventory, IaC Explorer and governance features.                                     | Created when you add the Integration, with the CloudFormation or ARM template, PowerShell script or Terraform. |
| **Write access**     | Runs `plan` and `apply` for workspaces bound to the Integration, drift remediation, codify-and-deploy and Backup & DR restores. | **Settings > Integrations**, in the Integration's **Edit integration** dialog, under **Credentials**.          |

When a workspace is **bound** to an Integration, every `plan` and `apply` phase resolves the Integration's write credentials before `init`, and the runner injects them as the standard provider environment variables (for example `AWS_ACCESS_KEY_ID` or `ARM_CLIENT_ID`). Any conflicting cloud credentials inherited from variables are replaced for that run, while all other variables, module access and Firefly backend settings are preserved.

Workspaces that are not bound to an Integration keep the existing behavior: credentials come from variables, variable sets or [OIDC configured on the project or workspace](https://docs.firefly.ai/detailed-guides/oidc-provider.md).

> **Note:** Integration-level write credentials are available for workspaces that run on Firefly's **managed runners**. A workspace that uses a self-hosted runner pool, directly or through its project, can't be bound to an Integration. Self-hosted runners keep authenticating with their own environment, for example [IRSA on AWS](https://docs.firefly.ai/detailed-guides/workflows/creating-self-hosted-runner/self-hosted-runner-aws-irsa.md).

## Credential Precedence

When write credentials are available from more than one place, Firefly uses the first match in this order:

1. **Integration** bound to the workspace, when it has an enabled credential source. This takes precedence over everything else, including OIDC configured on the project or workspace.
2. **Variable set** consumed by the workspace, or inline workspace variables.
3. **Project** variables, inherited from the project or any parent project.
4. **Organization** variables.

In practice this means:

* A workspace that is bound to an Integration always uses the Integration's credentials, even if a variable set or project also carries keys for the same account.
* A workspace that is **not** bound, or whose Integration has no enabled credential source, falls back to the variable-based credentials it had before. If both a variable set and a project define credentials, the variable set wins, following the normal [variable precedence](https://docs.firefly.ai/detailed-guides/workflows/creating-workflows.md#variable-precedence).
* Binding an Integration doesn't delete any variables. You can remove the duplicated keys from projects and variable sets once all of their workspaces are bound.

## Configuring Write Credentials on an Integration

Only Firefly **Admins** can add, change, enable, disable or delete write credentials. Other users can see the configuration without the secret values.

**Procedure:**

1. Go to **Settings > Integrations** and open the **AWS** or **Azure** tab.
2. On the Integration's menu, select **Edit**.
3. The **Edit integration** dialog shows the Integration's **Name** and **Mark as Production** setting, followed by a **Credentials** section with two rows:
   * **Discovery (Read)**: The existing read-only role or service principal, with its connection status. You can't change it here.
   * **Write access**: Required for apply, remediation and deploy. Shows the current state, for example **Not configured**.
4. Under **Write credentials method**, choose a method and fill in its fields. The methods and fields for each provider are listed below.
5. Click **Save**. The Integration name and the write credentials are saved separately, so if one of them fails you are told which.

Until write credentials are added, the dialog shows the warning **This integration has no write credentials**: Firefly can read the account but can't run apply, remediate drift or codify-and-deploy there.

After saving, the **Write access** row shows one of these states:

| State              | Meaning                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Not configured** | No write credentials exist. Bound workspaces fall back to variable-based credentials.             |
| **Disabled**       | Credentials exist but none are enabled. Bound workspaces fall back to variable-based credentials. |
| **Configured**     | An enabled credential source exists and is used by bound workspaces.                              |

> **Note:** **Configured** means Firefly has stored valid-looking credentials. It doesn't verify that the role or key has the cloud permissions your IaC needs. A run with insufficient permissions fails at `plan` or `apply` with the provider's error.

### AWS

AWS Integrations support two methods:

**OIDC role** (*Recommended*)

Firefly assumes an IAM role in your account with a short-lived OpenID Connect token. No long-lived key is stored.

* **Role ARN** (*Required*): The ARN of the IAM role Firefly assumes.
* The role's trust policy must trust Firefly's OIDC provider with the audience `sts.amazonaws.com` and the subject `account:<your Firefly account ID>`. Use **Copy trust policy** in the dialog to get a policy with the right values. Creating the identity provider and the role in IAM is described in [Amazon Web Services (AWS) OIDC Integration](https://docs.firefly.ai/detailed-guides/oidc-provider/aws.md#configure-firefly-as-an-identity-provider).
* At run time the runner sets `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE`, so the AWS provider authenticates without any changes to your Terraform code.

**Environment variables**

Firefly stores an IAM user's static access keys and injects them into runs as environment variables.

* **Access key ID** and **Secret access key** (*Required*): Injected as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
* **Session token** and **Expiration** (*Optional*): For temporary credentials. Supply both or neither. The session token is injected as `AWS_SESSION_TOKEN`, and runs that start after the expiration fail.

You can keep both an OIDC role and environment variables on the same Integration. When both are enabled, the OIDC role is used.

### Azure

Azure Integrations use the **Service principal** method: a client ID and secret that are injected into runs as environment variables. OIDC isn't currently available for Azure write access.

* **Client ID**, **Tenant ID** and **Subscription ID** (*Required*): The subscription must be the one the Integration discovers.
* **Client secret** (*Required*).

At run time the runner sets `ARM_CLIENT_ID`, `ARM_CLIENT_SECRET`, `ARM_TENANT_ID` and `ARM_SUBSCRIPTION_ID`. If your workspace uses an Azure Storage backend with Entra ID authentication, `ARM_USE_AZUREAD` is preserved.

> **Tip:** Grant the service principal a role scoped to what your workspaces manage, for example **Contributor** on the subscription or on specific resource groups. Keep it separate from the read-only service principal created for discovery.

### Google Cloud

Integration-level write credentials for Google Cloud are under development. Until they are available, authenticate Google Cloud workspaces with [OIDC at the project or workspace level](https://docs.firefly.ai/detailed-guides/oidc-provider/google-cloud.md) or with variable-based credentials.

## Managing Write Credentials

Open the Integration's **Edit** dialog to manage the credentials you saved:

* **Edit:** Change the role ARN or the non-secret fields. The method of a saved credential can't be changed. To switch from environment variables to an OIDC role, add the role and then disable or delete the keys.
* **Replace secret:** Secrets are write-only. Firefly never shows a saved secret, and you replace it by entering a new one.
* **Enable / Disable:** Disabling keeps the credentials stored but stops using them. All workspaces bound to the Integration fall back to the next source in the [precedence order](#credential-precedence).
* **Delete:** Removes the credentials from Firefly. Bound workspaces stay bound and fall back to variable-based credentials until you add new ones.

> **Notes:**
>
> * Changes take effect at the next `plan` or `apply` phase, including a delayed `apply` that was planned earlier. A command that is already running isn't affected.
> * Replacing or deleting credentials in Firefly doesn't revoke the key or role in your cloud account. Rotate or revoke it there as well.
> * If a bound workspace's credentials fail to resolve, for example because the secret expired, the run stops with an error. Firefly doesn't fall back to a different identity silently.

## Binding a Workspace to an Integration

**Procedure:**

1. In the workspace creation wizard, or in **Edit** on an existing workspace, go to the **Configuration** step.
2. Under **Runner Configuration**, make sure the runner type is **Managed by Firefly**.
3. In **Integration**, select the AWS account or Azure subscription the workspace deploys to. The list shows the cloud Integrations you have access to.
4. Save the workspace.

When an Integration is selected, the workspace's own OIDC settings are inactive and the Integration's credentials are used instead. Your existing variables, variable sets and backend settings are kept.

To unbind a workspace, clear the **Integration** selection and save. From the next run, the workspace authenticates with variables or project and workspace OIDC again.

> **Note:** Binding an Integration doesn't create credentials or start a run. If the Integration has no enabled write credentials, the workspace runs with variable-based credentials until you add them.

## Backup & DR Applications

[Recovery Automation](https://docs.firefly.ai/key-features/backup-and-dr.md) rebuilds an application in a recovery target by running a workflow. In the application wizard's **Resilience** step, the **Recovery target** is the destination Integration (account or subscription) and region, and Firefly restores with that Integration's write credentials.

If the selected Integration has no write credentials, the wizard warns that Firefly can't restore resources into the target until they are added. Click **Add write credentials** to open the Integration's **Edit integration** dialog, add them as described above, and then click **Check again**. You can still create the application first and add the credentials later, but a restore can't run until they exist.

The Plan workflow that Firefly runs on every snapshot can run with the Integration's discovery credentials when the target Integration has no write credentials, so snapshots keep validating even before write access is configured. An `apply` always requires write credentials.

## Moving from Variable-Based Credentials

If you already deliver credentials through projects or variable sets, for example with the `AWS Cloud Credentials` variable set template:

1. Add write credentials to each AWS account or Azure subscription Integration as described above.
2. Bind each workspace to its Integration. The Integration's credentials now take precedence, so this is safe to do one workspace at a time.
3. Once every workspace that consumed a credentials variable set is bound, remove the credential variables from the variable set or project, or delete the set.

Variable-based credentials remain supported, and you can mix both approaches while you migrate.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.firefly.ai/detailed-guides/workflows/cloud-credentials.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
