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.

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.

To create a workload identity:

1. Navigate to Cloud → Workload identities

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

When you select a provider link, you'll be prompted to install the OIDC provider if this is the first workload identity for this integration. This is a one-time operation.

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

Configure the permissions the workload identity will have in your cloud account.

For AWS:

Provide an IAM policy document:

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

For GCP:

Provide a list of permissions:

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

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.

To change permissions for an existing workload identity:

1. Navigate to 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.

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.

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:

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

4. Click Create and install

Application code:

The AWS SDK automatically uses the injected credentials:

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.

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

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