# Configure workload identity

Workload identity allows your services and jobs to securely access resources in your AWS or GCP account without managing credentials manually. Northflank assumes a role in your cloud account using OIDC (OpenID Connect), automatically injecting credentials that cloud SDKs recognize.

## How it works

When you configure workload identity:

1. Select a cloud provider integration (AWS or GCP)

2. Northflank installs an OIDC provider in your cloud account (if not already installed)

3. You define permissions for the workload identity

4. You configure which projects and tags can use the identity

5. Northflank automatically injects credentials into matching workloads

6. Credentials are refreshed before expiration

Your workloads can then access cloud resources (S3 buckets, Cloud Storage, databases, etc.) without hardcoded credentials.

## Create a workload identity

Use an AWS or GCP [cloud integration](use-other-cloud-providers-with-northflank) with the workload identity features available to your account. Select Workload Identity for access to existing identity resources. To let Northflank create and manage identity resources, also select Workload Identity Managed and grant the required cloud permissions.

For AWS, use a [cross-account role](aws-on-northflank#add-your-account-with-a-cross-account-role) or [access key](aws-on-northflank#add-your-account-with-an-iam-user). For GCP, use Service account key. These integration credentials are separate from the temporary credentials that workloads receive.

For sovereign resources, use an [AWS European Sovereign Cloud integration](aws-on-northflank#aws-european-sovereign-cloud). Use `arn:aws-eusc:` in resource and role ARNs, for example `arn:aws-eusc:s3:::my-bucket/*`.

To create a workload identity:

1. Open [Cloud → Workload identities](https://app.northflank.com/s/account/cloud/workload-identities/new).

### Basic information

1. **Name**: Provide a name for the workload identity (e.g., `s3-access`)

2. **Description**: (Optional) Describe what this identity is used for

3. Provider: Select Amazon Web Services, AWS European Sovereign Cloud, or Google Cloud Platform.

Set Priority to an integer from `0` to `100`. The default is `10`.

Northflank uses priority to choose between matching identities for each cloud provider. See the [selection rules, including precedence for linked addons](#selection-priority).

### Integration

1. **Credential name**: Select your cloud provider integration

2. **Provider setup**: Choose how to set up the OIDC provider
  
  
  
  - **Automatic** (recommended): Northflank installs the required resources
  
  - **Manual**: You create the IAM OpenID Connect identity provider yourself using the Provider URL and Audience shown. This is useful when your credentials lack permission to manage IAM infrastructure.

When using Manual setup, click **Verify** after creating the resources in your cloud account. Verify may fail if credentials lack read permissions, but the workload identity can still work if configured correctly.

### Scope

Configure which project can use this identity. By default, the identity is not available to any project.

**Project restriction:**

- Enable to restrict to specific projects

- Select which projects can use this identity

- Disable to allow all projects

**Tag restriction:**

- Enable to restrict by workload tags

- Add tags that workloads must have

- Toggle **Force matching all tags** to require workloads to have ALL specified tags (not just one)

- Disable to allow all workloads

**Note:** Project and tag restrictions work together with AND logic. Workloads must satisfy both configured restrictions (if enabled) to use the identity.

### Permission details

1. **Role mode**: Choose how to configure the IAM role
  
  
  - **Managed role** (recommended): Northflank creates and manages the IAM role
  
  - **Existing role**: Use a pre-existing IAM role from your cloud account

**For Managed role:**

**AWS:**

Provide an IAM policy document:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}
```

**GCP:**

Provide a list of permissions:

```
storage.objects.get
storage.objects.create
storage.buckets.list
```

**For Existing role:**

Create an IAM role in your cloud account with the trust policy shown in the UI, then enter the role ARN or name and click **Verify**.

### Create and install

Click **Create and install** to:

- Create the workload identity in Northflank

- Install the OIDC provider in your cloud account (if this is the first identity for this integration)

- Create the IAM role with the specified permissions

Or click **Create** to save the configuration without installing.

## Update workload identity

To change an existing workload identity:

1. Open [Cloud → Workload identities](https://app.northflank.com/s/team/cloud/workload-identities).

2. Select the workload identity.

3. Change its Priority, project and tag restrictions, or permission details.

4. Save the changes with the appropriate control below.

| Change | Save control |
| --- | --- |
| Priority or project and tag restrictions | Update |
| Permissions for a managed role | Update and install |

Priority and restriction changes do not require you to reinstall cloud permissions.

For managed roles, Update and install saves changes and starts installation in your cloud account. For example, Northflank creates or updates the IAM role and policy for a managed AWS role.

If you select only Update after changing managed permissions, Northflank saves the changes but does not install them.

### Apply a change in identity selection

Changing priority or restrictions can select a different identity and change the cloud permissions available to a workload on its next deployment.

Before restarting a workload, inspect its selected identity on the Workload identities page.

If a service shows Restart required, restart it to apply the selected identity configuration. For jobs, New configuration pending means that new runs use the selected identities. Running jobs retain the configuration from when they started.

## View active workload identities

On your service or job, select Workload identities in the sidebar.

The page shows matching identities and marks the selected identity for each cloud provider. Each entry includes:

- Workload identity name and description

- Cloud provider (e.g., Amazon Web Services, Google Cloud Platform)

- Source: provider integration or linked external addon

- Priority

- Creation date

### Selection priority

Northflank selects one eligible identity per cloud provider. The selection follows these rules:

1. Identities from linked external addons take precedence over identities matched through project and tag restrictions.

2. Within each source, the identity with the highest priority wins.

3. If priorities match, Northflank selects the first identity alphabetically by name.

For two AWS identities matched through project and tag restrictions, `aws-s3-access` at priority `20` takes precedence over `aws-prod` at `10`. If both use `10`, Northflank selects `aws-prod`.

An identity from a linked external addon still takes precedence over a project or tag match with a higher priority.

### Injected credentials

When a workload identity is active, Northflank automatically injects:

**Managed environment variables:**

- `AWS_ROLE_ARN` - The IAM role ARN (for AWS)

- `AWS_WEB_IDENTITY_TOKEN_FILE` - Path to the token file (for AWS)

- (GCP equivalents for Google Cloud)

**Managed files:**

- `/awstoken` - Web identity token file

Official cloud SDKs automatically detect and use these credentials. If you're connecting to cloud providers through other means, you can read these injected values directly.

## Example: S3 access from a service

This example shows a complete workflow for giving a service access to an S3 bucket.

**Setup:**

1. Navigate to **Cloud** → **Workload identities** → **Create new workload identity**

2. Configure:
  
  
  - **Name**: `s3-bucket-access`
  
  - **Provider**: AWS
  
  - **Integration**: Select your AWS integration
  
  - **Project restriction**: Enable and select your project

3. In **Permission details**, add this policy:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:*"],
      "Resource": [
        "arn:aws:s3:::my-app-bucket",
        "arn:aws:s3:::my-app-bucket/*"
      ]
    }
  ]
}
```

1. Click **Create and install**

**Application code:**

The AWS SDK automatically uses the injected credentials:

```javascript
const AWS = require('aws-sdk');
const s3 = new AWS.S3();

s3.getObject({
  Bucket: 'my-app-bucket',
  Key: 'file.txt'
}, (err, data) => {
  console.log(data.Body.toString());
});
```

No credential configuration needed - it just works.

## Best practices

**Scope configuration:**

- Use project restrictions for team-level access control

- Use tag restrictions for workload-specific access

- Enable "Force matching all tags" when you need to be more restrictive on workload selection

**Updating permissions:**

- Use **Update and install** to apply permission changes immediately

- Changes saved with **Update** alone won't affect workloads until installed

## Troubleshooting

**Workload identity not showing in service:**

Verify both project and tag restrictions are properly configured:

- Check **Project restriction** is either disabled OR includes your project

- Check **Tag restriction** is either disabled OR matches your workload's tags

- If both are enabled, the workload must satisfy BOTH rules

- If "Force matching all tags" is enabled, the workload must have ALL specified tags

### A different identity is selected

If multiple identities match, compare their [selection priority](#selection-priority). Identities from linked external addons take precedence for the same provider. Otherwise, the highest priority wins, with alphabetical order for ties.

If running containers still use a previous identity, follow the [instructions to apply the change](#apply-a-change-in-identity-selection).

## Next steps

- [Deploy node pools: Configure and deploy node pools on a Kubernetes cluster with Northflank.](/v1/application/bring-your-own-cloud/deploy-and-scale-node-pools)
- [Manage your Kubernetes cluster: Manage your clusters on other cloud providers using Northflank.](/v1/application/bring-your-own-cloud/manage-your-cluster)
- [Deploy workloads to your cluster: Deploy services, jobs, and addons to your own cluster, and configure workloads to schedule on specific node pools.](/v1/application/bring-your-own-cloud/deploy-workloads-to-your-cluster)
- [Create custom resource plans: Create custom plans for your team to deploy workloads and build code on your own clusters.](/v1/application/bring-your-own-cloud/create-custom-resource-plans)