# 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

To create a workload identity:

1. Navigate to [**Cloud** → **Workload identities**](https://app.northflank.com/s/team/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 the cloud provider (AWS or GCP)

### 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 permissions for an existing workload identity:

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

2. Select the workload identity

3. Update the permission details

4. Choose how to save:
  
  
  - Click **Update** to save changes without applying them immediately
  
  - Click **Update and install** to save and apply changes immediately

**When to use "Update and install":**

- Required when you change permissions (IAM policy document or permissions list)

- Not needed when only changing project or tag restrictions

When you update and install, Northflank creates or updates these resources in your cloud environment:

- IAM role

- IAM role policy

**Note:** If you only click **Update** after changing permissions, changes are saved but not applied to workloads until you install later.

## View active workload identities

To see which workload identities are being used by a service or job:

1. Navigate to your service or job

2. Click **Workload identities** in the sidebar

The page displays:

- Active workload identity name and description

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

- Provider integration link

- Creation date

**Note:** If multiple workload identities match a workload (via project and tag rules), only one identity per cloud provider will be used. Northflank selects the first one alphabetically by name. For example, if both `aws-prod` and `aws-s3-access` match, `aws-prod` will be used.

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

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