Randify.pro/docs/OAUTH_SETUP.md

OAuth App Setup Guide

This document explains how to register OAuth applications with VK and Yandex for the DM Dashboard authentication system.

---

1. VK ID Registration

Follow these steps to create a VK ID application for user authentication.

1.1. Start Registration

1. Go to the VK ID for Business portal: https://id.vk.com/about/business/go/
2. Sign in with your VK account
3. Navigate to the applications section and click "Create application"

1.2. Configure Platform

Select "Web" as the platform type for your application.

1.3. Add Redirect URIs

Add the following redirect URIs to your application settings:

http://localhost:4321/api/auth/callback/vk

For production, also add:

https://your-domain.com/api/auth/callback/vk

1.4. Request Scopes

Ensure the following scopes are requested during authentication:

• profile - Access to basic user profile information
• email - Access to user's email address

1.5. Copy Credentials

After creating the application:

1. Copy the Client ID (Application ID)
2. Copy the Client Secret (Secure key)
3. Paste both values into your .env file:

VK_CLIENT_ID=your_vk_client_id
VK_CLIENT_SECRET=your_vk_client_secret

---

2. Yandex OAuth Registration

Follow these steps to create a Yandex OAuth application for user authentication.

2.1. Start Registration

1. Go to the Yandex OAuth portal: https://oauth.yandex.com/
2. Sign in with your Yandex account
3. Click "Register a new client" or "Create application"

2.2. Configure Platform

Select "Web services" as the application type.

2.3. Add Redirect URIs

Add the following callback URL to your application settings:

http://localhost:4321/api/auth/callback/yandex

For production, also add:

https://your-domain.com/api/auth/callback/yandex

2.4. Request Scopes

Add the following access permissions (scopes):

• login:email - Access to user's email address
• login:info - Access to basic user information (name, etc.)
• login:avatar - Access to user's avatar image

2.5. Copy Credentials

After registering the application:

1. Copy the Client ID (also called Application ID)
2. Copy the Client Secret (also called Password)
3. Paste both values into your .env file:

YANDEX_CLIENT_ID=your_yandex_client_id
YANDEX_CLIENT_SECRET=your_yandex_client_secret

---

3. Environment Variables

The following environment variables are required for OAuth authentication:

Variable	Description	Source
VK_CLIENT_ID	VK application ID	VK ID admin panel
VK_CLIENT_SECRET	VK secure key	VK ID admin panel
YANDEX_CLIENT_ID	Yandex application ID	Yandex OAuth portal
YANDEX_CLIENT_SECRET	Yandex application password	Yandex OAuth portal
DATABASE_URL	PostgreSQL connection string	Your database setup
JWT_SECRET	Secret key for JWT token signing	Generate a random string

3.1. Generate a JWT Secret

Generate a secure random string for JWT signing:

openssl rand -base64 32

Copy the output and set it as JWT_SECRET in your .env file.

---

4. Testing OAuth Locally

After completing registration and setting up environment variables, test the login flow.

4.1. Start the Development Server

npm run dev

4.2. Test VK Login

1. Open http://localhost:4321 in your browser
2. Click "Sign in with VK"
3. You should be redirected to VK for authorization
4. After granting permissions, you should be redirected back to the dashboard
5. Check that your user profile is created in the database

4.3. Test Yandex Login

1. Open http://localhost:4321 in your browser
2. Click "Sign in with Yandex"
3. You should be redirected to Yandex for authorization
4. After granting permissions, you should be redirected back to the dashboard
5. Check that your user profile is created in the database

4.4. Troubleshooting

If authentication fails:

• Verify redirect URIs match exactly (including protocol and port)
• Check that all required scopes are granted
• Review server logs for OAuth callback errors
• Ensure environment variables are loaded correctly