yandex-id-oauth-php

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

yandex-id-oauth-php

★ 18 Open GitHub ↗

PHP SDK для Yandex ID OAuth с полной поддержкой Laravel. Комплексная библиотека для авторизации через Яндекс ID. Интеграция с Laravel, обработка ошибок, DTO, PKCE, логирование. Поддержка Laravel 8-12.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Yandex ID OAuth PHP

![Yandex ID/OAuth PHP SDK](https://github.com/user-attachments/assets/87227db6-8d98-4c00-961d-bfe82e174021)

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

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

> 📖 **English version:** [here](README-en.md)

---

## 📋 Содержание

- [🚀 Возможности](#-возможности)
- [🔧 Создание приложения в Яндекс OAuth](#-создание-приложения-в-яндекс-oauth)
- [💾 Установка](#-установка)
- [⚙️ Интеграция с Laravel](#️-интеграция-с-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: Регистрация приложения

1. Перейдите в [консоль Яндекс OAuth](https://oauth.yandex.ru/)
2. Нажмите кнопку **"+ Создать"**
3. Во всплывающем окне укажите тип приложения:
    - ✅ **Для авторизации пользователей** (рекомендуется для веб-сервисов)
    - Для доступа к 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. [Подробнее в документации Яндекса](https://yandex.ru/dev/id/doc/ru/codes/code-url)

---

## 💾 Установка

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

2. Установите пакет:
   ```bash
   composer require tigusigalpa/yandex-id-oauth-php --prefer-source
   ```

---

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

- 🔄 **Авто‑обнаружение провайдера и фасада** включено
- 📋 **Публикация конфига:**
  ```bash
  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`:**

```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
```

---

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

### Через фасад

```php
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

```php
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

```php
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
<?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
<?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']);
```

---

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

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

```php
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 статус
}
```

---

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

- 🌐 [О сервисе Яндекс ID](https://yandex.ru/dev/id/doc/ru/)
- 🔗 [Подключение к API](https://yandex.ru/dev/id/doc/ru/how-to)
- 📝 [Регистрация приложения](https://yandex.ru/dev/id/doc/ru/register-client)
- 🔍 [Получение кода из URL](https://yandex.ru/dev/id/doc/ru/codes/code-url)
- 🔄 [Обмен кода на токен](https://yandex.ru/dev/id/doc/ru/codes/code-url#token)

---

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

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

---

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

yandex-id-oauth-php

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README