n8n Google Cloud Identity Token Credential

Custom n8n credential for authenticating to Google Cloud services that require Identity Tokens (such as Cloud Run and Cloud Functions).

Why This Credential?

The Problem

The default Google Cloud credential in n8n generates Access Tokens, which are used to access Google APIs like Cloud Storage, BigQuery, etc. However, some Google Cloud services require Identity Tokens for authentication:

• Cloud Run services with authentication enabled
• Cloud Functions with authentication enabled
• Custom backends deployed on GCP that verify identity

Access Token vs Identity Token

| Feature | Access Token | Identity Token | |---------|-------------|----------------| | Purpose | Access Google APIs | Prove identity to a service | | Contains | OAuth scopes | Audience (aud claim) | | Verified by | Google servers | Target service | | Format | Opaque or JWT | Always JWT | | Use case | Call GCP APIs | Call your protected services |

The Solution

This credential generates proper Identity Tokens using your service account, allowing n8n to authenticate to services that require them.

Features

• ✅ Generates Google Cloud Identity Tokens
• ✅ Automatically adds Authorization: Bearer <token> header
• ✅ Works with n8n HTTP Request nodes
• ✅ Two versions available: standard and cached
• ✅ Supports any service account
• ✅ Compatible with Cloud Run, Cloud Functions, and custom services

Installation

Method 1: npm Installation (Recommended) 🚀

Install as a community node package:

# For global n8n installation
npm install -g n8n-credentials-google-identity-token

# For local n8n installation
npm install n8n-credentials-google-identity-token

# Then restart n8n
n8n start

With Docker:

# docker-compose.yml
version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_COMMUNITY_PACKAGES=n8n-credentials-google-identity-token
    volumes:
      - n8n_data:/home/node/.n8n

Or use environment variable:

docker run -it --rm \
  -e N8N_COMMUNITY_PACKAGES=n8n-credentials-google-identity-token \
  -p 5678:5678 \
  n8nio/n8n

Via n8n Interface:

1. Go to Settings → Community Nodes
2. Click Install
3. Enter: n8n-credentials-google-identity-token
4. Click Install

📚 Detailed installation guide: See INSTALL_COMMUNITY_NODE.md for complete instructions and troubleshooting.

Method 2: Manual Installation

1. Copy the credential file to your n8n custom directory:

   # Create credentials directory if it doesn't exist
   mkdir -p ~/.n8n/custom/credentials
   
   # Copy the credential file
   cp credentials/GoogleCloudIdentityToken.credentials.ts ~/.n8n/custom/credentials/

2. Restart n8n:

   # If running locally
   n8n restart
   
   # If using Docker
   docker restart <n8n-container-name>

3. Verify installation:

   • Open n8n interface
   • The credential should appear in the credentials list

Method 3: Using install.sh Script

# Install to default location
./install.sh

# Or specify custom path
./install.sh /path/to/n8n/custom

Configuration

Step 1: Create a Service Account

1. Go to Google Cloud Console
2. Navigate to IAM & Admin → Service Accounts
3. Click Create Service Account
4. Give it a name and description
5. Grant necessary permissions (see Permissions section)
6. Click Create Key → JSON
7. Save the JSON file securely

Step 2: Configure in n8n

