How to secure n8n with OAuth?

To secure n8n with OAuth, you need to configure OAuth authentication providers for user login and implement OAuth access to external services. This involves setting up authentication in the n8n configuration file, configuring providers like Google or GitHub, and implementing proper security measures to protect your workflow automation platform.

 

Understanding OAuth Security for n8n

 

OAuth (Open Authorization) provides a secure way for users to log into n8n without sharing credentials directly with the application. It also enables n8n to access third-party services securely on behalf of users. Implementing OAuth in n8n involves two primary aspects:

• User authentication: Securing access to the n8n interface itself
• Service authentication: Allowing n8n to connect to external services via OAuth

Before you begin, ensure you're running n8n version 0.148.0 or later, as these versions include improved OAuth support.

 

Step 1: Understanding n8n Authentication Types

 

n8n offers several authentication methods:

• None: No authentication (not recommended for production)
• Basic: Simple username/password authentication
• JWT: JSON Web Token-based authentication
• OAuth: Authentication through external identity providers

For production environments, OAuth provides the most secure and scalable solution, allowing you to leverage existing identity management systems.

 

Step 2: Prerequisites for Setting Up OAuth

 

Before configuring OAuth, ensure you have:

• n8n installed and running (version 0.148.0 or later)
• Access to modify n8n configuration files
• An account with your chosen OAuth provider (Google, GitHub, etc.)
• A domain name and TLS/SSL certificates for secure connections
• Admin access to your server environment

 

Step 3: Creating OAuth Applications with Providers

 

For this guide, we'll cover Google and GitHub as examples. You'll need to create OAuth applications with each provider you want to use.

For Google OAuth:

1. Navigate to the Google Cloud Console (https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Go to "APIs & Services" > "Credentials"
4. Click "Create Credentials" and select "OAuth client ID"
5. Set application type to "Web application"
6. Add a name like "n8n Authentication"
7. Add authorized JavaScript origins (your n8n domain, e.g., https://n8n.yourdomain.com)
8. Add authorized redirect URIs (https://n8n.yourdomain.com/rest/oauth2/callback)
9. Click "Create" and note down your Client ID and Client Secret

For GitHub OAuth:

1. Log in to GitHub and go to Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Enter an application name (e.g., "n8n Access")
4. Set homepage URL to your n8n instance (https://n8n.yourdomain.com)
5. Set Authorization callback URL to https://n8n.yourdomain.com/rest/oauth2/callback
6. Click "Register application"
7. Generate a client secret and note down your Client ID and Client Secret

 

Step 4: Configuring n8n Environment Variables

 

n8n uses environment variables for configuration. You can set these in several ways:

• In a .env file in your n8n root directory
• Directly in your environment
• In your Docker container configuration
• Through your process manager (PM2, systemd, etc.)

Here's a comprehensive configuration for OAuth:

# Basic n8n Configuration
N8N\_HOST=n8n.yourdomain.com
N8N\_PROTOCOL=https
N8N\_PORT=5678
N8N_ENCRYPTION_KEY=your-long-secure-encryption-key

# Authentication Settings
N8N_AUTH_ENABLED=true
N8N_USER_MANAGEMENT\_DISABLED=false

# OAuth Settings
N8N_AUTH_OAUTH\_ENABLED=true
N8N_AUTH_OAUTH_AUTO_REGISTER=true
N8N_AUTH_OAUTH_LOGIN_LABEL="Login with OAuth"
N8N_AUTH_OAUTH_LOGIN_ICON="globe"

# Google OAuth Provider
N8N_AUTH_OAUTH_GOOGLE_CLIENT\_ID=your-google-client-id
N8N_AUTH_OAUTH_GOOGLE_CLIENT\_SECRET=your-google-client-secret
N8N_AUTH_OAUTH_GOOGLE_SCOPE=openid,profile,email

# GitHub OAuth Provider
N8N_AUTH_OAUTH_GITHUB_CLIENT\_ID=your-github-client-id
N8N_AUTH_OAUTH_GITHUB_CLIENT\_SECRET=your-github-client-secret
N8N_AUTH_OAUTH_GITHUB_SCOPE=user:email

# Optional - Email Domain Restrictions
N8N_AUTH_OAUTH_EMAIL_DOMAIN\_WHITELIST=yourdomain.com,anotherdomain.com

# Security Settings
N8N_SECURE_COOKIE=true
N8N_JWT_SECRET=your-very-secure-jwt-secret
N8N_HIRING_DISABLED=true
N8N_PERSONALIZATION_ENABLED=false

 

Step 5: Setting Up OAuth in n8n.config.js

 

For more complex configurations, you can use the n8n.config.js file. Create or edit this file in your n8n root directory:

module.exports = {
  // Basic n8n configuration
  host: 'n8n.yourdomain.com',
  protocol: 'https',
  port: 5678,
  
  // Security settings
  encryptionKey: 'your-long-secure-encryption-key',
  
  // Authentication
  auth: {
    enabled: true,
    oauth: {
      enabled: true,
      autoRegister: true,
      loginLabel: 'Login with OAuth',
      loginIcon: 'globe',
      
      // Google OAuth Provider
      google: {
        clientId: 'your-google-client-id',
        clientSecret: 'your-google-client-secret',
        scope: 'openid profile email',
        authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
        tokenUrl: 'https://oauth2.googleapis.com/token',
        userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
        authorizationParams: {
          access\_type: 'offline',
          prompt: 'consent',
        }
      },
      
      // GitHub OAuth Provider
      github: {
        clientId: 'your-github-client-id',
        clientSecret: 'your-github-client-secret',
        scope: 'user:email',
        authUrl: 'https://github.com/login/oauth/authorize',
        tokenUrl: 'https://github.com/login/oauth/access\_token',
        userInfoUrl: 'https://api.github.com/user'
      },
      
      // Optional custom OAuth provider
      custom: {
        clientId: 'your-custom-client-id',
        clientSecret: 'your-custom-client-secret',
        scope: 'profile email',
        authUrl: 'https://custom-provider.com/oauth/authorize',
        tokenUrl: 'https://custom-provider.com/oauth/token',
        userInfoUrl: 'https://custom-provider.com/oauth/userinfo',
        userInfoMethod: 'GET',
        userInfoFields: {
          email: 'email',
          id: 'id',
          firstName: 'given\_name',
          lastName: 'family\_name',
        }
      }
    }
  },
  
  // Email domain restrictions
  deployment: {
    security: {
      oauth: {
        emailDomainWhitelist: ['yourdomain.com', 'anotherdomain.com']
      }
    }
  }
};

 

Step 6: Setting Up SSL/TLS for Secure Communication

 

OAuth requires secure HTTPS connections. If you're running n8n directly, configure it behind a reverse proxy like Nginx or Apache with SSL certificates:

Example Nginx configuration:

server {
    listen 80;
    server\_name n8n.yourdomain.com;
    return 301 https://$host$request\_uri;
}

server {
    listen 443 ssl;
    server\_name n8n.yourdomain.com;
    
    ssl\_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    ssl\_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server\_ciphers on;
    ssl\_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    
    location / {
        proxy\_pass http://localhost:5678;
        proxy_set_header X-Real-IP $remote\_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http\_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

For Docker-based deployments, you can use Traefik, Caddy, or other proxy solutions with automatic SSL certificate management.

 

Step 7: Starting n8n with OAuth Enabled

 

With your configuration in place, start or restart n8n to apply the changes:

For direct installation:

# If using environment variables
n8n start

# If using PM2
pm2 restart n8n

For Docker:

docker-compose down
docker-compose up -d

 

Step 8: Testing OAuth Login

 

Access your n8n instance at https://n8n.yourdomain.com. You should now see OAuth login options alongside any other authentication methods you've configured.

1. Click on the OAuth login button
2. You'll be redirected to the provider's login page
3. Authenticate with your credentials
4. Grant permissions to n8n
5. You'll be redirected back to n8n and logged in

If auto-registration is enabled, new users will be automatically created on their first login. Otherwise, only existing users will be able to log in.

 

Step 9: User Management with OAuth

 

n8n provides several options for user management with OAuth:

Auto-Registration:

If enabled, new users are automatically created when they first log in via OAuth. Control this with:

N8N_AUTH_OAUTH_AUTO_REGISTER=true

Email Domain Restrictions:

Limit OAuth logins to specific email domains:

N8N_AUTH_OAUTH_EMAIL_DOMAIN\_WHITELIST=yourdomain.com,anotherdomain.com

Default User Role:

Set the default role for new OAuth users:

N8N_AUTH_OAUTH_DEFAULT_ROLE=editor

Available roles include:

• owner
• admin
• member
• editor (default)
• user

 

Step 10: Setting Up OAuth for n8n Credential Authentication

 

Besides user login, OAuth is commonly used for n8n to authenticate with third-party services. This requires separate configuration for each service:

1. Navigate to Credentials in the n8n interface
2. Click "Create New"
3. Select the service you want to connect to
4. Choose "OAuth2" as the authentication type
5. Configure the required fields:

• OAuth Provider
• Client ID
• Client Secret
• Authorization URL
• Token URL
• Scope

Some services have pre-configured OAuth templates in n8n, while others require manual configuration.

 

Step 11: Advanced OAuth Configurations

 

Custom Claims Mapping:

If your OAuth provider returns custom claims or different field names, map them to n8n user fields:

N8N_AUTH_OAUTH_CUSTOM_USER_INFO_FIELDS={"email":"user_email","firstName":"given_name","lastName":"family\_name"}

Custom OAuth Provider:

For providers not directly supported by n8n:

N8N_AUTH_OAUTH_CUSTOM_CLIENT\_ID=your-client-id
N8N_AUTH_OAUTH_CUSTOM_CLIENT\_SECRET=your-client-secret
N8N_AUTH_OAUTH_CUSTOM_AUTH\_URL=https://custom-provider.com/oauth/authorize
N8N_AUTH_OAUTH_CUSTOM_TOKEN\_URL=https://custom-provider.com/oauth/token
N8N_AUTH_OAUTH_CUSTOM_USER_INFO_URL=https://custom-provider.com/oauth/userinfo
N8N_AUTH_OAUTH_CUSTOM_USER_INFO_METHOD=GET
N8N_AUTH_OAUTH_CUSTOM_SCOPE=profile,email

PKCE Support:

For enhanced security, enable PKCE (Proof Key for Code Exchange):

N8N_AUTH_OAUTH_CUSTOM_PKCE\_ENABLED=true

 

Step 12: Troubleshooting OAuth Issues

 

If you encounter problems with OAuth configuration, here are common troubleshooting steps:

Callback URL Issues:

Ensure the callback URL in your OAuth provider matches exactly what n8n expects:

• Default: https://your-n8n-domain.com/rest/oauth2/callback
• Check for trailing slashes or protocol mismatches

SSL Certificate Problems:

OAuth requires valid SSL certificates. If using self-signed certificates:

NODE_TLS_REJECT\_UNAUTHORIZED=0 # Only for development/testing!

Debugging OAuth Flow:

Enable verbose logging:

N8N_LOG_LEVEL=debug

Common Error Solutions:

• "Invalid redirect_uri": Check the exact callback URL in your OAuth provider settings
• "Client authentication failed": Verify client ID and secret
• "Access denied": Check scopes and permissions
• "State mismatch": Ensure cookies are being properly set and stored

 

Step 13: Security Best Practices for n8n OAuth

 

To maximize security when using OAuth with n8n:

• Use strong, unique encryption keys and JWT secrets
• Keep client secrets secure and never expose them in client-side code
• Enable secure cookies and HTTPS-only access
• Implement IP restrictions if possible
• Regularly rotate client secrets
• Use the principle of least privilege when granting scopes
• Implement PKCE for public clients
• Consider rate limiting for failed login attempts
• Use email domain restrictions for enterprise deployments
• Regularly audit user access and permissions

Configuration example for enhanced security:

N8N_SECURE_COOKIE=true
N8N_SSL_CERT=/path/to/cert.pem
N8N_SSL_KEY=/path/to/key.pem
N8N_ENCRYPTION_KEY=your-very-strong-encryption-key
N8N_JWT_SECRET=your-very-strong-jwt-secret
N8N_AUTH_OAUTH_EMAIL_DOMAIN\_WHITELIST=yourdomain.com

 

Step 14: Setting Up n8n Behind an Identity-Aware Proxy

 

For enterprise environments, you might want to implement an additional security layer using an Identity-Aware Proxy (IAP) like Google Cloud IAP, Cloudflare Access, or Auth0:

1. Set up your chosen IAP service
2. Configure the IAP to protect your n8n instance
3. Set up OAuth in the IAP configuration
4. Configure n8n to trust the authentication headers from your IAP

Example for Google Cloud IAP:

N8N_AUTH_IAP\_ENABLED=true
N8N_AUTH_IAP\_HEADER=x-goog-iap-jwt-assertion
N8N_AUTH_IAP_JWT_SECRET=your-iap-jwt-secret

 

Step 15: Implementing Multi-Factor Authentication

 

While n8n doesn't directly support MFA, you can implement it through your OAuth provider:

1. Enable MFA in your OAuth provider (Google, GitHub, etc.)
2. Users will be prompted for MFA during the OAuth login process
3. n8n will receive the authentication after MFA is completed

This provides an additional security layer without requiring changes to n8n itself.

 

Conclusion

 

Securing n8n with OAuth provides a robust authentication mechanism for both user access and service connections. By following this guide, you've implemented industry-standard security practices for your workflow automation platform. Keep your configurations updated, regularly review security settings, and stay informed about n8n updates to maintain a secure environment.

Remember that security is an ongoing process. Regularly audit your n8n instance, keep all components updated, and follow security best practices to protect your automation workflows and sensitive data.