randomayzer/docs/VK_OAUTH_FLOW.md

VK ID OAuth 2.1 Authentication Flow

This document specifies the authorization flow, endpoints, and security contracts for organizer login via VK ID.

---

Sequence Diagram

sequenceDiagram
    autonumber
    actor User as Organizer (Browser)
    participant App as Randomayzer Frontend
    participant Server as Randomayzer API
    participant Vault as Token Vault / DB
    participant VKID as VK ID OAuth 2.1 (id.vk.com)

    User->>App: Click "Войти через VK ID"
    App->>Server: GET /api/auth/vk/start?redirectTarget=/
    Server->>Server: Generate PKCE (verifier + S256 challenge) & State (32 bytes)
    Server->>Server: Save OAuthTransaction (10m TTL, single-use)
    Server-->>User: 302 Redirect to VK ID Auth URL
    User->>VKID: Authorize App & Grant Permissions
    VKID-->>User: 302 Redirect to /api/auth/vk/callback?code=AUTH_CODE&state=STATE
    User->>Server: GET /api/auth/vk/callback?code=AUTH_CODE&state=STATE
    Server->>Server: Validate & Consume single-use State
    Server->>VKID: POST /oauth2/auth (grant_type=authorization_code, code, code_verifier)
    VKID-->>Server: 200 OK (access_token, refresh_token, user_id, expires_in)
    Server->>Vault: Encrypt access_token & refresh_token with AES-256-GCM
    Server->>Server: Fetch Profile (users.get) & Upsert User/Organizer
    Server->>Server: Create Session & set HttpOnly Secure Cookie
    Server-->>User: 302 Redirect to redirectTarget
    User->>Server: GET /api/auth/me (Cookie: randomayzer_session)
    Server-->>User: 200 OK (safe profile without tokens)

---

Official Endpoints

1. Authorization Start: https://id.vk.com/auth

   • Parameters:
     • response_type=code
     • client_id (VK App ID)
     • redirect_uri (https://randomayzer.domain/api/auth/vk/callback)
     • state (Cryptographically random, single-use, 10 min TTL)
     • code_challenge (BASE64URL(SHA256(code_verifier)))
     • code_challenge_method=S256
     • scope=wall,groups,offline

2. Token Exchange: https://id.vk.com/oauth2/auth

   • Method: POST application/x-www-form-urlencoded
   • Parameters:
     • grant_type=authorization_code
     • code
     • code_verifier
     • client_id
     • client_secret
     • redirect_uri
     • state