SuperTokens, otwarty rdzeń i płatne dodatki

SuperTokens, otwarty rdzeń i płatne dodatki

SuperTokens rozwiązuje uwierzytelnianie w architekturze trzech elementów: osobnej usługi zwanej rdzeniem, biblioteki w Twoim backendzie i biblioteki we frontendzie. Rdzeń jest na licencji Apache 2.0, ale katalog ee w tym samym repozytorium ma licencję zastrzeżoną, a kilka funkcji, po które sięga się dość szybko, siedzi właśnie tam.

Trzy ruchome części zamiast jednej biblioteki

Rdzeń to program w Javie nasłuchujący domyślnie na porcie 3567. Trzyma użytkowników, hasła, sesje i role w bazie danych, którą sam migruje przy starcie. Od wydania 11.0.0 wspierany jest wyłącznie PostgreSQL w wersji minimum 13.0; MySQL i MongoDB zostały usunięte, więc jeśli ktoś pamięta stare wpisy w dokumentacji, dziś już nie działają. Więcej o samej bazie znajdziesz w PostgreSQL.

Druga część to SDK backendowe. Dla Node jest to pakiet supertokens-node, który wystawia w Twojej aplikacji zestaw tras pod wspólnym prefiksem i rozmawia z rdzeniem po HTTP. Każde żądanie do rdzenia niesie nagłówek cdi-version, a jeśli rdzeń ma ustawione api_keys, także nagłówek api-key. Trzecia część to SDK frontendowe: supertokens-auth-react z gotowymi komponentami logowania albo supertokens-web-js, jeśli interfejs piszesz sam.

Dokumentacja wdrożeniowa nazywa rdzeń zaufanym komponentem backendowym i wprost zaleca trzymanie go w sieci prywatnej, dostępnej tylko dla Twojego backendu, nigdy dla przeglądarki. To nie jest ozdobne zalecenie: rdzeń bez klucza API pozwala każdemu, kto go dosięgnie, wylistować i zmodyfikować użytkowników.

Koszt utrzymania takiego układu trzeba policzyć uczciwie. To dodatkowy kontener w Twojej infrastrukturze, dodatkowa baza albo dodatkowy schemat w istniejącej, migracje wykonywane przez rdzeń przy każdym starcie oraz trzy miejsca, w których trzeba pilnować wersji. Biblioteka, która żyje w jednym procesie z Twoją aplikacją, taka jak Better Auth, tego problemu nie ma w ogóle.

Wersje, licencja i zawartość opublikowanych paczek

Licencję sprawdziłem z trzech stron, bo deklaracja w rejestrze pakietów to za mało.

W rejestrze npm pakiet supertokens-node ma najnowszą wersję 24.0.3 opublikowaną 24 lipca 2026 roku, z polem license ustawionym na Apache-2.0. supertokens-auth-react jest w wersji 0.51.3 z 30 lipca 2026 roku, supertokens-web-js w 0.16.0 z 15 sierpnia 2025 roku, a supertokens-website w 20.1.6 z 21 marca 2025 roku, wszystkie z tym samym polem licencji. Na PyPI supertokens-python ma wersję 0.31.3 z 6 maja 2026 roku i deklaruje Apache 2.0 wraz z klasyfikatorem OSI.

W repozytorium plik licencyjny nazywa się LICENSE.md, nie LICENSE, i próba pobrania tej drugiej nazwy kończy się kodem 404. Jego treść jest ciekawsza niż zwykły tekst Apache, bo zaczyna się od podziału: wszystko, co leży w katalogu ee/, podlega osobnemu plikowi ee/LICENSE.md, a reszta jest na Apache 2.0. Ten osobny plik to SuperTokens Enterprise License. Mówi wprost, że oprogramowania z katalogu ee można używać produkcyjnie wyłącznie przy ważnej subskrypcji na odpowiednią liczbę stanowisk, że kopiowanie i modyfikowanie na potrzeby rozwoju i testów jest dozwolone bez subskrypcji, oraz że kopiowanie, publikowanie, dystrybucja i sprzedaż są zakazane. To jest licencja zastrzeżona, nie otwarta, i leży w tym samym drzewie źródeł co reszta.

