Техническая Поддержка

✅ Если вы используете ProMail для почты — всё необходимое описано выше. Этот раздел можно пропустить.

🛠️ Если вы разрабатываете сайт — ниже вы найдёте конфигурацию, примеры кода и частые ошибки.

Позвольте посетителям входить на ваш сайт через аккаунт ProMail вместо создания ещё одного пароля. ProMail берёт на себя пароли, ключи доступа и проверку отпечатка пальца; ваш сайт получает подтверждённую личность.

ProMail использует стандартный протокол OpenID Connect. Если у вашей платформы есть OIDC-библиотека, интеграция займёт около 10 минут — криптографию писать не придётся.

Перейдите в Аккаунт → 🔑 Приложения и нажмите ➕ Добавить приложение.
Введите название приложения и адрес возврата (redirect URI).

Каждое приложение занимает один слот лицензии. Та же лицензия может одновременно обслуживать домен и почтовый ящик — они не отнимают слоты друг у друга.

💡 Большинству библиотек нужен только Discovery URL — всё остальное они читают оттуда автоматически, включая ключи подписи.

1. promail-login.php — кнопка ведёт сюда

<?php
session_start();

define('ISSUER',        'https://promail.lv');
define('CLIENT_ID',     'your_client_id');
define('CLIENT_SECRET', 'your_client_secret');
define('REDIRECT_URI',  'https://yoursite.lv/promail-callback');

function b64url($b) {
    return rtrim(strtr(base64_encode($b), '+/', '-_'), '=');
}

// PKCE. Verifier остаётся на вашем сервере; в URL уходит только его хеш,
// поэтому украденный код без него бесполезен.
$verifier = b64url(random_bytes(32));
$_SESSION['pm_verifier'] = $verifier;
$_SESSION['pm_state']    = $state = b64url(random_bytes(16));
$_SESSION['pm_nonce']    = $nonce = b64url(random_bytes(16));

header('Location: ' . ISSUER . '/oidc/authorize?' . http_build_query([
    'client_id'             => CLIENT_ID,
    'redirect_uri'          => REDIRECT_URI,
    'response_type'         => 'code',
    'scope'                 => 'openid email profile',
    'state'                 => $state,
    'nonce'                 => $nonce,
    'code_challenge'        => b64url(hash('sha256', $verifier, true)),
    'code_challenge_method' => 'S256',
]));

2. promail-callback.php — сюда указывает redirect URI

<?php
session_start();
// ... те же define() что и выше ...

if (isset($_GET['error'])) {
    exit('Вход не удался: ' . htmlspecialchars($_GET['error']));
}

// state должен совпасть, иначе это подделанный запрос с другого сайта
if (!hash_equals($_SESSION['pm_state'] ?? '', $_GET['state'] ?? '')) {
    exit('Проверка безопасности не пройдена');
}

// Обмен кода. Сервер к серверу через TLS - браузер не участвует,
// поэтому здесь безопасно передавать client secret.
$ch = curl_init(ISSUER . '/oidc/token');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'grant_type'    => 'authorization_code',
        'code'          => $_GET['code'],
        'redirect_uri'  => REDIRECT_URI,
        'code_verifier' => $_SESSION['pm_verifier'],
        'client_id'     => CLIENT_ID,
        'client_secret' => CLIENT_SECRET,
    ]),
]);
$tokens = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($tokens['id_token'])) { exit('Обмен токена не удался'); }

$claims = json_decode(base64_decode(strtr(
    explode('.', $tokens['id_token'])[1], '-_', '+/')), true);

if ($claims['iss'] !== ISSUER)    { exit('Неверный издатель'); }
if ($claims['aud'] !== CLIENT_ID) { exit('Неверная аудитория'); }
if ($claims['exp'] < time())      { exit('Токен истёк'); }
if ($claims['nonce'] !== $_SESSION['pm_nonce']) { exit('Nonce не совпадает'); }

unset($_SESSION['pm_verifier'], $_SESSION['pm_state'], $_SESSION['pm_nonce']);

// $claims['sub']   - постоянный ID пользователя. СОХРАНИТЕ ЕГО.
// $claims['email'] - может измениться. Не используйте как ключ.
// $claims['name']

$user = findUserByPromailSub($claims['sub']);
if (!$user) {
    // Первый раз. Свяжите с существующим аккаунтом или создайте новый.
}

Email используется как ключ аккаунта

Используйте sub. Он никогда не меняется. Email меняется, и повторно выданный адрес передал бы аккаунт следующему владельцу.

Redirect URI не совпадает точно

ProMail сравнивает его посимвольно. https://site.lv/cb и https://site.lv/cb/ — это два разных адреса. Самая частая ошибка.

Доверие полю alg самого токена

Всегда требуйте RS256 из собственной конфигурации. Токен, заявляющий alg: none, должен быть отвергнут.

Пропущена проверка state

Без неё злоумышленник может завершить вход в браузере жертвы и привязать свой аккаунт ProMail к её сессии.

Client Secret попадает в JavaScript

Он должен находиться только на сервере. Всё, что в коде браузера, — публично.

PKCE не используется

ProMail его требует. Запросы без code_challenge отклоняются.

Используйте одинаковый текст и вид, чтобы пользователи узнавали кнопку на всех сайтах.

<a href="/promail-login" class="promail-btn">
  <img src="https://promail.lv/img/promail-logo.webp" alt="" width="20" height="20">
  <span>Войти через ProMail</span>
</a>

<style>
.promail-btn{display:inline-flex;align-items:center;justify-content:center;
  gap:9px;padding:11px 18px;border:1px solid #d1d5db;border-radius:8px;
  background:#fff;color:#111827;font:600 14px system-ui,sans-serif;
  text-decoration:none}
.promail-btn:hover{background:#f9fafb;border-color:#9ca3af}
</style>

Отдельной тестовой среды нет. Зарегистрируйте второе приложение с адресом возврата http://localhost — localhost единственный адрес, разрешённый без https — и проверьте интеграцию перед запуском.