🔐 VK ID Authentication for Discourse

🌍 Languages / Языки

---

OAuth 2.1 authentication plugin with VK ID, OK.ru, and Mail.ru support

Features • Installation • Configuration • Migration • Documentation

---

🆕 What's New in Version 2.0

Complete rewrite for VK ID (id.vk.ru):

Feature	Status
🔒 OAuth 2.1 with mandatory PKCE	✅
🆔 VK ID endpoints (id.vk.ru)	✅
🎨 OneTap widget (VK ID SDK)	✅
🔄 Automatic user migration	✅
🌐 Multi-provider (VK/OK/Mail.ru)	✅
📱 Mobile responsive	✅
🌙 Dark theme support	✅
🧪 Test coverage (~150 tests)	✅
📖 Bilingual docs (EN/RU)	✅

---

⚡ Features

🔐 Security OAuth 2.1 with PKCE Authorization code interception protection Email verification via id_token No permanent token storage Comprehensive error handling	🎨 User Experience OneTap widget in login modal Multi-provider support: 🔵 VK ID 🟠 OK.ru 🔵 Mail.ru One-click authentication Auto-migration from old provider
🛠️ Developer Tools Custom OmniAuth strategy Rake migration tasks Comprehensive test suite Detailed logging TypeScript-ready	📚 Documentation Complete setup guide Migration documentation API reference Troubleshooting guide Code examples

---

📋 Requirements

Component	Version
	2.7.0 or higher
	2.7+
	Application registered at id.vk.ru
	VK ID demo at id.vk.ru

---

🚀 Installation

Step 1: Install Plugin

Follow the Install a Plugin guide using:

cd /var/discourse
nano containers/app.yml

Add to hooks.after_code:

- git clone https://github.com/kaktaknet/discourse-vkid-oauth.git

git@github.com:kaktaknet/discourse-vkid-oauth.git

Step 2: Rebuild Container

cd /var/discourse
./launcher rebuild app

---

⚙️ Configuration

1. Create VK ID Application

1. Go to VK ID Console
2. Click "Create Application"
3. Choose "Website" platform

2. Configure OAuth

Redirect URI:

https://your-discourse-site.com/auth/vkid/callback

Scopes:

• ✅ vkid.personal_info (required)
• ✅ email (recommended)
• ✅ phone (optional)

PKCE: ✅ Must be enabled

3. Discourse Settings

Navigate to: Admin → Settings → Login

Setting	Value	Description
vkid_enabled	✅	Enable VK ID authentication
vkid_client_id	123456	App ID from VK ID console
vkid_client_secret	••••••	Secret key from VK ID
vkid_scope	vkid.personal_info email phone	OAuth scopes
vkid_widget_enabled	✅	Enable OneTap widget
vkid_widget_providers	vkid,ok_ru,mail_ru	Widget providers

---

🎨 OneTap Widget

Modern UI with Multi-Provider Support

Provider	Color	Icon
VK ID	#0077ff	🔵
OK.ru	#ee8208	🟠
Mail.ru	#005ff9	🔵

Features:

• ⚡ Loads asynchronously (~50KB gzipped)
• 📱 Mobile responsive design
• 🌙 Dark theme support
• 🎯 One-click authentication
• 🔄 Seamless backend integration

---

🔄 Migration from Old Plugin

Automatic Migration ✨

Users are automatically migrated on first login:

User logs in with VK ID
    ↓
Plugin detects old 'vkontakte' account
    ↓
Updates to 'vkid' provider
    ↓
User logged in seamlessly ✅

No manual intervention required!

Manual Migration (Optional)

Migrate all users at once:

cd /var/discourse
./launcher enter app
rake vkid:migrate_users

See: MIGRATION_GUIDE.md for detailed instructions

---

🏗️ Architecture

OAuth 2.1 Flow with PKCE

graph LR
    A[User] -->|Click Login| B[VK ID Widget]
    B -->|Generate PKCE| C[VK ID Server]
    C -->|Authorization Code| D[Discourse Callback]
    D -->|Exchange + Verify PKCE| E[Access Token]
    E -->|Fetch User Info| F[Create/Update User]
    F -->|Session| A

Loading

Technology Stack

