Podpisana tożsamość

Shayan TaslimZaktualizowano

Zwykłe wywołanie uj.identify pochodzi z przeglądarki, więc każdy może je zmienić. Podpisana tożsamość zapobiega podszywaniu się: serwer podpisuje krótkotrwały token JWT HS256 potwierdzający tożsamość użytkownika, a widżet przekazuje ten token do UserJot.

Wszystkie informacje zawarte w tokenie (identyfikator użytkownika, adres e-mail, imię i nazwisko, awatar, cechy i firmy) są traktowane jako zweryfikowane.

Kiedy tego potrzebujesz

  • Chcesz mieć pewność, że opinie, głosy i rozmowy pochodzą od prawdziwego zalogowanego użytkownika.

  • Chcesz, aby klienci mogli edytować i usuwać własne wpisy z opiniami i komentarze w widżecie (sesje bez podpisu uj.identify nie mogą edytować ani usuwać treści w widżecie).

  • Włączono opcję Wymagaj podpisanych tokenów w Ustawieniach → Logowanie (dostępną w planach Starter i Professional po włączeniu funkcji Automatyczne logowanie), która odrzuca niepodpisane wywołania identify i wymaga również umieszczenia członkostwa w firmach w podpisanym tokenie (ignorując niepodpisane companies po stronie klienta i wyświetlając ostrzeżenie UNSIGNED_COMPANY_IGNORED).

  • Z widżetu korzysta administrator lub właściciel obszaru roboczego. W przypadku kont z uprawnieniami nigdy nie są akceptowane niepodpisane dane identyfikacyjne. Podpisany token ustawia ich cechy i firmy; imię i nazwisko, awatar oraz adres e-mail są nadal zarządzane w panelu i w przypadku ich przesłania zwracane jest ostrzeżenie PRIVILEGED_PROFILE_IGNORED.

Note

Jeśli Twój produkt korzysta zarówno z widżetu internetowego, jak i z Swift SDK, włączenie opcji Wymagaj podpisanych tokenów wymusza weryfikację w obu przypadkach. Widżet internetowy używa tokenu JWT HS256 (token), natomiast Swift SDK używa HMAC-SHA256 signature podpisanego tym samym sekretem obszaru roboczego.

1. Utwórz token na swoim serwerze

Podpisz token JWT algorytmem HS256, używając sekretu obszaru roboczego. Identyfikator projektu i Sekret projektu znajdziesz w Ustawieniach → Logowanie, w sekcji Sekrety.

Nigdy nie podpisuj tokenów w przeglądarce. Przechowuj sekret na serwerze.

Wymagane pola

Deklaracja

Wartość

sub

Stały identyfikator użytkownika w Twoim systemie. Wymagany.

iss

Identyfikator projektu UserJot. Wymagany.

aud

Dokładny ciąg znaków userjot. Wymagany.

iat

Znacznik czasu wystawienia w sekundach czasu uniksowego. Wymagany.

exp

Znacznik czasu wygaśnięcia w sekundach czasu uniksowego. Wymagany. Maksymalnie 1 godzina (3600 sekund) po iat.

Opcjonalne zweryfikowane pola

Możesz też uwzględnić email, firstName, lastName, avatar, traits i companies. Każdy wpis w companies obsługuje:

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

Przykłady dla serwera

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

Wystawiaj nowy token przy każdym wczytaniu strony lub z uwierzytelnionego punktu końcowego backendu. Ponieważ tokeny wygasają najpóźniej po 1 godzinie, nie przechowuj ich w pamięci podręcznej dłużej.

2. Przekaż token w wywołaniu identify

Przekaż token JWT w polu token:

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

Możesz też przekazać user i companies razem z token, aby dodać niezweryfikowane pola; jeśli pole występuje w obu miejscach, pierwszeństwo ma podpisany token (chyba że włączono opcję Wymagaj podpisanych tokenów, która ignoruje niepodpisane firmy). Potwierdź weryfikację za pomocą zwróconej obietnicy:

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

Nieprawidłowe tokeny są odrzucane — nie następuje powrót do poprzedniego sposobu uwierzytelniania

Jeśli token wygasł, jest nieprawidłowo sformatowany lub został podpisany niewłaściwym sekretem, wywołanie uj.identify zostaje odrzucone z błędem IDENTIFY_FAILED, zamiast po cichu przechodzić na niepodpisaną sesję.

Podpisana tożsamość i konwersacje

  • Jeśli anonimowy użytkownik rozpocznie rozmowę gościnną, a później zidentyfikuje się za pomocą podpisanego tokenu, jego rozmowa gościnna zostanie przeniesiona na zweryfikowane konto użytkownika.

  • Rozmowy rozpoczęte przy użyciu podpisanej tożsamości pozostają chronione. Ponowne otwarcie ich bez podpisanej sesji powoduje wyświetlenie prośby o weryfikację przed pokazaniem historii.

  • Włączenie opcji Wymagaj podpisanych tokenów nadal pozwala anonimowym użytkownikom rozpoczynać gościnne rozmowy powiązane z przeglądarką; zapobiega jedynie przypisywaniu niepodpisanych wywołań identify do kont użytkowników.

Tożsamość jest przenoszona na Twoje strony publiczne

Po zidentyfikowaniu użytkownika widżet automatycznie przekazuje sesję do linków prowadzących do Twoich publicznych stron UserJot (tablicy, roadmapy, dziennika zmian lub centrum pomocy). Aby użytkownicy otwierali te strony już po zalogowaniu, włącz opcję Automatyczne logowanie w Ustawieniach → Logowanie (w planie Starter lub Professional). Zobacz: Automatyczne logowanie.

Rozwiązywanie problemów

Wywołanie identify jest odrzucane z błędem IDENTIFY_FAILED

  • Sprawdź, czy token został podpisany algorytmem HS256 i aktualnym sekretem projektu.

  • Sprawdź, czy iss jest zgodne z identyfikatorem projektu, a aud ma dokładnie wartość userjot.

  • Sprawdź, czy podano zarówno iat, jak i exp jako sekundy czasu uniksowego oraz czy exp - iat <= 3600.

  • Sprawdź, czy zegar serwera jest prawidłowo ustawiony (tokeny wystawione w przyszłości są odrzucane, jeśli różnica czasu przekracza 60 sekund).

Wywołanie identify bez podpisu przestało działać

Opcja Wymagaj podpisanych tokenów jest włączona w Ustawieniach → Logowanie (jest widoczna po włączeniu opcji Automatyczne logowanie). Po jej włączeniu każde wywołanie identify musi zawierać prawidłowy, podpisany token token.

Czy ten artykuł odpowiedział na Twoje pytanie?