omniauth-vk_id

OmniAuth 1.9-compatible strategy for VK ID (id.vk.ru) — the new ВКонтакте authorization protocol based on OAuth 2.1 + PKCE.

This is not compatible with the legacy omniauth-vkontakte gem (which uses the classic oauth.vk.com endpoint). VK now registers all new applications via id.vk.com, which requires the new protocol.

Features

• Authorization Code flow with PKCE (S256)
• Accepts the VK ID callback both as payload JSON and as flat query params
• Token exchange without client_secret (PKCE replaces it)
• Fetches user info from https://id.vk.ru/oauth2/user_info
• Returns a standard OmniAuth auth hash with uid, info.name, info.email, info.image, info.phone, credentials, extra.raw_info

Requirements

• Ruby >= 3.0
• omniauth ~> 1.9
• omniauth-oauth2 ~> 1.7

Installation

In your Gemfile:

gem 'omniauth-vk_id', '~> 0.1'

Then bundle install.

Important — full_host behind a reverse proxy. VK ID signs the flow against the exact redirect_uri, which OmniAuth builds from the incoming request's host/scheme. If your Rails app sits behind a proxy (nginx, Cloudflare, Heroku router, …) and receives HTTP internally, pin the public host explicitly, otherwise token exchange will fail with an invalid redirect_uri:

# config/initializers/omniauth.rb
OmniAuth.config.full_host = ENV.fetch('APP_HOST', 'https://your-domain.example')

Usage

Rails + Devise

# config/initializers/devise.rb
Devise.setup do |config|
  config.omniauth :vk_id,
                  ENV['OMNIAUTH_VK_ID_APP_ID'],
                  ENV['OMNIAUTH_VK_ID_SECRET'],
                  scope: 'email phone' # default: 'email phone'. Drop 'phone' if not needed.
end

Options

Option	Default	Description
scope	'email phone'	Space-separated VK ID scopes to request.
lang_id	(unset)	Optional VK ID language override (see VK ID docs).
scheme	(unset)	Optional UI scheme (light/dark/auto).
callback_path	/auth/vk_id/callback	Override if you mount OmniAuth under another path.

Routes (/users/auth/vk_id and /users/auth/vk_id/callback) are generated automatically by Devise.

Add a callback handler in app/controllers/users/omniauth_callbacks_controller.rb:

class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
  def vk_id
    handle_callback
  end
end

VK ID app setup

1. Register at https://id.vk.com → Мои приложения → Создать
2. Copy the numeric App ID and Защищённый ключ (Secret key)
3. In Доверенный Redirect URI add:
   • https://your-domain.example/users/auth/vk_id/callback
4. Export env vars:

   OMNIAUTH_VK_ID_APP_ID=12345
   OMNIAUTH_VK_ID_SECRET=yoursecret
   

Auth hash

{
  provider: 'vk_id',
  uid:      '1234567890',
  info: {
    name:       'Иван Иванов',
    email:      'user@example.com',
    first_name: 'Иван',
    last_name:  'Иванов',
    image:      'https://sun9-xxx.userapi.com/...',
    phone:      '+7...'
  },
  credentials: {
    token:         '...',
    refresh_token: '...',
    expires_at:    1711234567,
    expires:       true
  },
  extra: {
    raw_info: { ... },
    id_token: '...'
  }
}

Testing

bundle install
bundle exec rspec

License

MIT