How to Use Workload Identity Federation for the scan-plugins GitHub Action

Configure the scan-plugins action with your Anthropic federation rule ID, organization ID, and service account ID, then grant the workflow job id-token: write permissions to authenticate via OIDC instead of static API keys.

The scan-plugins action in the anthropics/claude-plugins-community repository performs automated safety scans on Claude plugin submissions using the Anthropic API. While you can authenticate with a static API key, Workload Identity Federation (WIF) eliminates long-lived secrets by exchanging GitHub's OIDC token for short-lived Anthropic credentials. This guide explains how to configure WIF using the inputs defined in .github/actions/scan-plugins/action.yml.

Prerequisites for Workload Identity Federation

Before configuring the workflow, you must set up the federation trust relationship in the Anthropic console and gather three specific identifiers.

Required Anthropic Console Configuration

1. Create a WIF rule in your Anthropic organization settings and note the rule ID (format: fdrl_XXXXXXXXXXXXXXXX).
2. Identify your Anthropic organization ID (format: org_XXXXXXXXXXXXXXXX).
3. Create or identify the service account ID (format: svac_XXXXXXXXXXXXXXXX) that the WIF rule binds to.

GitHub Workflow Permissions

The workflow job must have the id-token: write permission to mint the OIDC token required for the exchange. Without this, the action cannot retrieve the JWT from GitHub's identity provider.

Configuring the scan-plugins Action for WIF

The action.yml file defines three WIF-specific inputs that replace the static anthropic-api-key. When you provide these inputs, the action sets the internal environment variable HAS_WIF=true and invokes the Claude CLI with the --wif flag.

Required Inputs

• anthropic-federation-rule-id: The WIF rule ID from the Anthropic console (e.g., fdrl_abc123...).
• anthropic-organization-id: Your Anthropic organization UUID.
• anthropic-service-account-id: The service account UUID bound to the WIF rule.

Authentication Detection Logic

According to the implementation in .github/actions/scan-plugins/action.yml, the action checks for the presence of the federation rule ID input. If detected, it bypasses the static API key validation and configures the runtime environment to perform an OIDC token exchange. The helper functions in .github/actions/scan-plugins/lib/common.sh handle the actual token retrieval and HTTP headers for the Anthropic API request.

Complete Workflow Example

The following workflow demonstrates a complete setup using Workload Identity Federation. Notice the permissions block granting id-token: write and the absence of the anthropic-api-key input.

# .github/workflows/scan-plugins-wif.yml

name: Scan Plugins with Workload Identity Federation

on:
  push:
    paths:
      - 'plugins/**/*.json'

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for WIF

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run scan-plugins with WIF
        uses: anthropics/claude-plugins-community/.github/actions/scan-plugins@main
        with:
          anthropic-federation-rule-id: fdrl_XXXXXXXXXXXXXXXX
          anthropic-organization-id: org_XXXXXXXXXXXXXXXX
          anthropic-service-account-id: svac_XXXXXXXXXXXXXXXX

In this configuration, the action retrieves the OIDC token from GitHub's identity provider, exchanges it for a short-lived Anthropic access token via the federation rule, and executes the safety scan defined in .github/actions/scan-plugins/lib/pin-check.sh.

Fallback Behavior and Static Keys

If you provide both WIF inputs and a static anthropic-api-key, the action prioritizes Workload Identity Federation when the rule ID is present. If neither authentication method is provided, the action logs a notice and exits gracefully without performing the scan, ensuring the workflow does not fail due to missing credentials.

Troubleshooting WIF Failures

Insufficient Permissions Errors

If the workflow fails with "insufficient permissions" or "unable to fetch OIDC token", verify that the job-level permissions block includes id-token: write. This permission is distinct from contents: read and is mandatory for the GitHub Actions OIDC provider to function.

Invalid Federation Rule ID

Ensure the anthropic-federation-rule-id matches exactly the identifier shown in the Anthropic console, including the fdrl_ prefix. Mismatched IDs will cause the token exchange to fail with a 403 error from the Anthropic identity provider.

Summary

• Workload Identity Federation removes the need for static API keys by using GitHub's OIDC provider to authenticate with Anthropic.
• Three inputs are required: anthropic-federation-rule-id, anthropic-organization-id, and anthropic-service-account-id.
• Permission requirement: The workflow job must have id-token: write to mint the OIDC token.
• Implementation: The logic resides in .github/actions/scan-plugins/action.yml, with helper utilities in .github/actions/scan-plugins/lib/common.sh.
• Graceful degradation: The action skips scanning if no credentials are provided rather than failing the workflow.

Frequently Asked Questions

What inputs are required to enable Workload Identity Federation in scan-plugins?

You must provide three specific inputs defined in action.yml: anthropic-federation-rule-id (the WIF rule identifier starting with fdrl_), anthropic-organization-id (your org UUID), and anthropic-service-account-id (the service account UUID). These replace the static anthropic-api-key input.

Can I use both a static API key and Workload Identity Federation simultaneously?

Yes, but the action prioritizes WIF when the anthropic-federation-rule-id input is present. If the federation exchange fails, the action does not automatically fall back to the static key; it treats WIF as the explicit authentication method when configured.

Why does my workflow fail with "insufficient permissions" when using WIF?

This error indicates the GitHub Actions runner cannot mint an OIDC token. You must explicitly set id-token: write in the job's permissions block. Without this scope, the scan-plugins action cannot retrieve the JWT required for the Anthropic token exchange.

Where is the OIDC token exchange logic implemented in the scan-plugins action?

The detection logic and environment variable setup (HAS_WIF=true) are implemented in .github/actions/scan-plugins/action.yml. The actual token handling and API request construction utilize helper functions defined in .github/actions/scan-plugins/lib/common.sh, which prepares the authentication headers for the Anthropic API call.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}