Identiteettivarmistus

Ilman identiteettivarmistusta kuka tahansa kävijä voi kutsua AihioWidget('identify', { user_id: '…' }) selaimen kehittäjätyökalusta millä käyttäjätunnuksella tahansa. Varmistus sitoo istunnon palvelimesi allekirjoittamaan salaisuuteen: Aihio tietää, että kutsuja on oikeasti kirjautunut käyttäjä.

Aihio tukee kahta menetelmää: HMAC-käyttäjätiivistettä ja JWT HS256 -tokenia.

Mistä salaisuus löytyy

Avaa chatbotin Julkaise-näkymä ohjauspaneelissa. Sivulla on Identiteetin varmennus -osio chat-widgetin upotuskoodin vieressä. Paina Luo salaisuus ja kopioi arvo heti talteen: se näytetään vain kerran. Salaisuus näyttää esimerkiksi tältä: aihio_idv_….

Tallenna salaisuus palvelimesi ympäristömuuttujaksi (esim. AIHIO_IDENTITY_SECRET). Älä koskaan sisällytä sitä selainpuolen JavaScript-koodiin tai versiohallintaan.

Menetelmä A: HMAC-käyttäjätiiviste

Laske HMAC-SHA256(salaisuus, user_id) palvelimellasi ja välitä tulos user_hash-kentässä. Tulosteen on oltava pienet kirjaimet sisältävä heksadesimaali. Aihio hylkää isolla kirjoitetun heksan.

Kaikki alla olevat esimerkit tuottavat oikean muodon oletuksena.

Node.js

const crypto = require('crypto');

function computeUserHash(secret, userId) {
  return crypto.createHmac('sha256', secret).update(userId).digest('hex');
}

Python

import hmac, hashlib

def compute_user_hash(secret: str, user_id: str) -> str:
    return hmac.new(
        secret.encode('utf-8'),
        user_id.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

PHP

function compute_user_hash(string $secret, string $user_id): string {
    return hash_hmac('sha256', $user_id, $secret);
}

Ruby

require 'openssl'

def compute_user_hash(secret, user_id)
  OpenSSL::HMAC.hexdigest('SHA256', secret, user_id)
end

Menetelmä B: JWT HS256 -token

Allekirjoita JWT HS256-algoritmilla chatbotin salaisuudella. exp-väite on pakollinen: Aihio hylkää tokenin ilman sitä. Kellopoikkeama on 30 sekuntia.

Suositeltu tokenin elinikä on 1 tunti (exp = iat + 3600). Älä myönnä yli 24 tunnin tokeneita.

Tuetut JWT-väitteet

Vain HS256 hyväksytään. RS256-, ES256- tai alg: none -tokeneja ei hyväksytä.

Allekirjoita JWT palvelimella

Allekirjoita token chatbotin salaisuudella HS256-algoritmilla. Aseta exp (suositus 1 tunti). custom_attributes on vapaaehtoinen.

Node.js (jsonwebtoken)

Asennus: npm install jsonwebtoken

const jwt = require('jsonwebtoken');

function signIdentityToken(secret, user) {
  return jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      custom_attributes: { plan: user.plan },
    },
    secret,
    { algorithm: 'HS256', expiresIn: '1h' },
  );
}

Ruby on Rails (jwt-kirjasto)

Asennus: bundle add jwt

require 'jwt'

def sign_identity_token(secret, user)
  payload = {
    user_id: user.id,
    email: user.email,
    name: user.name,
    custom_attributes: { plan: user.plan },
    exp: Time.now.to_i + 3600,
  }
  JWT.encode(payload, secret, 'HS256')
end

Django / Python (PyJWT)

Asennus: pip install PyJWT

import time
import jwt

def sign_identity_token(secret: str, user) -> str:
    payload = {
        'user_id': user.id,
        'email': user.email,
        'name': user.name,
        'custom_attributes': {'plan': user.plan},
        'exp': int(time.time()) + 3600,
    }
    return jwt.encode(payload, secret, algorithm='HS256')

PHP (firebase/php-jwt)