Trzecie źródło to zawartość opublikowanych paczek, bo tu w innych projektach najczęściej wychodzą niespodzianki. Archiwum supertokens-node-24.0.3.tgz waży około 554 kB, zawiera 1015 wpisów, w tym 397 plików .js, oraz plik package/LICENSE.md z nagłówkiem Apache 2.0 i notą praw autorskich VRAI Labs z 2021 roku. Archiwum supertokens-auth-react w wersji 0.51.3 również ma package/LICENSE.md z tą samą notą, tyle że datowaną na 2020 rok, i 82 pliki .js. Innymi słowy: obie paczki zawierają realny kod i realny plik licencyjny, deklaracje się zgadzają, żadnej atrapy tu nie ma.

Projekt jest aktywny w sposób, który widać w kanale wydań. Daty sprawdziłem pojedynczo, bo tu łatwo o pomyłkę: wpis v12.1.1 nosi datę 13 sierpnia 2026 roku, a v12.1.0 datę 12 sierpnia, czyli dzień wcześniej, a nie ten sam. Za to 6 sierpnia 2026 przyniósł cztery wydania naraz, v12.0.10, v12.0.9, v11.4.7 i v11.3.7, rozłożone na niecałe siedem godzin. Utrzymywanie kilku linii jednocześnie i wypuszczanie poprawek do starszych gałęzi to dobry sygnał dla kogoś, kto nie chce aktualizować rdzenia co miesiąc.

Warto zauważyć jedną rzecz o zależnościach: supertokens-node 24.0.3 ciągnie piętnaście pakietów, w tym twilio w wersji ^4.19.3 i nodemailer w ^8.0.2. Trafiają do node_modules niezależnie od tego, czy wysyłasz SMS albo maile przez te kanały.

Co jest darmowe, a co wymaga płatnej licencji

To jest sedno sprawy i najczęstsza niespodzianka przy wdrożeniu. Lista funkcji objętych licencją komercyjną nie jest kwestią interpretacji, bo siedzi w kodzie rdzenia jako wyliczenie EE_FEATURES. W wydaniu v12.1.1 zawiera wartości: account_linking, multi_tenancy, test, dashboard_login, mfa, security, oauth oraz saml.

Po darmowej stronie zostaje sporo i to jest uczciwa część układu. Logowanie hasłem, logowanie społecznościowe i dowolni własni dostawcy OpenID, logowanie bez hasła magicznym odnośnikiem oraz kodem jednorazowym przez e-mail lub SMS, weryfikacja adresu, resetowanie hasła, zarządzanie sesjami w ciasteczkach, role i uprawnienia, gotowy interfejs logowania i mechanizm nadpisywania funkcji SDK. Panel administracyjny też jest darmowy, ale do trzech kont: stała MAX_NUMBER_OF_FREE_DASHBOARD_USERS w klasie Dashboard ma wartość 3, a próba dodania czwartego konta bez klucza kończy się wyjątkiem FeatureNotEnabledException.

Dwie rzeczy w tym zestawieniu są niewygodne. Po pierwsze, saml jest w wyliczeniu funkcji płatnych, ale na stronie cennika nie pojawia się na liście dodatków z ceną, a w tabeli porównawczej z konkurencją widnieje jako "SAML Login: Yes". Nie da się z materiałów dostawcy odczytać, ile to kosztuje. Po drugie, w kodzie rdzenia leży tablica ENTERPRISE_THIRD_PARTY_IDS z wartościami google-workspaces, okta, active-directory i boxy-saml, używana przy zliczaniu statystyk użycia funkcji płatnych. Jeśli planujesz logowanie firmowe przez Okta albo Active Directory, to jest dokładnie ten obszar, w którym rozliczenie przestaje być bezpłatne.

