npm package: @general-dexterity/n8n-nodes-jwt-auth
Description: JWT authentication nodes for n8n workflows - verify signatures and validate claims
Author: Aliou Diallo
Latest version: 0.2.0

# n8n JWT Authentication Nodes

Comprehensive JWT (JSON Web Token) nodes for n8n workflows. Sign, decode, verify, and validate JWT tokens with support for JWKS (JSON Web Key Set) endpoints.

![n8n](https://img.shields.io/badge/n8n-compatible-brightgreen.svg)
![License](https://img.shields.io/npm/l/@general-dexterity/n8n-nodes-jwt-auth)
![Version](https://img.shields.io/npm/v/@general-dexterity/n8n-nodes-jwt-auth)

## Features

- 🔐 **Complete JWT Operations**: Sign, Decode, Verify, and Validate tokens
- 🔑 **JWKS Support**: Automatic key fetching from JWKS endpoints
- ✅ **Comprehensive Validation**: Claims, expiration, audience, issuer checks
- 🎯 **Dual Outputs**: Separate success/error paths for better workflow control
- 🔧 **Flexible Configuration**: Multiple token sources and extraction methods
- 🛡️ **Security First**: Clear separation between verification and validation

## Installation

### In n8n

1. Go to **Settings** > **Community Nodes**
2. Search for `@general-dexterity/n8n-nodes-jwt-auth`
3. Click **Install**

### Manual Installation

```bash
npm install -g @general-dexterity/n8n-nodes-jwt-auth
```

### Docker

Add to your `docker-compose.yml`:

```yaml
services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
    volumes:
      - ./n8n-nodes-jwt-auth:/home/node/.n8n/custom/node_modules/@general-dexterity/n8n-nodes-jwt-auth
```

## Nodes Included

### 🔐 JWT Auth
All-in-one node for JWT operations:
- **Sign**: Create and sign new tokens
- **Decode**: Parse tokens without verification
- **Verify**: Verify signature using JWKS
- **Validate**: Check structure and claims

[📖 Full Documentation](docs/nodes/JwtAuth.md)

### ✅ JWT Auth Verify
Dedicated node for JWT signature verification using JWKS endpoints.

[📖 Full Documentation](docs/nodes/JwtAuthVerify.md)

### 🔍 JWT Auth Validate
Validate JWT structure and claims without signature verification.

[📖 Full Documentation](docs/nodes/JwtAuthValidate.md)

## Credentials

### 🔑 JWT Auth JWKS
Configure JWKS endpoints for token verification.

[📖 Full Documentation](docs/credentials/JwtAuthJwks.md)

### 🗝️ JWT Auth Key
Store signing keys for creating JWT tokens.

[📖 Full Documentation](docs/credentials/JwtAuthKey.md)

## Quick Start

### Verify Incoming JWT Tokens

1. **Add Webhook Trigger**
2. **Add JWT Auth node**
   - Operation: `Verify`
   - Token Source: `Authorization Header`
3. **Configure JWKS credential**
   - JWKS URL: `https://your-provider/.well-known/jwks.json`
   - Expected Issuer: `https://your-provider`
   - Expected Audience: `your-api`
4. **Handle outputs**
   - Success → Continue processing
   - Error → Return 401 Unauthorized

### Create Signed Tokens

1. **Add JWT Auth node**
   - Operation: `Sign`
2. **Configure JWT Auth Key credential**
   - Key Type: `PEM Key` or `Passphrase`
   - Algorithm: `RS256` or `HS256`
3. **Set payload**
   - Use JSON or individual claims
   - Set expiration time
4. **Use generated token in HTTP requests**

## Common JWKS Endpoints

| Provider | JWKS URL Format |
|----------|-----------------|
| Auth0 | `https://{domain}.auth0.com/.well-known/jwks.json` |
| Okta | `https://{domain}.okta.com/oauth2/default/v1/keys` |
| AWS Cognito | `https://cognito-idp.{region}.amazonaws.com/{poolId}/.well-known/jwks.json` |
| Azure AD | `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys` |
| Google | `https://www.googleapis.com/oauth2/v3/certs` |

## Token Extraction Methods

### Authorization Header
```
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```

### JSON Field
```json
{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "data": "..."
}
```
Supports dot notation: `body.token`, `data.auth.jwt`

### Raw String
Direct token input for testing or when already extracted.

## Workflow Examples

### API Authentication Flow
```
Webhook → JWT Auth (Verify) → Process Request
                ↓ (Error)
         Return 401 Response
```

### Token Generation for External API
```
Trigger → Get User Data → JWT Auth (Sign) → HTTP Request with Token
```

### Token Inspection
```
Webhook → JWT Auth (Decode) → Analyze Claims → Route Based on Role
```

## Testing

A complete Docker-based testing environment is provided:

```bash
cd tests
docker-compose up -d
```

This includes:
- n8n instance with the JWT nodes
- Mock JWKS server for testing
- Example workflows
- Token generation scripts

[📖 Testing Documentation](tests/README.md)

## Security Considerations

- ⚠️ **Never use Decode for authentication** - it doesn't verify signatures
- ⚠️ **Validate doesn't check signatures** - use only when appropriate  
- ✅ **Always use Verify for production authentication**
- 🔒 Keep signing keys secure in n8n credentials
- 🔄 Regularly rotate signing keys
- 🔐 Use HTTPS for all JWKS endpoints

## Development

### Building from Source

```bash
# Install dependencies
pnpm install

# Build the nodes
pnpm build

# Run tests
pnpm test
```

### Project Structure
```
├── credentials/       # Credential types
├── nodes/            # Node implementations
├── docs/             # Documentation
├── tests/            # Test environment
└── assets/           # Icons and images
```

## Support

- 🐛 [Report Issues](https://github.com/general-dexterity/n8n-nodes-jwt/issues)
- 💡 [Request Features](https://github.com/general-dexterity/n8n-nodes-jwt/issues)
- 📖 [Documentation](https://github.com/general-dexterity/n8n-nodes-jwt/tree/main/docs)
- 💬 [Discussions](https://github.com/general-dexterity/n8n-nodes-jwt/discussions)

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT - see [LICENSE](LICENSE.md) file for details.

## Acknowledgments

- Built for [n8n](https://n8n.io) workflow automation platform
- Uses [jose](https://github.com/panva/jose) for JWT operations
- Icons from [Phosphor](https://phosphoricons.com/)