JAVIS SSO - Unified OAuth Authentication for NodeBB

Enterprise-grade unified Single Sign-On plugin for NodeBB with support for LinkedIn, Google, GitHub, Microsoft, and custom OAuth2/OIDC providers.

Features

• 5 OAuth Providers: LinkedIn, Google, GitHub, Microsoft, and Generic OAuth2/OIDC
• Enterprise Security: Input validation, HTTPS enforcement, secure credential storage
• Easy Configuration: Multi-tab admin interface with clear setup instructions
• Flexible Authentication: Support for any OAuth2/OIDC provider via generic configuration
• Auto Account Linking: Automatically links accounts via email matching
• Profile Sync: Imports profile pictures and basic information
• Environment Variables: Secure credential management via environment variables
• Deauth Support: Users can disconnect OAuth providers from their accounts

Requirements

• NodeBB v3.0.0 or higher
• HTTPS enabled (required in production)
• OAuth2 credentials from your chosen providers

Installation

Via npm

npm install nodebb-plugin-javis-sso

Via NodeBB Admin Panel

1. Navigate to Admin Control Panel → Extend → Plugins
2. Search for "nodebb-plugin-javis-sso"
3. Click Install
4. Activate the plugin
5. Rebuild and restart NodeBB

Configuration

Quick Start

1. Navigate to Admin Control Panel → Plugins → JAVIS SSO
2. Select the provider tab you want to configure
3. Enable the provider
4. Enter your OAuth credentials
5. Copy the callback URL to your OAuth app settings
6. Save settings
7. Rebuild and restart NodeBB

Provider Setup Guides

LinkedIn

1. Create LinkedIn OAuth App

1. Go to LinkedIn Developers
2. Click "Create app"
3. Fill in application details:
   • App name: Your NodeBB Forum Name
   • LinkedIn Page: Your company page (or create one)
   • App logo: Your forum logo
4. In "Auth" tab:
   • Add redirect URL: https://yourdomain.com/auth/linkedin/callback
   • Request OAuth 2.0 scopes: openid, profile, email
5. Copy your Client ID and Client Secret

2. Configure in NodeBB

Via Admin Panel:

• Navigate to JAVIS SSO settings → LinkedIn tab
• Enable LinkedIn SSO
• Enter Client ID and Client Secret
• Save settings

Via Environment Variables:

export LINKEDIN_CLIENT_ID="your_client_id"
export LINKEDIN_CLIENT_SECRET="your_client_secret"

Google

1. Create Google OAuth App

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable Google+ API
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
5. Application type: "Web application"
6. Add authorized redirect URI: https://yourdomain.com/auth/google/callback
7. Copy your Client ID and Client Secret

2. Configure in NodeBB

Via Admin Panel:

• Navigate to JAVIS SSO settings → Google tab
• Enable Google SSO
• Enter Client ID and Client Secret
• Save settings

Via Environment Variables:

export GOOGLE_CLIENT_ID="your_client_id"
export GOOGLE_CLIENT_SECRET="your_client_secret"

GitHub

1. Create GitHub OAuth App

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in application details:
   • Application name: Your NodeBB Forum Name
   • Homepage URL: https://yourdomain.com
   • Authorization callback URL: https://yourdomain.com/auth/github/callback
4. Copy your Client ID and Client Secret

2. Configure in NodeBB

Via Admin Panel:

• Navigate to JAVIS SSO settings → GitHub tab
• Enable GitHub SSO
• Enter Client ID and Client Secret
• Save settings

Via Environment Variables:

export GITHUB_CLIENT_ID="your_client_id"
export GITHUB_CLIENT_SECRET="your_client_secret"

Microsoft / Azure AD

1. Create Microsoft OAuth App

1. Go to Azure Portal
2. Click "New registration"
3. Fill in application details:
   • Name: Your NodeBB Forum Name
   • Supported account types: Choose based on your needs
   • Redirect URI: Web → https://yourdomain.com/auth/microsoft/callback
4. In "Certificates & secrets", create a new client secret
5. Copy your Application (client) ID and Client Secret

2. Configure in NodeBB

Via Admin Panel:

• Navigate to JAVIS SSO settings → Microsoft tab
• Enable Microsoft SSO
• Enter Application ID as Client ID
• Enter Client Secret
• Save settings

Via Environment Variables:

export MICROSOFT_CLIENT_ID="your_application_id"
export MICROSOFT_CLIENT_SECRET="your_client_secret"

Generic OAuth2 / OIDC

Use this for Okta, Auth0, Keycloak, or any custom OAuth2/OIDC provider.

1. Gather Provider Information

You'll need:

