### Discourse VK Auth: Installation and Configuration (Bash)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This guide provides shell commands to install the VK authentication plugin for Discourse by cloning the repository and rebuilding the application container. It also outlines the steps for configuring VK application settings on the VK website and within the Discourse admin panel.

```bash
# 1. Install the plugin
cd /var/discourse
git clone https://github.com/discourse/discourse-vk-auth.git plugins/discourse-vk-auth

# 2. Rebuild Discourse container
./launcher rebuild app

# 3. Create VK application at https://vk.com/apps?act=manage
# - Select "Website" platform
# - Note the App ID and Secure Key from settings

# 4. Configure in Discourse Admin Panel
# Navigate to: Site Settings → Search "VK"
# Set the following values:
# - vk_app_id: "your_app_id_here"
# - vk_secure_key: "your_secure_key_here"
# - vk_auth_enabled: true

# 5. Test authentication
# Visit your forum's login page
# Click "Login with VK" button
# Authorize the app on VK.com
# You should be redirected back and logged in
```

--------------------------------

### Handle VK OAuth Callback and User Authentication

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This code illustrates the handling of the OAuth callback from VK. It shows how to make a POST request to the callback endpoint with the authorization code and state. The snippet also details the expected outcomes: a successful login with user redirection and session ID assignment, or a failed login if VK does not provide a verified email.

```ruby
# Usage in integration test
# After VK redirects back with authorization code
post "/auth/vkontakte/callback",
  params: {
    state: session["omniauth.state"],
    code: "vk_temp_code_544254"
  }

# If successful (email verified and matches existing user)
response.status # => 302
response.location # => "http://test.localhost/"
session[:current_user_id] # => user.id

# If failed (no verified email from VK)
response.status # => 302
response.location # => "http://test.localhost/"
session[:current_user_id] # => nil
```

--------------------------------

### Discourse Plugin Metadata and Dependencies

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Configures the Discourse plugin's metadata, including its name, description, author, and version. It also declares the dependency on the 'omniauth-vkontakte' gem, specifying the required version for proper functionality.

```ruby
# plugin.rb
# frozen_string_literal: true

# name: discourse-vk-auth
# about: Allows users to login to your forum using VK.com Authentication
# meta_topic_id: 12987
# version: 0.1
# author: Penar Musaraj
# url: https://github.com/discourse/discourse-vk-auth

enabled_site_setting :vk_auth_enabled
enabled_site_setting :vk_app_id
enabled_site_setting :vk_secure_key

gem "omniauth-vkontakte", "1.7.1"
```

--------------------------------

### Initiate VK OAuth Authentication Flow

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This snippet demonstrates how to initiate the VK OAuth 2.0 authentication process by making a POST request to the Discourse endpoint. The expected response is a 302 redirect to VK's authorization server, containing necessary OAuth parameters like client ID, redirect URI, and scope.

```ruby
# Usage in integration test
post "/auth/vkontakte"
# Response: 302 redirect to https://oauth.vk.com/authorize
# Includes client_id, redirect_uri, scope=email, state (CSRF token)

# Expected response
response.status # => 302
response.location # => "https://oauth.vk.com/authorize?client_id=..."
```

--------------------------------

### Localization Configuration - English VK Login (YAML)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Configures English client-side strings for VK login UI elements within Discourse. This YAML file defines the text displayed to users during the VK authentication process in English. It specifies names, titles, and messages for the VK login option.

```yaml
# config/locales/client.en.yml
en:
  js:
    login:
      vkontakte:
        name: "Vkontakte"
        title: "with VK"
        message: "Authenticating with VK (make sure pop up blockers are not enabled)"
```

--------------------------------

### VK OAuth: Token Exchange and User Data Fetch (cURL)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This section demonstrates how to manually exchange an authorization code for an access token and retrieve user profile information from the VK API using cURL. It shows two separate cURL commands: one for the token exchange and another for fetching user details.