Layer	Technology	Purpose
Frontend	VK ID SDK	Widget UI
Backend	Custom Strategy	OAuth 2.1 + PKCE
Auth		Secure flow
Data		User storage

Files Structure

discourse-vk-auth/
├── 📄 plugin.rb                              # Entry point
├── 📁 lib/
│   ├── 🔐 vkid_authenticator.rb             # Main authenticator
│   ├── 🔑 omniauth/strategies/vkid.rb       # OAuth 2.1 + PKCE
│   └── 🛠️ tasks/vkid_migration.rake         # Migration utilities
├── 📁 assets/
│   ├── 🎨 javascripts/                       # VK ID widget
│   └── 💅 stylesheets/                       # Widget styles
├── 📁 config/
│   ├── ⚙️ settings.yml                       # Plugin settings
│   └── 🌐 locales/                           # i18n (en, ru)
├── 🧪 spec/                                  # Test suite (~150 tests)
├── 📖 README.md                              # This file
├── 📖 README_RU.md                           # Russian docs
├── 📖 MIGRATION_GUIDE.md                     # Migration guide
└── 📖 MIGRATION_GUIDE_RU.md                  # Russian migration

---

🧪 Testing

Run the test suite:

bundle exec rspec

Coverage:

• ✅ PKCE generation and validation
• ✅ User migration scenarios
• ✅ Username uniqueness
• ✅ Error handling
• ✅ ID Token parsing
• ✅ OAuth flow integration

Total: ~150 test cases

---

🐛 Troubleshooting

❌ "invalid_request: code_verifier is missing"

Cause: PKCE not properly implemented or disabled.

Solution: Ensure you're using plugin v2.0+. PKCE is handled automatically by the custom strategy.

❌ "No email returned from VK ID"

Cause: Email scope not granted or user hasn't provided email.

Solution:

• Check vkid_scope includes email
• Verify VK ID app has email permission enabled
• User must have email in their VK account

❌ "redirect_uri_mismatch"

Cause: Redirect URI doesn't match VK app settings.

Solution: Verify redirect URI in VK ID console:

https://your-site.com/auth/vkid/callback

❌ Widget not showing

Checks:

1. vkid_enabled is true
2. vkid_widget_enabled is true
3. vkid_client_id is configured
4. Browser console for errors

Debug:

console.log(window.VKIDSDK); // Should show SDK
console.log(Discourse.SiteSettings.vkid_enabled); // true

See: Full troubleshooting guide in README.md

---

📚 Documentation

Document	Description
📖 README.md	Main documentation (English)
📖 README_RU.md	Документация (Русский)
📖 MIGRATION_GUIDE.md	Migration from v1.x
📖 MIGRATION_GUIDE_RU.md	Руководство по миграции

---

🔗 API Endpoints

Endpoint	Purpose
https://id.vk.ru/authorize	OAuth authorization
https://id.vk.ru/oauth2/auth	Token exchange
https://id.vk.ru/oauth2/user_info	User information

---

🤝 Support

• Forum: Discourse Meta
• Issues: GitHub Issues
• VK ID Docs: Official Documentation
• VK ID DEMO: Official DEMO

---

📄 License

MIT License - see LICENSE file for details

---

🎉 Changelog

Version 2.0.0 (2025)

✨ New Features

• ✅ OAuth 2.1 with mandatory PKCE
• ✅ Custom OmniAuth strategy
• ✅ VK ID SDK widget integration
• ✅ Multi-provider support (VK/OK/Mail.ru)
• ✅ Automatic user migration
• ✅ Bilingual documentation

🔧 Technical

• ✅ New endpoints (id.vk.ru)
• ✅ PKCE implementation (RFC 7636)
• ✅ ID Token parsing
• ✅ Enhanced security
• ✅ Comprehensive tests

📖 Documentation

• ✅ Complete rewrite
• ✅ Migration guides
• ✅ Widget documentation
• ✅ Troubleshooting

Version 1.x (Legacy - Deprecated)

• ⚠️ Old VK OAuth 2.0 (oauth.vk.com)
• ⚠️ No PKCE support
• ⚠️ No longer compatible

---

**Made with ❤️ for Discourse community**

⬆ Back to top