Dokumentacja funkcji płatnych oznacza je ramką "This feature is only available to paid users" z przyciskiem "View Details". Zawartość tego przycisku renderuje się dopiero w przeglądarce, więc pobranie strony narzędziem wiersza poleceń nie pokaże żadnej ceny. Jeśli chcesz znać liczby, musisz otworzyć stronę cennika.

Klucz licencyjny w praktyce

Klucz podaje się rdzeniowi przez API /ee/license. Metoda PUT z polem licenseKey w ciele zapisuje klucz i od razu synchronizuje listę funkcji, GET zwraca aktualnie ustawiony klucz, a DELETE go usuwa. Wywołanie jest przypisane do aplikacji i można je wykonać tylko z publicznego tenanta.

# ustawienie klucza licencyjnego na rdzeniu
curl -X PUT http://127.0.0.1:3567/ee/license \
  -H 'Content-Type: application/json' \
  -H 'api-key: TWOJ_KLUCZ_API_RDZENIA' \
  -d '{"licenseKey":"..."}'

# sprawdzenie, co rdzen ma zapisane
curl -X GET http://127.0.0.1:3567/ee/license \
  -H 'api-key: TWOJ_KLUCZ_API_RDZENIA'

# usuniecie klucza i powrot do funkcji otwartych
curl -X DELETE http://127.0.0.1:3567/ee/license \
  -H 'api-key: TWOJ_KLUCZ_API_RDZENIA'

Weryfikacja klucza ma dwie ścieżki i różnica między nimi jest istotna przy wdrożeniu odciętym od internetu. Metoda doesLicenseKeyRequireServerQuery sprawdza po prostu, czy klucz rozbity po kropce ma trzy części. Jeśli tak, jest to token JWT i rdzeń weryfikuje go lokalnie kluczem publicznym RSA wkompilowanym w źródła. Jeśli nie, rdzeń wysyła żądanie POST na adres https://api.supertokens.com/0/st/license/check.

Zawartość tego żądania jest jawna w kodzie: telemetryId, licenseKey, superTokensVersion oraz obiekt paidFeatureUsageStats. Ten ostatni niesie liczniki użycia, na przykład user_count dla panelu administracyjnego i statystyki dla MFA, wielodostępności oraz łączenia kont. Stała INTERVAL_BETWEEN_SERVER_SYNC wynosi 3600 * 24 sekund, czyli synchronizacja powtarza się raz na dobę, a INTERVAL_BETWEEN_DB_READS to cztery godziny, po których rdzeń odczytuje ponownie zapisany stan flag. Wynik trafia do bazy pod kluczami LICENSE_KEY i FEATURE_FLAG.

Wniosek praktyczny: hostowanie u siebie nie oznacza automatycznie, że rdzeń nie rozmawia z dostawcą. Przy kluczu w formacie JWT nie rozmawia. Przy kluczu nieprzypominającym JWT wychodzi raz dziennie na zewnątrz i wysyła statystyki użycia razem z identyfikatorem telemetrii. Jeśli pracujesz w sieci bez wyjścia na świat, to jest pytanie do zadania dostawcy przed podpisaniem umowy, a nie po.

Cennik i arytmetyka

Strona cennika rozdziela dwa warianty. W chmurze płacisz 0,02 USD za aktywnego użytkownika miesięcznie, przy czym poniżej pięciu tysięcy takich użytkowników jest bezpłatnie. Wariant samodzielny opisany jest jako darmowy i otwarty bez limitu liczby użytkowników, co odnosi się wyłącznie do funkcji otwartych.

Arytmetykę z przykładów na stronie sprawdziłem i się zgadza. Dla 5000 użytkowników z włączonym łączeniem kont wychodzi (0,02 + 0,005) * 5000 = 125 USD miesięcznie, dla 7000 użytkowników (0,02 + 0,005) * 7000 = 175 USD. Zgadza się też podana wartość 100 USD miesięcznie w przedziale od 1 do 4999 użytkowników, bo tam działa minimum rozliczeniowe dodatku.

