Gdy czytelnik, który nie jest zalogowany, otwiera Twoje centrum pomocy, Notiondesk przekierowuje go na stronę Twojej aplikacji, czyli adres URL logowania jednokrotnego (SSO). Ta strona loguje go za pomocą Messengera lub przekierowania z Twojego serwera, a następnie trafia z powrotem na żądaną stronę bez ponownego logowania.
Zanim zaczniesz
- Centrum pomocy korzysta z trybu dostępu dla kont gości .
- Masz tajny klucz aplikacji. Utwórz go w Ustawieniach > Dostęp , na karcie tajny klucz aplikacji . Jest on wyświetlany tylko raz, więc zapisz go na serwerze, na przykład w
NOTIONDESK_APP_SECRET.
- Twój serwer może podpisać token użytkownika. Identyfikuj zalogowanych użytkowników w Notiondesk Messenger wyjaśnia działanie tokena. W Ustawieniach > Widżet , karta informacji o użytkowniku synchronizacji zawiera kod podpisu w Node.js, Pythonie, PHP i Ruby, z wypełnionym polem
site_uuid. Przechowujsite_uuidrównież na swoim serwerze, na przykład wNOTIONDESK_SITE_UUID.
Krok 1: Dodaj adres URL logowania jednokrotnego
- Przejdź do Ustawienia > Dostęp .
- W sekcji Kontrola dostępu ustaw Tryb dostępu na Konta gości . Zostanie on zapisany natychmiast po wybraniu tej opcji.
- W polu SSO URL wprowadź adres strony swojej aplikacji, która loguje czytelników, na przykład
https://app.example.com/help-sso.
- Kliknij Zapisz zmiany .
Adres URL logowania jednokrotnego musi zaczynać się od https://, zawierać nazwę domeny (nie localhost) i prowadzić do strony aplikacji, a nie centrum pomocy. Jeśli centrum pomocy znajduje się w Twojej domenie, skorzystaj z usług innego hosta lub tego samego hosta spoza ścieżki do centrum pomocy: z centrum pomocy pod adresem example.com/help, example.com/login będzie działać.
Gdy Notiondesk kieruje czytelnika na Twój adres URL logowania jednokrotnego (SSO), zachowuje Twój własny ciąg zapytania i dodaje return_to, pełny adres strony centrum pomocy, o którą prosił czytelnik. Dodaje również dwa parametry używane przez Messengera. Pozostaw je w adresie URL.
Krok 2: Zaloguj czytelników na swojej stronie logowania jednokrotnego (SSO)
Wybierz opcję, która pasuje do Twojej aplikacji. Obie używają tego samego tokenu użytkownika.
Opcja A: z Messengerem
Użyj tej opcji, jeśli Twoja aplikacja już korzysta z Messengera. Na stronie logowania jednokrotnego (SSO) załaduj Messengera z tokenem użytkownika dla zalogowanego użytkownika. Messenger loguje czytelnika do centrum pomocy i odsyła go z powrotem do żądanej strony. Nie ma potrzeby wywoływania niczego innego.
Upewnij się, że Twoja strona SSO:
- Najpierw zaloguj użytkownika do aplikacji. Użytkownik bez tokena użytkownika nie zostanie zalogowany do centrum pomocy.
- Ładuje komunikator centrum pomocy, z którego przyszedł czytelnik, wraz z tokenem podpisanym tajnym kluczem aplikacji tego centrum pomocy.
- Podpisuje token podczas ładowania strony, z wygaśnięciem po godzinie lub krócej. Późniejsze wygaśnięcie jest odrzucane.
- Otwiera się jako normalna strona, a nie w ramce i nie ustawia opcji
apiUrlprogramu Messenger.
- Zachowuje pełny adres, z którego nastąpiło otwarcie. Jeśli logowanie najpierw przekieruje użytkownika na inną stronę lub kartę, przekieruj go z powrotem na ten sam adres ze wszystkimi parametrami, zanim załaduje się Messenger.
Dokumentacja pakietu Messenger SDK omawia instalacje React, Vue i znaczników skryptu w sekcji logowania w Centrum pomocy .
Opcja B: z przekierowaniem z Twojego serwera
Użyj tej opcji, jeśli Twoja aplikacja nie obsługuje Messengera lub wolisz logować czytelników na swoim serwerze.
- Na stronie logowania SSO odczytaj
return_toz adresu i zachowaj go podczas logowania.
- Na swoim serwerze podpisz token użytkownika zalogowanego za pomocą swojego tajnego klucza aplikacji.
- Przekieruj przeglądarkę do
https://help.example.com/private/sso/jwt?jwt=TOKEN&return_to=RETURN_TO, używając domeny swojego centrum pomocy, tokena ireturn_to, obie wartości zakodowane w adresie URL. W centrum pomocy pod adresemexample.com/helpadres zaczyna się odhttps://example.com/help/private/sso/jwt.
Oto przykład w Node.js z Express. requireLogin oznacza własne sprawdzenie logowania: wysyła niezalogowanego użytkownika na stronę logowania, a następnie z powrotem na ten adres ze swoim ciągiem zapytania.
Pamiętaj o tych zasadach:
const jwt = require('jsonwebtoken');
const HELP_CENTER_URL = 'https://help.example.com';
app.get('/help-sso', requireLogin, (req, res) => {
const now = Math.floor(Date.now() / 1000);
const token = jwt.sign(
{
type: 'site_contact_app',
iat: now,
exp: now + 300,
user_id: String(req.user.id),
site_uuid: process.env.NOTIONDESK_SITE_UUID,
email: req.user.email,
name: req.user.name,
},
process.env.NOTIONDESK_APP_SECRET,
{ algorithm: 'HS256' },
);
const target = new URL(`${HELP_CENTER_URL}/private/sso/jwt`);
target.searchParams.set('jwt', token);
if (req.query.return_to) {
target.searchParams.set('return_to', req.query.return_to);
}
res.redirect(target.toString());
});- Podpisz nowy token dla każdego przekierowania. Token loguje czytelnika tylko raz.
- Daj mu krótki czas wygaśnięcia. Wystarczy 5 minut, a ponad godzina zostanie odrzucona. Utrzymuj synchronizację zegara serwera: dopuszczalna jest różnica do 60 sekund.
- Rozmiar tokena nie powinien przekraczać 8 KB, więc
custom_attributespowinien być niewielki.
- Przekaż
return_toz powrotem bez zmian. Bez niego lub z adresem spoza centrum pomocy, czytelnik trafi na stronę główną centrum pomocy.
- Przekieruj z serwera. Nigdy nie umieszczaj tego linku w e-mailu, ponieważ token znajduje się w adresie.
Możesz również kierować użytkowników bezpośrednio na ten adres z aplikacji bez adresu URL logowania jednokrotnego, na przykład za pomocą linku Pomoc w menu aplikacji. Ustaw return_to na stronę centrum pomocy, którą chcesz, aby otworzyli.
Krok 3: Przetestuj
- Otwórz okno przeglądarki w trybie prywatnym i przejdź do strony centrum pomocy, która wymaga zalogowania.
- Sprawdź, czy trafiłeś na adres URL logowania jednokrotnego, zaloguj się do aplikacji i wróć na tę samą stronę centrum pomocy, będąc zalogowanym.
Jeśli to nie zadziała, sprawdź token podpisany przez Twoją aplikację:
- W Ustawieniach > Dostęp , w sekcji Adres URL logowania jednokrotnego (SSO) kliknij Sprawdź token logowania . Pojawi się on po zapisaniu adresu URL logowania jednokrotnego (SSO).
- Wklej token, a następnie kliknij „Sprawdź token” . Zobaczysz, czy Twoje centrum pomocy go akceptuje i dlaczego. Token jest sprawdzany i nigdy nie jest przechowywany.

