Logowanie jednokrotne

Shayan TaslimZaktualizowano

Logowanie jednokrotne (SSO) zastępuje domyślny proces logowania na publicznej tablicy. Gdy odwiedzający klikną Zaloguj się, UserJot przekieruje ich do Twojego punktu końcowego uwierzytelniania, a Ty przekierujesz ich z powrotem, używając podpisanego tokenu JWT HS256.

Tryby logowania na tablicy (Domyślne, SSO i Wyłączone) wymagają planu Professional.

Włącz SSO

  1. Otwórz Ustawienia → Logowanie.

  2. W sekcji Uwierzytelnianie ustaw opcję Logowanie na tablicy na SSO.

  3. W oknie Włącz SSO wpisz adres URL przekierowania HTTPS i kliknij Włącz SSO. Adres URL możesz później edytować w sekcji Adres URL przekierowania SSO (aby całkowicie usunąć adres URL przekierowania, najpierw wyłącz Logowanie do tablicy przez SSO).

  4. Skopiuj identyfikator projektu i tajny klucz projektu z sekcji Klucze tajne.

Adres URL przekierowania musi używać protokołu https:// (podczas testowania lokalnie użyj tunelu HTTPS).

Tryby logowania na tablicy

  • Domyślne: Odwiedzający logują się za pomocą standardowych kont UserJot.

  • SSO: Kliknięcie Zaloguj się przekierowuje odwiedzających do punktu końcowego SSO. Zwykłe konta użytkowników końcowych UserJot nie mogą logować się bezpośrednio, gdy SSO jest aktywne (przeglądarki z istniejącą sesją UserJot spoza zespołu są traktowane jako anonimowe na tablicy obsługującej wyłącznie SSO, a nie jako goście). Właściciele i administratorzy obszaru roboczego mogą logować się za pomocą kont UserJot lub przez przekierowanie SSO (przy SSO ich istniejąca rola w zespole jest zachowywana, traits i companies są synchronizowane, a zarządzane z poziomu panelu nazwa, awatar i adres e-mail pozostają bez zmian).

  • Wyłączone: Całkowicie ukrywa przycisk Zaloguj się. W przypadku otwartych tablic połącz tę opcję z ustawieniem Opinie gości albo wyłącz zgłoszenia gości, aby publiczna tablica służyła tylko do odczytu.

Jak działa proces przekierowania SSO

Gdy odwiedzający kliknie Zaloguj się, UserJot otworzy wyskakujące okno logowania (a jeśli wyskakujące okna są blokowane, przekieruje do tej samej karty) z skonfigurowanym adresem URL i parametrami zapytania state oraz redirect:

text
https://yourapp.com/userjot/sso?state=OPAQUE_STATE_FROM_USERJOT&redirect=https%3A%2F%2Fapi.userjot.com%2Fauth%2Fsso

Twój punkt końcowy musi jedynie zachować state:

  1. Odczytać parametr zapytania state.

  2. Uwierzytelnij użytkownika w swojej aplikacji (jeśli nie jest jeszcze zalogowany, przeprowadź go przez proces logowania i wróć do tego punktu końcowego z oryginalnym state).

  3. Podpisz token JWT HS256 za pomocą Tajnego klucza projektu.

  4. Przekieruj przeglądarkę na https://api.userjot.com/auth/sso?jwt=<JWT>&state=<STATE>.

Nie modyfikuj state. Można go użyć tylko raz, jest powiązany z sesją przeglądarki i wygasa po 15 minutach.

Ładunek tokenu JWT

Podpisz token za pomocą HS256, używając tajnego klucza projektu (przechowuj klucz tajny na serwerze, nigdy w kodzie po stronie klienta). Przekazanie email łączy z istniejącym kontem UserJot tylko wtedy, gdy adres e-mail tego konta został potwierdzony (lub konto jest już istniejącym członkiem zespołu albo jest powiązane przez externalId).

Roszczenie

Wymagane

Opis

sub

Tak

Stabilny identyfikator użytkownika w Twoim systemie

iss

Tak

Dokładny identyfikator projektu UserJot

aud

Tak

Dokładny ciąg znaków userjot

