Tehniskais Atbalsts

✅ Ja lietojat ProMail e-pastam — viss nepieciešamais ir aprakstīts augstāk. Šo sadaļu varat izlaist.

🛠️ Ja veidojat mājaslapu — tālāk atradīsiet konfigurāciju, koda piemērus un biežākās kļūdas.

Ļaujiet apmeklētājiem pieteikties jūsu mājaslapā ar ProMail kontu — bez vēl vienas paroles. ProMail parūpējas par parolēm, piekļuves atslēgām un pirksta nospieduma pārbaudi; jūsu vietne saņem apstiprinātu identitāti.

ProMail izmanto standarta OpenID Connect protokolu. Ja jūsu sistēmai ir OIDC bibliotēka, integrācija aizņem apmēram 10 minūtes — kriptogrāfija jums nav jāraksta.

Dodieties uz Konts → 🔑 Lietotnes un nospiediet ➕ Pievienot lietotni.
Ievadiet lietotnes nosaukumu un atgriešanās adresi (redirect URI).

Katra lietotne izmanto vienu licences vietu. Tā pati licence vienlaikus var apkalpot domēnu un e-pasta kontu — tās neatņem viena otrai vietu.

💡 Lielākajai daļai bibliotēku pietiek ar Discovery URL — visu pārējo tās nolasa automātiski, ieskaitot parakstu atslēgas.

1. promail-login.php — poga ved šurp

<?php
session_start();

define('ISSUER',        'https://promail.lv');
define('CLIENT_ID',     'jusu_client_id');
define('CLIENT_SECRET', 'jusu_client_secret');
define('REDIRECT_URI',  'https://jusuvietne.lv/promail-callback');

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

// PKCE. Verifier paliek uz jusu servera; URL nonak tikai ta hash.
// Tapec nozagts kods bez ta nav izmantojams.
$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 norada šurp

<?php
session_start();
// ... tie pasi define() kas augstak ...

if (isset($_GET['error'])) {
    exit('Pieteiksanas neizdevas: ' . htmlspecialchars($_GET['error']));
}

// state jasakrit, citadi tas ir viltots pieprasijums no citas vietnes
if (!hash_equals($_SESSION['pm_state'] ?? '', $_GET['state'] ?? '')) {
    exit('Drosibas parbaude neizdevas');
}

// Koda apmaina. Serveris pret serveri caur TLS - parluks nav iesaistits,
// tapec seit ir drosi sutit 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('Marķiera apmaina neizdevas'); }

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

if ($claims['iss'] !== ISSUER)    { exit('Nepareizs izdevejs'); }
if ($claims['aud'] !== CLIENT_ID) { exit('Nepareiza auditorija'); }
if ($claims['exp'] < time())      { exit('Marķieris noildzis'); }
if ($claims['nonce'] !== $_SESSION['pm_nonce']) { exit('Nonce nesakrit'); }

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

// $claims['sub']   - pastavigs lietotaja ID. SAGLABAJIET SO.
// $claims['email'] - var mainities. Nelietojiet ka atslegu.
// $claims['name']

$user = atrastLietotajuPecSub($claims['sub']);
if (!$user) {
    // Pirma reize. Sasaistiet ar esosu kontu vai izveidojiet jaunu.
}

E-pasts tiek izmantots kā konta atslēga

Lietojiet sub. Tas nekad nemainās. E-pasti mainās, un atkārtoti izmantota adrese nodotu kontu nākamajam īpašniekam.

Redirect URI nesakrīt precīzi

ProMail salīdzina to burtu pa burtam. https://vietne.lv/cb un https://vietne.lv/cb/ ir divas dažādas adreses. Šī ir visbiežākā kļūda.

Tiek uzticēts marķiera paša alg laukam

Vienmēr pieprasiet RS256 no savas konfigurācijas. Marķieris, kas apgalvo alg: none, ir jānoraida.

Tiek izlaista state pārbaude

Bez tās uzbrucējs var pabeigt pieteikšanos upura pārlūkā un piesaistīt savu ProMail kontu upura sesijai.

Client Secret nonāk JavaScript kodā

Tas drīkst atrasties tikai uz servera. Viss, kas ir pārlūka kodā, ir publisks.

PKCE netiek izmantots

ProMail to pieprasa. Pieprasījumi bez code_challenge tiek noraidīti.

Lietojiet vienādu tekstu un izskatu, lai lietotāji pogu atpazītu visās vietnēs.

<a href="/promail-login" class="promail-btn">
  <img src="https://promail.lv/img/promail-logo.webp" alt="" width="20" height="20">
  <span>Pieteikties ar 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>

Atsevišķas testa vides nav. Reģistrējiet otru lietotni ar http://localhost atgriešanās adresi — localhost ir vienīgā adrese, kas atļauta bez https — un pārbaudiet integrāciju pirms palaišanas reālajā vietnē.