Uwaga na próg darmowy: to jest próg skokowy, a nie odliczenie. Przy 4999 użytkownikach podstawa w chmurze kosztuje zero, przy 5000 płacisz 0,02 USD za wszystkich pięć tysięcy, czyli 100 USD, i tak właśnie liczy przykład dostawcy. Druga rzecz to minimum 100 USD miesięcznie przy MFA i przy łączeniu kont. Oznacza ono, że najtańszy scenariusz z MFA na Twoim własnym serwerze, przy pięćdziesięciu użytkownikach, kosztuje 100 USD miesięcznie, czyli 1200 USD rocznie. To bywa zaskoczeniem dla kogoś, kto wybrał SuperTokens właśnie po to, żeby nie płacić za MAU.

Jest też rozbieżność w samej stronie. Kalkulator ma wiersz "Multitenancy" pokazujący 0 USD w obu kolumnach, a lista funkcji płatnych odsyła przy wielodostępności do "See pricing" bez podanej liczby. Wielodostępność jest w EE_FEATURES, więc bez klucza nie zadziała, ale ceny z materiałów dostawcy odczytać się nie da. Sekcja pytań na stronie cennika dodaje, że przy ponad dziesięciu tysiącach aktywnych użytkowników miesięcznie albo ponad pięciu organizacjach jako klientach można negocjować rabat, również bez podanych stawek.

Uruchomienie od zera

Rdzeń najprościej postawić z obrazu kontenera. Obraz w dokumentacji nosi nazwę supertokens/supertokens-postgresql, a plik README projektu obrazu odwołuje się do registry.supertokens.io/supertokens/supertokens-postgresql.

# rdzen z wlasna baza PostgreSQL
docker run -p 3567:3567 -d \
  -e POSTGRESQL_CONNECTION_URI="postgresql://user:pass@db:5432/supertokens" \
  -e API_KEYS="dlugi-losowy-ciag" \
  registry.supertokens.io/supertokens/supertokens-postgresql

# sprawdzenie, czy rdzen wstal
curl http://127.0.0.1:3567/hello

Bez zmiennych POSTGRESQL_USER, POSTGRESQL_PASSWORD, POSTGRESQL_PASSWORD_FILE i POSTGRESQL_CONNECTION_URI rdzeń wstaje na bazie w pamięci. Demo działa, logowanie działa, a po restarcie kontenera nie ma ani jednego użytkownika. Ten sam plik README dodaje, że rdzeń przy starcie czeka na dostępność PostgreSQL nawet do godziny, więc kontener, który wygląda na zawieszony, może po prostu czekać na bazę.

Konfigurację można też podać plikiem. W kontenerze leży on pod ścieżką /usr/lib/supertokens/config.yaml i przyjmuje między innymi takie pola:

# fragment config.yaml rdzenia
port: 3567
host: "0.0.0.0"
api_keys: "dlugi-losowy-ciag"
access_token_validity: 3600          # sekundy
refresh_token_validity: 144000       # minuty, nie sekundy
password_hashing_alg: "BCRYPT"       # albo "ARGON2"
bcrypt_log_rounds: 11
ip_allow_regex: "10\\.0\\..*"
log_level: "INFO"
disable_telemetry: true

Backend inicjalizuje się raz, przy starcie aplikacji. Typ TypeInput w supertokens-node przyjmuje pola supertokens, framework, appInfo, recipeList, telemetry, isInServerlessEnv oraz debug. Pole framework przyjmuje wartości express, fastify, hapi, loopback, koa, awsLambda i custom.

import supertokens from "supertokens-node"
import Session from "supertokens-node/recipe/session"
import EmailPassword from "supertokens-node/recipe/emailpassword"
import Dashboard from "supertokens-node/recipe/dashboard"

supertokens.init({
  framework: "express",
  supertokens: {
    connectionURI: process.env.SUPERTOKENS_CONNECTION_URI!,
    apiKey: process.env.SUPERTOKENS_API_KEY
  },
  appInfo: {
    appName: "code-worlds",
    apiDomain: "https://api.example.com",
    websiteDomain: "https://example.com",
    apiBasePath: "/auth",
    websiteBasePath: "/auth"
  },
  recipeList: [EmailPassword.init(), Session.init(), Dashboard.init()],
  telemetry: false
})

