README

🔐 Полнофункциональный OAuth клиент для Яндекс ID с бесшовной интеграцией в Laravel

Авторизация через Яндекс ID: построение URL, обмен кода на токен, обновление токена и получение профиля пользователя

📖 English version: here

📋 Содержание

🚀 Возможности
🔧 Создание приложения в Яндекс OAuth
💾 Установка
⚙️ Интеграция с Laravel
🎯 Конфигурация
📖 Использование
🛡️ Обработка ошибок
📚 Документация

🚀 Возможности

✅ authUrl() — формирование URL для авторизации (response_type=code)
✅ exchangeCode() — обмен кода подтверждения на OAuth‑токен (возвращает TokenResponse)
✅ refreshToken() — обновление токена по refresh_token (возвращает TokenResponse)
✅ getUserInfo() — получение профиля пользователя по access_token (возвращает UserInfo)
✅ revokeToken() — отзыв токена доступа
🎯 Полная интеграция с Laravel: сервис‑провайдер, фасад, публикуемый конфиг
🔒 PKCE поддержка для enhanced security
⚡ Пользовательские исключения для детальной обработки ошибок
📝 PSR-3 логирование с автоматической интеграцией с Laravel
🏗️ DTO классы для структурированных ответов

🔧 Создание приложения в Яндекс OAuth

Шаг 1: Регистрация приложения

Перейдите в консоль Яндекс OAuth
Нажмите кнопку "+ Создать"
Во всплывающем окне укажите тип приложения:
- ✅ Для авторизации пользователей (рекомендуется для веб-сервисов)
- Для доступа к API или отладки

Шаг 2: Основная информация

Шаг 1/4:

📝 Название вашего сервиса — введите название вашего приложения
🖼️ Иконка сервиса — прикрепите иконку (рекомендуется 128x128px)
📧 Почта для связи — укажите контактный email

Шаг 2/4:

🌐 Платформы приложений — обязательно выберите "Веб-сервисы"
🔗 Redirect URI — введите URL для перенаправления после авторизации:
```
https://your.app/callback/yandex
```
🏠 Suggest Hostname — хост страницы, на которой разместится кнопка авторизации

Шаг 3: Права доступа

Шаг 3/4: Выберите необходимые права доступа к данным пользователей:

📅 Доступ к дате рождения
📧 Доступ к адресу электронной почты
👤 Доступ к логину, имени и фамилии, полу
📸 Доступ к портрету пользователя
📱 Доступ к номеру телефона

💡 Совет: Выберите только те права, которые действительно необходимы вашему приложению.

Шаг 4: Завершение

Шаг 4/4:

✅ Проверьте все введенные данные
✅ Нажмите "Создать приложение"

После создания вам будут выданы:

🔑 Client ID — идентификатор клиента
🔐 Client Secret — секретный ключ

📖 Документация: Мы используем метод подтверждения через получение code из специального URL. Подробнее в документации Яндекса

💾 Установка

Добавьте репозиторий типа path в корневой composer.json вашего проекта:
```
{
  "repositories": [
    { "type": "path", "url": "public_html/packages/yandex-id-oauth-php" }
  ]
}
```

Установите пакет:

composer require tigusigalpa/yandex-id-oauth-php --prefer-source

⚙️ Интеграция с Laravel

🔄 Авто‑обнаружение провайдера и фасада включено

📋 Публикация конфига:

php artisan vendor:publish --tag=yandexid-config

🎯 Конфигурация

config/yandexid.php управляется через .env:

Переменная	Описание	Пример
`YANDEX_ID_CLIENT_ID`	ID вашего приложения	`your_client_id`
`YANDEX_ID_CLIENT_SECRET`	Секретный ключ	`your_client_secret`
`YANDEX_ID_REDIRECT_URI`	URL для редиректа	`https://your.app/callback/yandex`
`YANDEX_ID_SCOPE`	Права доступа	`login:email login:info`
`YANDEX_ID_FORCE_CONFIRM`	Принудительное подтверждение	`false`
`YANDEX_ID_AUTH_BASE`	Базовый URL OAuth	`https://oauth.yandex.ru`
`YANDEX_ID_USER_INFO_ENDPOINT`	URL информации о пользователе	`https://login.yandex.ru/info`
`YANDEX_ID_USER_INFO_AUTH`	Тип авторизации	`OAuth`

Пример .env:

YANDEX_ID_CLIENT_ID=your_client_id
YANDEX_ID_CLIENT_SECRET=your_client_secret
YANDEX_ID_REDIRECT_URI=https://your.app/callback/yandex
YANDEX_ID_SCOPE=login:email login:info
YANDEX_ID_FORCE_CONFIRM=false
YANDEX_ID_USER_INFO_AUTH=OAuth

📖 Использование

Через фасад

use Tigusigalpa\YandexID\Facades\YandexId;
use Tigusigalpa\YandexID\Dto\TokenResponse;
use Tigusigalpa\YandexID\Dto\UserInfo;

// 🎯 Получение URL авторизации
$url = YandexId::authUrl(state: 'abc123');

// 🔄 Обмен кода на токен (возвращает TokenResponse)
$token = YandexId::exchangeCode($code);
echo $token->accessToken; // string
echo $token->expiresIn;   // int|null

// 👤 Получение информации о пользователе (возвращает UserInfo)
$profile = YandexId::getUserInfo($token->accessToken);
echo $profile->getDisplayName(); // string
echo $profile->getPrimaryEmail(); // string|null

