Ondertekende identiteit

Shayan TaslimBijgewerkt:

Een gewone uj.identify-aanroep komt vanuit de browser, dus iedereen kan die aanpassen. Ondertekende identiteit voorkomt spoofing: je server ondertekent een kortlevende HS256-JWT die bewijst wie de gebruiker is, en de widget geeft dat token door aan UserJot.

Alles in het token (gebruikers-ID, e-mailadres, naam, avatar, kenmerken en bedrijven) wordt als geverifieerd beschouwd.

Wanneer heb je dit nodig?

  • Je wilt verifiëren dat feedback, stemmen en gesprekken afkomstig zijn van het echte ingelogde account.

  • Je wilt dat klanten hun eigen feedbackberichten en reacties in de widget kunnen bewerken en verwijderen (sessies zonder handtekening uj.identify kunnen geen content in de widget bewerken of verwijderen).

  • Je hebt Ondertekende tokens verplichten ingeschakeld in Instellingen → Inloggen (beschikbaar bij Starter- en Professional-abonnementen zodra Automatisch inloggen is ingeschakeld). Hierdoor worden niet-ondertekende identify-aanroepen geweigerd en moeten bedrijfs lidmaatschappen ook in het ondertekende token zijn opgenomen (niet-ondertekende client-side companies worden genegeerd, met een waarschuwing via UNSIGNED_COMPANY_IGNORED).

  • Een workspacebeheerder of -eigenaar gebruikt de widget. Niet-ondertekende identificatie wordt nooit geaccepteerd voor accounts met verhoogde rechten. Een ondertekend token past hun kenmerken en bedrijven toe; hun naam, avatar en e-mailadres worden beheerd in het dashboard en leveren een PRIVILEGED_PROFILE_IGNORED-waarschuwing op als ze worden meegestuurd.

Note

Als je product zowel de webwidget als de Swift SDK gebruikt, wordt verificatie voor beide afgedwongen wanneer je Ondertekende tokens vereisen inschakelt. De webwidget gebruikt een HS256-JWT (token), terwijl de Swift SDK een HMAC-SHA256 signature gebruikt, ondertekend met hetzelfde workspacegeheim.

1. Maak het token aan op je server

Onderteken een JWT met HS256 en je workspacegeheim. Je vindt zowel de Project-ID als het Projectgeheim onder Instellingen → Inloggen → Geheimen.

Onderteken nooit tokens in de browser. Bewaar het geheim op je server.

Vereiste claims

Claim

Waarde

sub

De stabiele ID van de gebruiker in je systeem. Verplicht.

iss

Je UserJot Project ID. Verplicht.

aud

De exacte tekenreeks userjot. Verplicht.

iat

Tijdstempel van uitgifte in Unix-seconden. Verplicht.

exp

Vervaltijdstip in Unix-seconden. Verplicht. Maximaal 1 uur (3600 seconden) na iat.

Optionele geverifieerde claims

Je kunt ook email, firstName, lastName, avatar, traits en companies opnemen. Elke vermelding in companies ondersteunt:

JSON
{
  "companies": [
    {
      "id": "acme",
      "name": "ACME Inc.",
      "domain": "acme.com",
      "logo": "https://acme.com/logo.png",
      "traits": { "plan": "enterprise" }
    }
  ]
}

Servervoorbeelden

Node.js

JavaScript
import jwt from 'jsonwebtoken';

export function createUserJotToken(user, secret, projectId) {
  return jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: projectId,
      aud: 'userjot'
    },
    secret,
    { algorithm: 'HS256', expiresIn: '1h' }
  );
}

Python

Python
import time
import jwt

def create_userjot_token(user, secret, project_id):
    now = int(time.time())
    return jwt.encode(
        {
            "sub": user["id"],
            "email": user["email"],
            "firstName": user["first_name"],
            "lastName": user["last_name"],
            "iss": project_id,
            "aud": "userjot",
            "iat": now,
            "exp": now + 3600,
        },
        secret,
        algorithm="HS256",
    )

PHP

PHP
<?php

use Firebase\JWT\JWT;