Frontend dostaje niemal identyczny obiekt appInfo, co jest wygodne, bo obie strony muszą się zgadzać co do prefiksów tras. Jeśli budujesz na Next.js, pamiętaj, że apiDomain i websiteDomain będą tym samym adresem.

import SuperTokens from "supertokens-auth-react"
import Session from "supertokens-auth-react/recipe/session"
import EmailPassword from "supertokens-auth-react/recipe/emailpassword"

SuperTokens.init({
  appInfo: {
    appName: "code-worlds",
    apiDomain: "https://api.example.com",
    websiteDomain: "https://example.com",
    apiBasePath: "/auth",
    websiteBasePath: "/auth"
  },
  recipeList: [EmailPassword.init(), Session.init()]
})

Zgodność wersji między rdzeniem a SDK jest realną pułapką przy aktualizacji, bo aktualizujesz trzy rzeczy, a zgodne muszą być wszystkie trzy. Dostawca publikuje tabelę zgodności pod adresem /docs/references/compatibility-table, ale listy wersji ładują się w niej dopiero w przeglądarce. Strona pobrana bez wykonania JavaScriptu pokazuje same nagłówki: "Compatible Backend SDK Versions", "SuperTokens Core Version" i "Compatible Frontend SDK Versions", bez ani jednego numeru. Tabela istnieje, ale nie da się jej sprawdzić skryptem w potoku ciągłej integracji. Mechanizm pod spodem to negocjacja interfejsów: żądania niosą nagłówek cdi-version, a konfiguracja rdzenia ma pola supertokens_max_cdi_version i supertokens_min_cdi_version.

SuperTokens a alternatywy

Miejsce SuperTokens na tej mapie jest dość konkretne. Jeśli głównym wymaganiem jest to, żeby baza użytkowników i hasła nigdy nie opuściły Twojej infrastruktury, a jednocześnie nie chcesz pisać przepływów resetu hasła i rotacji sesji od zera, to jest dobry wybór. Jeśli zależy Ci tylko na tym, żeby nie płacić, Better Auth daje ten sam efekt bez dodatkowego kontenera i bez kategorii funkcji płatnych. Jeśli natomiast liczysz czas zespołu wyżej niż rachunek, gotowe usługi takie jak Clerk, Auth0 czy Kinde oszczędzą Ci całej warstwy operacyjnej, kosztem oddania danych i związania z dostawcą. Osobny przypadek to sprzedaż do dużych firm, gdzie liczy się głównie liczba podłączonych dostawców tożsamości, i tam sensowniej wypada rozliczenie za połączenie w WorkOS.

Przywiązanie do dostawcy w SuperTokens jest niższe niż w usługach zamkniętych, ale nie zerowe. Schemat bazy jest Twój i możesz go odczytać, jednak hasła są zahaszowane algorytmem ustawionym w password_hashing_alg, a przepływy sesji zakładają obecność rdzenia. Migracja do innego rozwiązania to przeniesienie haszy i wymuszenie ponownego zalogowania, nie zwykłe podmienienie biblioteki.