1. Open n8n and go to Settings → Credentials
2. Click Add Credential
3. Search for Google Cloud Identity Token
4. Fill in the fields:
   • Service Account JSON: Paste the entire content of your JSON key file
   • Target Audience: The URL of the service you want to call (e.g., https://your-service-xyz.run.app)
5. Click Save

Step 3: Use in HTTP Request Node

1. Add an HTTP Request node to your workflow
2. Set the URL to your protected service
3. In Authentication → Predefined Credential Type
4. Select Google Cloud Identity Token
5. Choose your configured credential
6. The credential will automatically add the Authorization: Bearer <identity-token> header

Usage Examples

Example 1: Call a Protected Cloud Run Service

1. HTTP Request node:
   - Method: GET
   - URL: https://my-service-xyz.run.app/api/data
   - Authentication: Google Cloud Identity Token
   - Credential: [Your configured credential]

2. Target Audience in credential: https://my-service-xyz.run.app

Example 2: Invoke a Cloud Function

1. HTTP Request node:
   - Method: POST
   - URL: https://us-central1-myproject.cloudfunctions.net/myfunction
   - Authentication: Google Cloud Identity Token
   - Credential: [Your configured credential]

2. Target Audience: https://us-central1-myproject.cloudfunctions.net/myfunction

Example 3: Multiple Services

If you need to call multiple protected services, create separate credentials for each with different target audiences:

• Credential 1: Target Audience = https://service-a.run.app
• Credential 2: Target Audience = https://service-b.run.app
• Credential 3: Target Audience = https://us-central1-project.cloudfunctions.net/func

Permissions

Your service account needs the following IAM role to invoke protected services:

For Cloud Run:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/run.invoker"

For Cloud Functions:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/cloudfunctions.invoker"

Verify Permissions:

# Test with gcloud
gcloud auth print-identity-token \
  --audiences=https://your-service.run.app \
  --impersonate-service-account=your-sa@project.iam.gserviceaccount.com

Troubleshooting

Error: "Invalid JWT Signature"

Cause: The service account JSON is malformed or incomplete.

Solution:

• Ensure you copied the entire JSON content
• Check for no extra spaces or characters
• Try generating a new key from Google Cloud Console

Error: "Permission denied"

Cause: Service account doesn't have invoker permission.

Solution:

# Grant the role
gcloud run services add-iam-policy-binding SERVICE_NAME \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/run.invoker"

Error: "Invalid audience"

Cause: Target audience doesn't match the service URL.

Solution:

• Verify the Target Audience matches exactly
• For Cloud Run: use the full service URL
• Don't include trailing slashes or paths in most cases

Token Not Working

Symptoms: 401 Unauthorized or 403 Forbidden

Debug steps:

1. Test with gcloud CLI:

   TOKEN=$(gcloud auth print-identity-token \
     --audiences=https://your-service.run.app)
   
   curl -H "Authorization: Bearer $TOKEN" \
     https://your-service.run.app

2. Decode the token to check claims:

   echo $TOKEN | cut -d. -f2 | base64 -d | jq

3. Verify the aud claim matches your service URL

Cached Version Not Updating

Issue: Using v2 credential and tokens seem stale.

Solution:

• Disable cache temporarily
• Restart n8n to clear in-memory cache
• Switch to standard version for testing

Versions

This package includes two versions:

Standard Version (GoogleCloudIdentityToken.credentials.ts)

• Generates a fresh token for every request
• No caching
• Best for low-volume workflows or testing

Cached Version (GoogleCloudIdentityToken.credentials.v2.ts)

• Caches tokens for 50 minutes
• Reduces API calls to Google OAuth
• Best for high-volume workflows
• Can be disabled per credential

See VERSIONS.md for detailed comparison.

Security Considerations

• Never commit service account keys to version control
• Store JSON keys securely (use n8n's encrypted credential storage)
• Follow the principle of least privilege (grant only necessary roles)
• Rotate service account keys regularly
• Monitor service account usage in Google Cloud Console
• Use separate service accounts for different environments (dev/staging/prod)

Architecture

How It Works

┌─────────┐                ┌──────────────┐                ┌─────────────┐
│  n8n    │   1. Create    │  This        │   2. Request   │   Google    │
│  HTTP   │──────JWT────▶  │  Credential  │──────token───▶ │   OAuth     │
│ Request │                │              │                │   Server    │
└─────────┘                └──────────────┘                └─────────────┘
     │                            │                               │
     │                            │     3. Receive Identity Token │
     │                            │◀──────────────────────────────┘
     │                            │
     │    4. Add Authorization    │
     │◀───────header──────────────┘
     │
     │     5. Make authenticated request
     └──────────────────────────────────────▶ Protected Service

Token Generation Flow

1. n8n calls authenticate() method
2. Credential creates a JWT with:
   • iss and sub: service account email
   • aud: Google OAuth endpoint
   • target_audience: your service URL
3. JWT is signed with service account private key
4. JWT is exchanged for Identity Token via Google OAuth
5. Identity Token is added to Authorization: Bearer <token> header
6. n8n makes the HTTP request with this header

Identity Token Structure

{
  "iss": "https://accounts.google.com",
  "sub": "103584029384756284756",
  "aud": "https://your-service.run.app",
  "iat": 1234567890,
  "exp": 1234571490,
  "email": "[email protected]",
  "email_verified": true
}

FAQ

Q: Can I use this with the default Google Cloud credential? A: No, they serve different purposes. Use this for Identity Tokens, the default one for Access Tokens to Google APIs.

Q: How long do Identity Tokens last? A: Tokens are valid for 1 hour. The credential generates them on-demand.

Q: Does this work with Cloud Storage or BigQuery? A: No, those services require Access Tokens. Use the default Google Cloud credential for those.

Q: Can I use this outside of n8n? A: This is specifically built for n8n, but the logic can be adapted for other use cases.

Q: Is the cached version safe? A: Yes, tokens are cached in-memory only and expire after 50 minutes. The cache is cleared when n8n restarts.

Q: Can I use this with Workload Identity? A: Not directly. This requires a service account JSON key. For Workload Identity, you'd need a different approach.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

• Google Cloud Identity Token Documentation
• n8n Custom Credentials Documentation
• Service Account Keys

License

MIT License - see LICENSE file for details.

Related Resources

• INSTALL_COMMUNITY_NODE.md - Complete installation guide for community nodes
• QUICKSTART.md - Get started in 3 steps
• EXAMPLES.md - Real-world usage examples
• VERSIONS.md - Compare standard vs cached versions
• PROJECT.md - Project overview and architecture

Changelog

v1.0.0 (Initial Release)

• Standard credential implementation
• Cached credential implementation (v2)
• Complete documentation
• Installation scripts
• Examples and troubleshooting guides