```bash
# Exchange authorization code for access token
curl -X POST "https://oauth.vk.com/access_token" \
  -d "client_id=abcdef11223344" \
  -d "client_secret=adddcccdddd99922" \
  -d "code=vk_temp_code_544254" \
  -d "redirect_uri=https://example.com/auth/vkontakte/callback"

# Response (URL-encoded):
# access_token=vk_access_token_448&email=user@example.com&user_id=9829345845345

# Fetch user profile data
curl "https://api.vk.com/method/users.get" \
  -G \
  -d "access_token=vk_access_token_448" \
  -d "fields=nickname,screen_name,sex,city,country,photo_200" \
  -d "v=5.107"

# Response (JSON):
# {
#   "response": [{
#     "id": 9829345845345,
#     "first_name": "Russian",
#     "last_name": "Guy",
#     "screen_name": "russianguy",
#     "photo_200": "https://..."
#   }]
# }
```

--------------------------------

### VK Authentication Site Settings Configuration

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Defines the configuration settings for the VK authentication plugin within Discourse. This includes fields for the VK application ID, secure key, and a boolean to enable or disable the VK authentication provider. These settings are managed via the Discourse admin interface.

```yaml
# config/settings.yml
plugins:
  vk_app_id:
    default: ""
  vk_secure_key:
    default: ""
  vk_auth_enabled:
    client: true
    default: false
```

--------------------------------

### Localization Configuration - Russian VK Login (YAML)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Configures Russian client-side strings for VK login UI elements in Discourse, ensuring native language support. This YAML file provides localized text for the VK authentication process in Russian, enhancing user experience for Russian-speaking communities.

```yaml
# config/locales/client.ru.yml
ru:
  js:
    login:
      vkontakte:
        name: "Vkontakte"
        title: "Войти через VK"
        message: "Аутентификация с помощью VK (убедитесь, что всплывающие окна разрешены)"
```

--------------------------------

### VK Authenticator Class for Discourse

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Defines the VkontakteAuthenticator class, extending Discourse's Auth::ManagedAuthenticator to handle VK OAuth integration. It configures middleware, sets API credentials from site settings, and defines how user information is presented and processed after authentication. VK is configured to always return verified emails.

```ruby
class Auth::VkontakteAuthenticator < Auth::ManagedAuthenticator
  def name
    "vkontakte"
  end

  def enabled?
    SiteSetting.vk_auth_enabled
  end

  def register_middleware(omniauth)
    omniauth.provider :vkontakte,
                      setup:
                        lambda { |env|
                          strategy = env["omniauth.strategy"]
                          strategy.options[:client_id] = SiteSetting.vk_app_id
                          strategy.options[:client_secret] = SiteSetting.vk_secure_key
                          strategy.options[:scope] = "email"
                        }
  end

  def description_for_user(user)
    info = UserAssociatedAccount.find_by(provider_name: name, user_id: user.id)&.info
    return "" if info.nil?
    info["name"] || info["email"] || ""
  end

  def after_authenticate(auth_token, existing_account: nil)
    auth_token[:extra] = {}
    super
  end

  def primary_email_verified?(auth_token)
    true
  end
end

# Register the authenticator with Discourse
register_svg_icon "fab-vk" if respond_to?(:register_svg_icon)
auth_provider authenticator: Auth::VkontakteAuthenticator.new, icon: "fab-vk"
```

--------------------------------

### Retrieve VK Account Display Info (Ruby)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Retrieves displayable information (name or email) for a user's associated VK account. This Ruby method queries the UserAssociatedAccount model and returns relevant details if an account is linked, otherwise returns an empty string. It's used in the user preferences panel.

```ruby
# plugin.rb
def description_for_user(user)
  info = UserAssociatedAccount.find_by(
    provider_name: name,
    user_id: user.id
  )&.info
  return "" if info.nil?

  info["name"] || info["email"] || ""
end

# Usage example:
# In user preferences, displays: "Russian Guy" or "user@example.com"
# If no association exists, displays: ""
```

--------------------------------

### Discourse VK Auth: User Sign-in with Verified Email (Ruby)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This RSpec integration test verifies that a user can successfully sign in to Discourse using VK authentication when VK provides a verified email address. It stubs API requests to VK for user data and token exchange. Successful authentication redirects the user and sets the session.