exp

Tak

Znacznik czasu wygaśnięcia w formacie Unix (zalecane od 5 do 15 minut)

iat

Nie

Znacznik czasu wystawienia w formacie Unix (nie może wykraczać w przyszłość poza dopuszczalną różnicę czasu)

email

Nie

Adres e-mail użytkownika (zalecany do łączenia kont na podstawie adresu e-mail i wysyłania powiadomień)

firstName

Nie

Imię

lastName

Nie

Nazwisko

avatar

Nie

Adres URL awatara

traits

Nie

Płaska mapa klucz-wartość zawierająca ciągi znaków, liczby, wartości logiczne lub null

companies

Nie

Tablica członkostw w firmach

Przykładowy payload:

JavaScript
const now = Math.floor(Date.now() / 1000);

const payload = {
  sub: 'user_123',
  email: 'jane@example.com',
  firstName: 'Jane',
  lastName: 'Doe',
  iss: 'YOUR_PROJECT_ID',
  aud: 'userjot',
  iat: now,
  exp: now + 10 * 60
};

Dane firmy

JSON
{
  "companies": [
    {
      "id": "company_456",
      "name": "Acme Corp",
      "domain": "acme.com",
      "logo": "https://example.com/acme.png",
      "traits": {
        "plan": "enterprise",
        "seats": 42
      }
    }
  ]
}

Przykładowy punkt końcowy (Hono)

JavaScript
import { Hono } from 'hono';
import jwt from 'jsonwebtoken';

const app = new Hono();

const USERJOT_PROJECT_ID = process.env.USERJOT_PROJECT_ID;
const USERJOT_PROJECT_SECRET = process.env.USERJOT_PROJECT_SECRET;
const USERJOT_CALLBACK_URL = 'https://api.userjot.com/auth/sso';

app.get('/userjot/sso', async (c) => {
  const state = c.req.query('state');
  if (!state) return c.text('Missing state', 400);

  const user = await getCurrentUser(c);

  const token = jwt.sign(
    {
      sub: user.id,
      email: user.email,
      firstName: user.firstName,
      lastName: user.lastName,
      iss: USERJOT_PROJECT_ID,
      aud: 'userjot'
    },
    USERJOT_PROJECT_SECRET,
    { algorithm: 'HS256', expiresIn: '10m' }
  );

  const callback = new URL(USERJOT_CALLBACK_URL);
  callback.searchParams.set('jwt', token);
  callback.searchParams.set('state', state);

  return c.redirect(callback.toString());
});

Zmiana tajnego klucza projektu

Jeśli klikniesz Unieważnij klucz w sekcji Ustawienia → Logowanie → Klucze tajne, UserJot natychmiast wygeneruje nowy tajny klucz projektu. Od razu zaktualizuj swój punkt końcowy SSO (a także wszystkie mechanizmy podpisujące Podpisaną tożsamość i Swift SDK), ponieważ tokeny podpisane starym kluczem przestaną natychmiast działać.

Rozwiązywanie problemów

W domyślnym przepływie z wyskakującym oknem błędy callbacku są przekazywane do tablicy i wyświetlane w oknie modalnym logowania. Jeśli przeglądarka przekieruje do tej samej karty (na przykład gdy wyskakujące okna są blokowane), UserJot przekieruje z powrotem do tablicy z parametrem zapytania sso_error:

Kod błędu

Znaczenie

invalid_state

Wartość state była nieobecna, zmodyfikowana, wygasła (po ponad 15 minutach) lub została już użyta.

invalid_token

Niezgodność podpisu, nieprawidłowe iss/aud, brak sub/exp lub wygasły token JWT.

sso_disabled

Opcja Logowanie na tablicy nie jest już ustawiona na SSO.

config_error

Konfiguracja SSO obszaru roboczego jest niekompletna (brakuje adresu URL przekierowania lub tajnego klucza).

invalid_return_to

Nie udało się zweryfikować adresu URL powrotu po zalogowaniu.

auth_failed / session_error

Uwierzytelnianie lub utworzenie sesji na serwerze nie powiodło się.

Czy ten artykuł odpowiedział na Twoje pytanie?