function createUserJotToken(array $user, string $secret, string $projectId): string
{
    $now = time();

    return JWT::encode([
        'sub' => $user['id'],
        'email' => $user['email'],
        'firstName' => $user['firstName'],
        'lastName' => $user['lastName'],
        'iss' => $projectId,
        'aud' => 'userjot',
        'iat' => $now,
        'exp' => $now + 3600,
    ], $secret, 'HS256');
}

Ruby

Ruby
require 'jwt'

def create_userjot_token(user, secret, project_id)
  now = Time.now.to_i

  payload = {
    sub: user[:id],
    email: user[:email],
    firstName: user[:first_name],
    lastName: user[:last_name],
    iss: project_id,
    aud: 'userjot',
    iat: now,
    exp: now + 3600
  }

  JWT.encode(payload, secret, 'HS256')
end

Geef bij elke paginalaadbeurt of via een geauthenticeerd backend-eindpunt een nieuw token uit. Omdat tokens maximaal 1 uur geldig zijn, mag je ze niet langer dan dat cachen.

2. Geef het token mee bij het identificeren

Geef de JWT door in het veld token:

JavaScript
uj.identify({
  token: 'TOKEN_FROM_YOUR_SERVER'
});

Je kunt ook user en companies meegeven naast token voor extra niet-geverifieerde velden. Als een veld in beide voorkomt, krijgt het ondertekende token voorrang (tenzij Ondertekende tokens verplichten is ingeschakeld; dan worden niet-ondertekende bedrijven genegeerd). Controleer de verificatie via de geretourneerde promise:

JavaScript
const result = await uj.identify({ token });
result.identityTrust; // 'signed'

Ongeldige tokens worden geweigerd; er wordt niet teruggevallen

Als een token is verlopen, een ongeldige indeling heeft of met het verkeerde geheim is ondertekend, wordt uj.identify afgewezen met IDENTIFY_FAILED in plaats van stilzwijgend terug te vallen op een niet-ondertekende sessie.

Ondertekende identiteit en gesprekken

  • Als een anonieme bezoeker een gastgesprek start en zich later identificeert met een ondertekend token, wordt het gastgesprek overgezet naar het geverifieerde ledenaccount.

  • Gesprekken die met een ondertekende identiteit zijn gestart, blijven beschermd. Als je ze opnieuw opent zonder ondertekende sessie, moet de bezoeker zich verifiëren voordat die de gespreksgeschiedenis kan bekijken.

  • Als je Ondertekende tokens vereisen inschakelt, kunnen anonieme bezoekers nog steeds browsergebonden gastgesprekken starten; hiermee wordt alleen voorkomen dat niet-ondertekende identify-aanroepen aan ledenaccounts worden gekoppeld.

Identiteit wordt meegenomen naar je openbare pagina's

Zodra de bezoeker is geïdentificeerd, geeft de widget de sessie automatisch door aan links naar je openbare UserJot-pagina's (bord, roadmap, changelog of helpcentrum). Schakel Automatisch inloggen in via Instellingen → Inloggen (Starter- of Professional-abonnement) als je wilt dat bezoekers op die pagina's al ingelogd aankomen. Zie Automatisch inloggen.

Problemen oplossen

De aanroep om te identificeren mislukt met IDENTIFY_FAILED

  • Controleer of het token is ondertekend met HS256 en je huidige Projectgeheim.

  • Controleer of iss overeenkomt met je Project-ID en of aud exact gelijk is aan userjot.

  • Controleer of zowel iat als exp aanwezig zijn als Unix-seconden en of exp - iat <= 3600.

  • Controleer of de klok van je server nauwkeurig is (tokens die meer dan 60 seconden in de toekomst zijn uitgegeven, worden geweigerd vanwege de klokafwijking).

Identificatie zonder handtekening werkt niet meer

Ondertekende tokens vereisen is ingeschakeld via Instellingen → Inloggen (wordt weergegeven wanneer Automatisch inloggen is ingeschakeld). Zodra dit is ingeschakeld, moet elke identify-aanroep een geldige ondertekende token bevatten.

Heeft dit je vraag beantwoord?