```ruby
RSpec.describe "VK Oauth2" do
  let(:access_token) { "vk_access_token_448" }
  let(:app_id) { "abcdef11223344" }
  let(:secure_key) { "adddcccdddd99922" }
  let(:temp_code) { "vk_temp_code_544254" }
  let(:vk_user_id) { 9_829_345_845_345 }

  fab!(:user)

  before do
    SiteSetting.vk_auth_enabled = true
    SiteSetting.vk_app_id = app_id
    SiteSetting.vk_secure_key = secure_key

    # Stub VK API user data endpoint
    stub_request(:get,
      "https://api.vk.com/method/users.get?access_token=#{access_token}&fields=nickname,screen_name,sex,city,country,online,bdate,photo_50,photo_100,photo_200,photo_200_orig,photo_400_orig&https=0&lang=&v=5.107"
    ).to_return(
      status: 200,
      body: JSON.dump(response: [{
        id: vk_user_id.to_s,
        first_name: "Russian",
        last_name: "Guy"
      }]),
      headers: { "Content-Type" => "application/json" }
    )
  end

  it "signs in the user if VK returns verified email" do
    # Initiate OAuth flow
    post "/auth/vkontakte"
    expect(response.status).to eq(302)
    expect(response.location).to start_with("https://oauth.vk.com/authorize")

    # Stub token exchange endpoint
    stub_request(:post, "https://oauth.vk.com/access_token").with(
      body: hash_including(
        "client_id" => app_id,
        "client_secret" => secure_key,
        "code" => temp_code
      )
    ).to_return(
      status: 200,
      body: Rack::Utils.build_query(
        access_token: access_token,
        email: user.email,
        user_id: vk_user_id
      ),
      headers: { "Content-Type" => "application/x-www-form-urlencoded" }
    )

    # Handle OAuth callback
    post "/auth/vkontakte/callback",
      params: { state: session["omniauth.state"], code: temp_code }

    expect(response.status).to eq(302)
    expect(response.location).to eq("http://test.localhost/")
    expect(session[:current_user_id]).to eq(user.id)
  end
end
```

--------------------------------

### Discourse VK Auth: Rejection of Unverified Email (Ruby)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

This RSpec integration test demonstrates the failure case where VK authentication is rejected because the VK API response does not include an email address, indicating an unverified account. Similar to the success case, it stubs API requests but expects no user to be logged in.

```ruby
# spec/integration/vk_auth_spec.rb
it "doesn't sign in if VK doesn't include email" do
  # Initiate OAuth flow
  post "/auth/vkontakte"
  expect(response.status).to eq(302)
  expect(response.location).to start_with("https://oauth.vk.com/authorize")

  # Stub token exchange with no email (unverified)
  stub_request(:post, "https://oauth.vk.com/access_token").with(
    body: hash_including(
      "client_id" => app_id,
      "client_secret" => secure_key,
      "code" => temp_code
    )
  ).to_return(
    status: 200,
    body: Rack::Utils.build_query(
      access_token: access_token,
      email: nil,  # No email returned
      user_id: vk_user_id
    ),
    headers: { "Content-Type" => "application/x-www-form-urlencoded" }
  )

  # Handle OAuth callback
  post "/auth/vkontakte/callback",
    params: { state: session["omniauth.state"], code: temp_code }

  expect(response.status).to eq(302)
  expect(response.location).to eq("http://test.localhost/")
  expect(session[:current_user_id]).to be_blank  # No user logged in
end
```

--------------------------------

### VK Email Verification Trust Policy (Ruby)

Source: https://context7.com/discourse/discourse-vk-auth/llms.txt

Sets the email verification policy for VK-authenticated users in Discourse to trust emails as pre-verified. This Ruby method always returns true, indicating that emails received from VK are considered verified by default. This is based on the assumption that the VK API only returns verified emails.

```ruby
# plugin.rb
def primary_email_verified?(auth_token)
  true
end

# Rationale: VK API only returns verified emails
# If user's email is unverified on VK, it won't be included in API response
# Therefore, any email we receive from VK is guaranteed to be verified
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.