Wybierz, kiedy czytelnicy będą przechodzić do Twojego adresu URL logowania jednokrotnego
Wymagaj logowania , przełącznik nad adresem URL logowania jednokrotnego (SSO) , jest domyślnie włączony. Po jego włączeniu każdy niezalogowany czytelnik po otwarciu Centrum pomocy przejdzie na Twój adres URL logowania jednokrotnego (SSO).
Po jej wyłączeniu każdy będzie mógł przeglądać Twoje centrum pomocy, a na Twój adres URL logowania SSO będą kierowani tylko wybrani czytelnicy:
- Czytelnicy, którzy otwierają artykuł wymagający zalogowania.
- Czytelnicy, którzy klikną link do centrum pomocy kończący się na
nd_sign_in=1, na przykładhttps://help.example.com/en/articles/billing?nd_sign_in=1. Dodaj go do linków do centrum pomocy w swojej aplikacji.
- Czytelnicy, którzy klikną opcję Kontynuuj korzystanie ze swojego konta na stronie logowania w centrum pomocy.
Zaproszeni goście nadal będą mogli wybrać opcję Użyj adresu e-mail i hasła na stronie logowania.
Połącz czytelników z zaproszonymi przez Ciebie kontami gości
Token dla użytkownika, którego nigdy nie zaprosiłeś, rejestruje go jako nowego czytelnika. Aby przyznać użytkownikowi dostęp i rolę konta gościa zaproszonego przez e-mail:
- Dodaj
emailużytkownika do tokena od momentu jego pierwszej identyfikacji. Użytkownik zidentyfikowany po raz pierwszy bez tego elementu będzie miał osobny czytnik, bez dostępu do konta gościa, nawet jeśli dodasz adres e-mail później.
- Jeśli Twoja aplikacja nie zweryfikowała adresu e-mail użytkownika, wyślij
email_verified: false. Ten użytkownik nie jest powiązany z kontem gościa. Jeśli pominiesz ten adres, adres e-mail zostanie uznany za zweryfikowany. Wyślij go jakotruelubfalse, a nie jako tekst: wartość taka jak"true"zostanie uznana zafalse.
- Konto gościa jest powiązane z jednym kontem
user_id. Drugi użytkownik, który loguje się przy użyciu tego samego adresu e-mail, ma osobny czytnik.
Jeśli zaproszenie gościa jest jeszcze w trakcie realizacji, zostanie automatycznie zaakceptowane.
Rozwiązywanie problemów
| Problem | Przyczyna | Naprawić |
|---|---|---|
| Czytelnik trafia na stronę logowania z komunikatem: „Nie udało się zalogować automatycznie. Spróbuj ponownie lub zaloguj się poniżej”. | Token został odrzucony: wygasł, był już używany, wygasa ponad godzinę wcześniej lub został podpisany innym tajnym kluczem aplikacji | Uruchom Sprawdź token logowania i podpisz nowy token dla każdego przekierowania |
| Czytelnik pozostaje na Twojej stronie SSO | W programie Messenger nie było tokena użytkownika lub był on nieprawidłowy, adres utracił swoje parametry podczas logowania, strona znajduje się w ramce lub ustawiono apiUrl | Uruchom opcję Sprawdź token logowania i sprawdź listę w opcji A |
| Czytelnik jest zalogowany, ale trafia na stronę główną | return_to brakowało lub nie jest stroną Twojego centrum pomocy | Przekaż return_to z powrotem bez zmian |
| Czytelnicy nigdy nie są kierowani na Twój adres URL SSO | Nie zapisano adresu URL SSO lub opcja Wymagaj logowania jest wyłączona | Zapisz adres URL logowania jednokrotnego, a następnie dodaj nd_sign_in=1 do linków w centrum pomocy lub włącz opcję Wymagaj logowania |
| „Wprowadź adres URL zaczynający się od https://” podczas zapisywania | Adres URL logowania jednokrotnego nie jest adresem https:// | Użyj adresu https:// strony swojej aplikacji |
| „Wejdź na stronę swojej aplikacji, a nie do centrum pomocy” podczas zapisywania | Adres URL logowania jednokrotnego znajduje się w adresie Twojego centrum pomocy | Użyj innego hosta lub ścieżki spoza centrum pomocy |
| Sprawdź, czy token logowania wyświetla komunikat „Ten token nie jest jeszcze ważny”. | iat jest w milisekundach lub zegar serwera jest do przodu | Użyj sekund i zsynchronizuj zegar serwera |
| Czytelnik nie ma dostępu do zaproszonego przez Ciebie konta gościa | Token nie miał email za pierwszym razem lub email_verified nie jest true | Zobacz powyżej „Połącz czytelników z zaproszonymi przez Ciebie kontami gości” |
Często zadawane pytania
Czy czytelnicy logują się dwa razy?
Nie. Czytelnicy zalogowani do Twojej aplikacji przechodzą przez Twój adres URL logowania jednokrotnego i wracają zalogowani, bez logowania Notiondesk.
Którą opcję powinienem wybrać?
Opcja A, jeśli Twoja aplikacja już uruchamia Messengera na kontrolowanej przez Ciebie stronie. Opcja B, jeśli nie działa lub jeśli logujesz się na swoim serwerze.
Czy czytelnicy nadal mogą logować się za pomocą adresu e-mail i hasła?
Tak. Zaproszeni goście mogą wybrać opcję Użyj adresu e-mail i hasła na stronie logowania w centrum pomocy.
Jak długo czytelnik pozostaje zalogowany?
Do 12 godzin. Wylogowanie się z aplikacji nie powoduje wylogowania z Centrum pomocy, więc pamiętaj o tym na komputerach współdzielonych.
Kto może zmienić adres URL logowania jednokrotnego?
Właściciele, administratorzy i redaktorzy obszarów roboczych.
Jak wyłączyć logowanie jednokrotne?
Wyczyść pole adresu URL logowania jednokrotnego i kliknij Zapisz zmiany . Czytelnicy zalogują się, podając swój adres e-mail i hasło.