npm package: @okjavis/nodebb-plugin-javis-sso
Description: Unified OAuth 2.0 / OpenID Connect SSO plugin for NodeBB with enterprise-grade security
Author: Chirag Dugar
Latest version: 1.1.0

# 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

```bash
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](https://www.linkedin.com/developers/apps)
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:**
```bash
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](https://console.developers.google.com/)
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:**
```bash
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](https://github.com/settings/developers)
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:**
```bash
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](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps)
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:**
```bash
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:**
```bash
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**
   ```bash
   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](https://github.com/javis-admin/nodebb-plugin-javis-sso/issues)
- **Security**: See [SECURITY.md](SECURITY.md)
- **NodeBB Community**: [NodeBB Community Forums](https://community.nodebb.org)

---

## 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](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](https://nodebb.org) - Modern forum software
- [Passport.js](http://www.passportjs.org/) - Authentication middleware
- [OAuth 2.0](https://oauth.net/2/) - Industry-standard protocol

---

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