• Authorization URL (e.g., https://provider.com/oauth/authorize)
• Token URL (e.g., https://provider.com/oauth/token)
• User Info URL (e.g., https://provider.com/oauth/userinfo)
• Client ID
• Client Secret
• Scopes (usually openid profile email)

2. Configure in NodeBB

Via Admin Panel:

• Navigate to JAVIS SSO settings → Generic OAuth2 tab
• Enable Generic OAuth2
• Enter all URLs and credentials
• Specify scopes (space-separated)
• Save settings

Via Environment Variables:

export GENERIC_CLIENT_ID="your_client_id"
export GENERIC_CLIENT_SECRET="your_client_secret"

Security Best Practices

Production Requirements

1. HTTPS is Mandatory

   • The plugin enforces HTTPS in production
   • OAuth 2.0 over HTTP is insecure and will be blocked

2. Use Environment Variables

   • Store credentials in environment variables, not the database
   • Environment variables take precedence over admin panel settings

3. Regular Updates

   npm audit
   npm update nodebb-plugin-javis-sso

Recommended Settings

• Auto-confirm Email: Only enable if you trust the OAuth provider's email verification
• Rate Limiting: Configure rate limiting on your NodeBB instance
• Database Security: Ensure your NodeBB database has proper access controls

Usage

For End Users

Once configured, users will see OAuth login buttons on the login and registration pages:

• "Sign in with LinkedIn"
• "Sign in with Google"
• "Sign in with GitHub"
• "Sign in with Microsoft"

Linking Accounts

Users can link OAuth providers to existing accounts:

1. Log in to NodeBB with existing credentials
2. Go to Settings → Account
3. Click "Connect" next to the OAuth provider
4. Complete OAuth flow

Unlinking Accounts

Users can disconnect OAuth providers:

1. Go to Settings → Account
2. Click "Disconnect" next to the OAuth provider

Troubleshooting

"HTTPS is required in production"

Solution: Ensure your NodeBB is configured with HTTPS

• Update config.json to use https:// in the URL
• Set NODE_ENV=production only when HTTPS is configured

"Client ID or Secret not configured"

Solution: Either:

• Configure credentials in the admin panel, or
• Set environment variables for the provider

"OAuth callback error"

Solutions:

1. Verify callback URL in provider settings matches NodeBB URL
2. Ensure callback URL includes correct protocol (https://)
3. Check that NodeBB is accessible from the internet
4. Review NodeBB logs for specific error messages

"No email returned from provider"

Solution:

• Check that email scope is requested
• For GitHub: User's email may be private (plugin handles this)
• Some providers require additional permissions for email access

Users can't link accounts

Solutions:

1. Verify user's email in NodeBB matches OAuth provider email
2. Ensure user is logged in before attempting to link
3. Check server logs for specific errors

Advanced Configuration

Multiple Providers

Enable as many providers as needed. Users can link multiple OAuth providers to a single NodeBB account.

Email Auto-Confirmation

When enabled, users who sign up via OAuth will have their email automatically confirmed, bypassing email verification.

Security Note: Only enable this if you trust the OAuth provider's email verification process.

Custom OAuth2 Providers

The Generic OAuth2 provider supports any standard OAuth2 or OpenID Connect provider:

• Okta: Use your Okta domain OAuth endpoints
• Auth0: Use your Auth0 tenant OAuth endpoints
• Keycloak: Use your Keycloak realm OAuth endpoints
• Custom: Any OAuth2-compliant identity provider

Development

Project Structure

nodebb-plugin-javis-sso/
├── lib/
│   ├── providers/          # OAuth provider implementations
│   │   ├── base.js        # Base provider class
│   │   ├── linkedin.js
│   │   ├── google.js
│   │   ├── github.js
│   │   ├── microsoft.js
│   │   └── generic.js
│   ├── security/          # Security utilities
│   │   ├── validation.js  # Input validation & sanitization
│   │   ├── https-check.js # HTTPS enforcement
│   │   └── logger.js      # Secure logging
│   ├── user-manager.js    # User operations
│   ├── settings-manager.js # Settings management
│   └── strategy-builder.js # OAuth strategy factory
├── static/                # Frontend assets
│   ├── lib/admin.js      # Admin panel JS
│   └── templates/        # Admin templates
├── library.js            # Main plugin entry
├── plugin.json           # NodeBB plugin metadata
└── package.json          # NPM package config

Adding a New Provider

1. Create a new provider class in lib/providers/
2. Extend BaseProvider
3. Define provider configuration (URLs, scopes, field mapping)
4. Add to lib/providers/index.js
5. Update library.js to include provider ID
6. Add tab to admin template
7. Update documentation

Support

• Issues: GitHub Issues
• Security: See SECURITY.md
• NodeBB Community: NodeBB Community Forums

Changelog

1.0.0 (Initial Release)

Features:

• LinkedIn OAuth 2.0 / OpenID Connect
• Google OAuth 2.0 / OpenID Connect
• GitHub OAuth 2.0
• Microsoft / Azure AD OAuth 2.0
• Generic OAuth2/OIDC provider support
• Multi-tab admin configuration interface
• Environment variable support for all providers
• Enterprise-grade security (input validation, HTTPS enforcement)
• Account linking via email matching
• Profile picture import
• Deauth endpoints for all providers

Security:

• Input validation and sanitization for all user data
• HTTPS enforcement in production
• Secure credential storage with environment variable precedence
• Sensitive data redaction in logs
• SQL injection protection via parameterized queries
• XSS protection via input sanitization

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - See LICENSE file for details

Credits

Developed by the JAVIS Team

Built with security best practices and inspired by the NodeBB plugin ecosystem.

Related Projects

• NodeBB - Modern forum software
• Passport.js - Authentication middleware
• OAuth 2.0 - Industry-standard protocol

Ready to enhance your NodeBB forum with unified OAuth authentication? Install JAVIS SSO today!