// 🔄 Обновление токена
$refreshed = YandexId::refreshToken($token->refreshToken);

// 🗑️ Отзыв токена
$success = YandexId::revokeToken($token->accessToken);

PKCE и проверка state

use Tigusigalpa\YandexID\Facades\YandexId;

// 🔐 Генерация ссылки авторизации с PKCE
$auth = YandexId::authUrlWithPkce(state: null, prompt: null);
// Сохраните $auth['state'] и $auth['verifier'] в сессии
$url = $auth['url'];

// ✅ После редиректа проверьте state
$isValid = YandexId::validateState($_GET['state'] ?? '', session('yandex_state'));
if (!$isValid) {
    // обработка ошибки CSRF
}

// 🔄 Обмен кода на токен по PKCE
$tokens = YandexId::exchangeCodeWithPkce($_GET['code'], session('yandex_verifier'));

Через DI

use Tigusigalpa\YandexID\YandexIdClient;

public function __construct(YandexIdClient $yandex)
{
    $this->yandex = $yandex;
}

$url = $this->yandex->authUrl('xyz');
$token = $this->yandex->exchangeCode($code); // TokenResponse
$profile = $this->yandex->getUserInfo($token->accessToken); // UserInfo

Использование без Laravel (Standalone PHP)

Библиотека может использоваться без Laravel как обычный PHP пакет:

<?php
require_once 'vendor/autoload.php';

use Tigusigalpa\YandexID\YandexIdClient;
use Tigusigalpa\YandexID\Dto\TokenResponse;
use Tigusigalpa\YandexID\Dto\UserInfo;
use Psr\Log\NullLogger;

// 🚀 Создание клиента
$client = new YandexIdClient(
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret',
    redirectUri: 'https://your.app/callback/yandex',
    scope: 'login:email login:info',
    forceConfirm: false,
    authBase: 'https://oauth.yandex.ru',
    userInfoEndpoint: 'https://login.yandex.ru/info',
    userInfoAuth: 'OAuth',
    httpClient: null, // Используем Guzzle по умолчанию
    logger: new NullLogger() // или ваш PSR-3 логгер
);

// 🎯 Получение URL авторизации
$authUrl = $client->authUrl('random_state_123');
header('Location: ' . $authUrl);
exit;

// 🔄 Обмен кода на токен (в callback)
$code = $_GET['code'] ?? '';
$token = $client->exchangeCode($code);

echo "Access Token: " . $token->accessToken . "\n";
echo "Expires In: " . $token->expiresIn . "\n";
echo "Refresh Token: " . $token->refreshToken . "\n";

// 👤 Получение информации о пользователе
$profile = $client->getUserInfo($token->accessToken);
echo "User ID: " . $profile->id . "\n";
echo "Login: " . $profile->login . "\n";
echo "Name: " . $profile->getFullName() . "\n";
echo "Email: " . $profile->getPrimaryEmail() . "\n";

// 🔄 Обновление токена
$newToken = $client->refreshToken($token->refreshToken);

// 🗑️ Отзыв токена
$success = $client->revokeToken($token->accessToken);
echo "Token revoked: " . ($success ? 'Yes' : 'No') . "\n";

Пример с PKCE (без Laravel)

<?php
require_once 'vendor/autoload.php';

use Tigusigalpa\YandexID\YandexIdClient;
use Psr\Log\NullLogger;

session_start();

$client = new YandexIdClient(
    'your_client_id',
    'your_client_secret',
    'https://your.app/callback/yandex',
    'login:email login:info',
    false,
    'https://oauth.yandex.ru',
    'https://login.yandex.ru/info',
    'OAuth',
    null,
    new NullLogger()
);

// 🔐 Генерация PKCE параметров и сохранение в сессию
$auth = $client->authUrlWithPkce();
$_SESSION['yandex_state'] = $auth['state'];
$_SESSION['yandex_verifier'] = $auth['verifier'];

// Перенаправление на авторизацию
header('Location: ' . $auth['url']);
exit;

// В callback обработке:
$code = $_GET['code'] ?? '';
$state = $_GET['state'] ?? '';

// ✅ Проверка state
if (!$client->validateState($state, $_SESSION['yandex_state'])) {
    die('Invalid state - CSRF protection');
}

// 🔄 Обмен кода на токен по PKCE
$token = $client->exchangeCodeWithPkce($code, $_SESSION['yandex_verifier']);

// Очистка сессии
unset($_SESSION['yandex_state'], $_SESSION['yandex_verifier']);

🛡️ Обработка ошибок

Библиотека использует структурированные исключения:

use Tigusigalpa\YandexID\Facades\YandexId;
use Tigusigalpa\YandexID\Exceptions\ApiException;
use Tigusigalpa\YandexID\Exceptions\InvalidRequestException;

try {
    $token = YandexId::exchangeCode($code);
} catch (InvalidRequestException $e) {
    // ❌ Ошибка валидации входных данных
    echo $e->getMessage();
} catch (ApiException $e) {
    // ❌ Ошибка API Yandex
    echo $e->getMessage();
    echo $e->getContext()['status']; // HTTP статус
}

📚 Документация

👨‍💻 Автор и лицензия

👤 Автор: Igor Sazonov (tigusigalpa)
📧 Email: sovletig@gmail.com
🐙 GitHub: https://github.com/tigusigalpa/yandex-id-oauth-php
📄 Лицензия: MIT

⭐ Если библиотека вам помогла, поставьте звезду на GitHub!

tigusigalpa / yandex-id-oauth-php

Maintainers

Details