Asennus: composer require firebase/php-jwt

use Firebase\JWT\JWT;

function sign_identity_token(string $secret, $user): string {
    $payload = [
        'user_id' => $user->id,
        'email' => $user->email,
        'name' => $user->name,
        'custom_attributes' => ['plan' => $user->plan],
        'exp' => time() + 3600,
    ];
    return JWT::encode($payload, $secret, 'HS256');
}

Go (golang-jwt)

Asennus: go get github.com/golang-jwt/jwt/v5

import (
    "time"

    "github.com/golang-jwt/jwt/v5"
)

func SignIdentityToken(secret string, user User) (string, error) {
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
        "user_id":           user.ID,
        "email":             user.Email,
        "name":              user.Name,
        "custom_attributes": map[string]any{"plan": user.Plan},
        "exp":               time.Now().Add(time.Hour).Unix(),
    })
    return token.SignedString([]byte(secret))
}

Java (jjwt)

Asennus (Maven): io.jsonwebtoken:jjwt-api, jjwt-impl, jjwt-jackson (runtime).

import io.jsonwebtoken.Jwts;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.Map;

String signIdentityToken(String secret, User user) {
    SecretKeySpec key = new SecretKeySpec(
        secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    return Jwts.builder()
        .claim("user_id", user.getId())
        .claim("email", user.getEmail())
        .claim("name", user.getName())
        .claim("custom_attributes", Map.of("plan", user.getPlan()))
        .expiration(new Date(System.currentTimeMillis() + 3_600_000))
        .signWith(key)
        .compact();
}

Stripe-tilien välittäminen (tuleva ominaisuus)

Kirjoittamalla stripe_accounts-taulukon JWT-tokeniin voit liittää käyttäjään Stripe-asiakastiedot. Varmennettu identiteetti toimii tulevien identiteettisidonnaisten toimintojen pohjana, jotka hakevat tilaukset ja laskut ilman erillistä tunnistautumista.

jwt.sign(
  {
    user_id: user.id,
    email: user.email,
    stripe_accounts: [{ label: 'Pääasiakkuus', stripe_id: 'cus_xxx' }],
    exp: Math.floor(Date.now() / 1000) + 3600,
  },
  secret,
  { algorithm: 'HS256' },
);

Identiteetin välittäminen widgetille

Laske arvo palvelimella ja injektoi se sivulle. Kutsu sitten identify:

// Menetelmä A: HMAC-käyttäjätiiviste
window.AihioWidget('identify', {
  user_id: currentUser.id, // 'externalId' hyväksytään myös aliaksena
  email: currentUser.email,
  name: currentUser.name,
  user_hash: '{{ palvelimelta_laskettu_tiiviste }}',
});

// Menetelmä B: JWT-token
window.AihioWidget('identify', {
  token: '{{ palvelimelta_allekirjoitettu_jwt }}',
});

identify-kutsun voi tehdä milloin tahansa init-kutsun jälkeen. Jos kutsut sitä ennen kuin bundle on latautunut, komento asetetaan jonoon ja suoritetaan automaattisesti käynnistyksen yhteydessä.

Tyhjennä identiteetti uloskirjautumisen yhteydessä:

window.AihioWidget('resetUser');

Salaisuuden kierrätys

Salaisuuden kierrätys ei välittömästi mitätöi vanhaa salaisuutta. Edellinen salaisuus on voimassa 24 tuntia kierrätyksen jälkeen. Tämä vastaa Stripen webhook-salaisuuden kierrätysmallia: voit päivittää allekirjoituskoodin ympäristöihin ennen kuin vanha salaisuus vanhenee.

1. Kierrätä salaisuus

   Paina Kierrätä salaisuus Julkaise-näkymän Identiteetin varmennus -osiossa.

2. Päivitä ympäristömuuttuja

   Päivitä AIHIO_IDENTITY_SECRET palvelimesi ympäristöön uudella arvolla.

3. Ota muutos käyttöön

   Ota uusi ympäristömuuttuja käyttöön. Vanha salaisuus jatkaa istuntojen varmennusta rinnakkain 24 tunnin ajan.

4. Odota 24 tuntia

   24 tunnin kuluttua vanha salaisuus lakkaa toimimasta. Holvimerkintä säilytetään, mutta sitä ei enää käytetä varmennuksessa.

Pakota identiteettivarmistus

Oletuksena varmistus on avoin (fail-open). Voit ottaa pakotuksen käyttöön chatbotin Julkaise → Suojaus -välilehdeltä.

• Pakota identiteettivarmistus. Pyyntö, joka väittää identiteettiä (user_id/external_id, email, token tai user_hash) ilman validia allekirjoitusta, hylätään HTTP 403:lla. Anonyymit kävijät voivat silti keskustella.
• Vaadi tunnistautuminen (tiukka). Jokainen varmistamaton pyyntö hylätään, myös anonyymit.

Kun pakotus on päällä, keskustelu sidotaan varmennettuun external_id-tunnisteeseen. Uudelleenkäytetty reference_id, jonka tallennettu identiteetti ei vastaa varmennettua tokenia, aloittaa uuden keskustelun sen sijaan että liittyisi vanhaan. Näin yksi kävijä ei voi jatkaa toisen kävijän yksityistä keskustelua.

Pakotus avautuu vasta, kun Aihio on nähnyt vähintään yhden validin tokenin, joten et voi lukita itseäsi ulos ottamalla sen käyttöön ennen kuin integraatiosi on toiminnassa.

Turvallinen yhteys ja istunnon kesto

• Vain turvallinen yhteys. Kun tämä on päällä, chat-widget lähettää identiteettiotsikot ja tallentaa identiteetin vain HTTPS-yhteydellä. Tavallisella HTTP-sivulla se ei lähetä identiteettiä, ja palvelin hylkää varmennuksen.
• Istunnon kesto. Aseta tokenin suurin hyväksytty ikä (60 sekunnista 30 päivään). Chat-widget tyhjentää tallennetun identiteetin iän ylittyessä, ja palvelin hylkää rajaa vanhemman tokenin, vaikka sen oma exp olisi yhä voimassa.

Käyttöönottotapa: toiminto avoimena (fail-open)

Nykyinen toteutus on avoin käyttöönottoa varten: jos allekirjoitusta ei toimiteta tai varmennus epäonnistuu, istunto jatkuu identity_verified = false -tilassa eikä sitä hylätä.

Tämä tarkoittaa, että varmistamaton user_id tai sähköposti hyväksytään näyttövihjeinä, mutta teknisesti hyökkääjän muutettavissa olevia arvoja. Käsittele identiteettitietoja luotettavina vain kun keskustelun identity_verified-lippu on true.

Allekirjoitetut vs allekirjoittamattomat tiedot

Vain JWT:n sisällä allekirjoitetut tiedot ovat varmennettuja ja luotettavia. Kaikki muu on näyttövihje, jonka lähettäjä voi väärentää.

HMAC-käyttäjätiiviste (tapa A) varmentaa vain external_id-arvon. Jos haluat luottaa email-, name- tai mukautettuihin kenttiin, allekirjoita ne JWT:n sisällä (tapa B). Lähettäjän antamat kentät hyväksytään näyttövihjeinä. Niitä ei koskaan tallenneta varmennettuina, ja keskustelun identity_verified-lippu pysyy arvossa false, ellei validia allekirjoitusta ole.

Tietoturvatarkistuslista

• Tallenna chatbotin salaisuus yksinomaan palvelimelle. Älä sisällytä sitä selainpuolen JavaScript-koodiin tai versiohallintaan.
• Aseta exp jokaiseen JWT-tokeniin (suositus 1 h).
• Kierrätä salaisuus heti, jos se paljastuu (Julkaise-näkymän Identiteetin varmennus -osion kautta).
• Tarkista identity_verified = true toimintokäsittelijöissäsi ennen tilitasoisen datan palauttamista.
• Käytä HMAC-funktiosi oletustulosteen pieniä kirjaimia sisältävää heksadesimaalia.