167 lines
4.1 KiB
Markdown
167 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|