Jedna nazwa z tej kategorii wymaga sprostowania, bo wciąż krąży w poradnikach. Stack Auth, wymieniany kiedyś obok SuperTokens jako otwarta alternatywa dla Clerka, nazywa się dziś Hexclave: repozytorium i domena przekierowują pod nowy szyld, a pakiety @stackframe/* zastąpiła rodzina @hexclave/*. Podział licencji jest tam podobny do tutejszego, czyli klient na MIT i komponenty serwerowe na AGPLv3, ale z dwiema różnicami na niekorzyść: pole license nie istnieje w metadanych sześciu pakietów naraz, a nota o prawach autorskich nadal wskazuje starą nazwę firmy.

Typowe błędy

Pierwszy i najkosztowniejszy: założenie, że hostowanie u siebie oznacza wszystko za darmo. Otwarty jest rdzeń poza katalogiem ee. MFA, łączenie kont, wielodostępność, rola dostawcy OAuth 2.0, SAML i pakiet ochrony przed atakami wymagają klucza również wtedy, gdy prąd do serwera płacisz sam.

Drugi: zostawienie bazy w pamięci. Kontener bez zmiennych POSTGRESQL_* uruchamia się poprawnie i przechodzi testy, a traci dane przy każdym restarcie.

Trzeci: wystawienie rdzenia na świat. Bez api_keys port 3567 daje pełny dostęp do użytkowników. Do tego dochodzą ip_allow_regex i ip_deny_regex, które warto ustawić nawet w sieci prywatnej.

Czwarty: aktualizacja SDK bez rdzenia albo odwrotnie. Nagłówek cdi-version odrzuci niezgodną kombinację, a tabela zgodności nie da się sprawdzić skryptem, więc trzeba to zrobić ręcznie przed wdrożeniem.

Piąty: dodanie czwartego konta do panelu administracyjnego. Stała MAX_NUMBER_OF_FREE_DASHBOARD_USERS wynosi 3, a nadprogramowe konto kosztuje 20 USD miesięcznie.

Szósty: przyjęcie, że weryfikacja licencji jest lokalna. Klucz w formacie JWT weryfikuje się offline, każdy inny powoduje żądanie do api.supertokens.com raz na dobę wraz ze statystykami użycia.

FAQ

Czy hostowanie SuperTokens u siebie jest naprawdę darmowe?

Częściowo. Logowanie hasłem, logowanie społecznościowe, logowanie bez hasła, weryfikacja adresu, sesje, role i uprawnienia oraz panel do trzech kont są bezpłatne bez limitu użytkowników. Funkcje wymienione w wyliczeniu EE_FEATURES wymagają płatnego klucza niezależnie od tego, gdzie stoi rdzeń.

Które dokładnie funkcje wymagają klucza licencyjnego?

W wydaniu v12.1.1 są to account_linking, multi_tenancy, dashboard_login powyżej trzech kont, mfa, security, oauth i saml. Ceny podane wprost dotyczą tylko MFA, łączenia kont i kont panelu. Dla pozostałych dostawca odsyła do kontaktu.

Czy rdzeń łączy się z internetem?

Zależy od formatu klucza. Klucz trzyczłonowy jest tokenem JWT weryfikowanym lokalnie. Każdy inny powoduje wywołanie https://api.supertokens.com/0/st/license/check co dobę, z identyfikatorem telemetrii i licznikami użycia funkcji płatnych. Telemetrię można wyłączyć osobno przez disable_telemetry w konfiguracji rdzenia oraz telemetry: false w SDK.

Czy da się użyć MySQL albo MongoDB?

Nie w bieżących wersjach. Wsparcie dla obu baz zostało usunięte w wydaniu 11.0.0 rdzenia. Obsługiwany jest PostgreSQL od wersji 13.0 wzwyż.

Ile kosztuje najtańszy scenariusz z MFA na własnym serwerze?

Sto dolarów miesięcznie, bo taka jest minimalna kwota rozliczenia dodatku MFA, niezależnie od liczby użytkowników. Przy stawce 0,01 USD za aktywnego użytkownika minimum przestaje mieć znaczenie dopiero powyżej dziesięciu tysięcy użytkowników miesięcznie.

Kiedy SuperTokens nie jest dobrym wyborem?

Gdy potrzebujesz wyłącznie logowania hasłem i społecznościowego w małym projekcie, bo trzy ruchome części to nadmiarowa złożoność. Gdy pracujesz w sieci odciętej od internetu i nie masz pewności co do formatu klucza. Oraz gdy Twój plan produktowy od początku zakłada wielodostępność i SAML, bo wtedy z dwóch obiecanych zalet, czyli otwartości i darmowości, zostaje jedna.