Passwordless SSO s Notakey: konfigurace krok za krokem

Na konci tohoto návodu se uživatelé budou k aplikaci přihlašovat schválením z telefonu — zadají uživatelské jméno nebo naskenují QR kód a potvrdí to v aplikaci Notakey. Na přihlašovací stránce žádné heslo nebude. Heslo přitom nikam nezmizí, jen má jedinou povinnou úlohu: je vyžadováno jednou, při registraci zařízení, kdy se vytváří uživatelský klíč. Všechno, co následuje, je už jen otázka nastavené politiky — a tento návod ukazuje přesně, kde se každá z nich konfiguruje.

Každá služba Notakey — tytéž, které už možná používáte pro 2FA k VPN, Windows nebo Wi-Fi — umí fungovat i jako poskytovatel OpenID Connect. Není k tomu potřeba žádný samostatný produkt: v Dashboardu službě zapnete OIDC, aplikaci, která ho bude využívat, zaregistrujete jako klienta a tu pak nasměrujete na endpointy, které jí Notakey vygeneruje. Žádné SAML certifikáty, žádný samostatný server identity providera, o který by se bylo potřeba starat.

your app ──OIDC──▶ Notakey service (OIDC provider)
                        │
                        ├──▶ user repository: onboarded devices in this service
                        └──▶ push ──▶ user's phone: read, approve

(Klasické podnikové aplikace, které umí jen SAML — Google Workspace, AWS — potřebují místo toho samostatného SAML identity providera od Notakey; kde ho najít, popisujeme v poslední části.)

Jak tady heslo skutečně funguje

Stojí za to být tu přesný, protože slovo „passwordless“ se často používá dost volně:

Jediné povinné heslo je to při onboardingu. Nastavené v Dashboardu nebo převzaté z Active Directory se ověří jen jednou, když si uživatel registruje zařízení a v zabezpečeném hardwaru telefonu se generuje jeho klíč.
Běžné přihlášení heslo nepotřebuje vůbec. Uživatel zadá jméno nebo naskenuje QR kód — přihlašovací stránku lze omezit čistě na skenování, bez jediného políčka k vyplnění. Identitu ověřuje podepsané schválení v aplikaci.
Všechno ostatní je věc nastavení, ne pevné pravidlo. Jedna aplikace může vyžadovat ještě potvrzení v appce navíc, jiná heslo, další obojí. Heslo lze také nechat znovu vyžádat po určitém intervalu, aby na něj uživatelé úplně nezapomněli. Všechno se nastavuje na jedné obrazovce, kterou popisuje krok 5 níže.

Krok 1 — Vyberte službu

Pokud se uživatelé stávající služby Notakey překrývají s uživateli aplikace, kterou připojujete, použijte ji. Pokud chcete, aby měla tato aplikace vlastní politiku hesel, nezávislou na všem ostatním, vytvořte novou (Services → Manage → New). Rozhodující je, že politika z kroku 5 platí pro celou službu, ne pro jednotlivého klienta.

Krok 2 — Zapněte OpenID Connect

Otevřete službu a přejděte na OpenID Connect configuration → Configure, kde zaškrtnete Enabled. Zbytek prozatím nechte na výchozích hodnotách — volby Require password a Require mfa nastavíte záměrně až v kroku 5, ne tady omylem. Uložte.

Krok 3 — Zkopírujte endpointy

Zpátky na OpenID Connect configuration klikněte na Show. Notakey už má vygenerovaný discovery dokument a jednotlivé endpointy za ním:

https://<your-dashboard-host>/oidc/services/<access-id>/.well-known/openid-configuration

Většině softwaru, který umí OIDC, stačí právě tato jedna URL — vložíte ji do pole „auto discovery“ nebo „issuer“ a aplikace si sama stáhne endpointy pro authorization, token, userinfo i JWKS. <access-id> je totéž ID, které je vidět na stránce samotné služby.

Krok 4 — Zaregistrujte aplikaci jako klienta

V rámci služby přejděte na OpenID Connect configuration → Clients → New client. Notakey vám vygeneruje Client ID a náhodný Secret.

Než uložíte, stojí za to vědět dvě věci. Pole Secret je maskované a jakmile stránku opustíte, Notakey vám ho už znovu nezobrazí — zkopírujte si ho hned, nebo do pole vložte vlastní tajemství podle svého výběru, což funguje stejně dobře a snáz se to eviduje. A pole Redirect URIs musí odpovídat znak po znaku URL, kterou aplikace posílá zpátky při přihlášení — chybějící nebo přebývající lomítko na konci stačí k tomu, aby to přestalo fungovat (viz háček níže).

Vyplňte:

Description — cokoliv, podle čeho klienta později poznáte.
Secret — zkopírujte vygenerovaný, nebo ho přepište vlastním.
Redirect URIs — callback URL aplikace pro OAuth. Pokud je aplikace dostupná na více adresách, oddělte je čárkou.
Logout URI — kam přesměrovat prohlížeč po odhlášení. Nepovinné.

Jakmile zaregistrujete pár aplikací, seznam klientů služby vypadá takto:

Krok 5 — Nasměrujte aplikaci na Notakey

Konkrétní kroky se liší od aplikace k aplikaci, ale princip je vždy stejný: issuer nebo discovery URL, client ID, client secret. Dva reálné příklady ze self-hosted nástrojů:

Gitea na to má rovnou CLI příkaz — žádný webový formulář, žádný restart:

gitea admin auth add-oauth \
  --name notakey \
  --provider openidConnect \
  --key <client-id> \
  --secret <client-secret> \
  --auto-discover-url https://<dashboard-host>/oidc/services/<access-id>/.well-known/openid-configuration \
  --scopes openid --scopes profile --scopes email

Na přihlašovací stránce Gitea se hned objeví tlačítko „Sign in with notakey“, vedle stávajícího přihlašovacího formuláře — nic se neruší.

Proxmox VE to bere jako další authentication realm, který přibude k těm, co už existují:

pveum realm add notakey --type openid \
  --issuer-url https://<dashboard-host>/oidc/services/<access-id> \
  --client-id <client-id> \
  --client-key <client-secret> \
  --username-claim sub \
  --scopes "openid email profile" \
  --autocreate 1

--issuer-url je tady discovery URL bez koncovky /.well-known/openid-configuration — tu si Proxmox připojí sám. --autocreate 1 při prvním úspěšném přihlášení vytvoří odpovídajícího uživatele Proxmoxu, ale bez jediného oprávnění, dokud mu nějaká výslovně neudělíte; přístup vám tedy omylem nerozdá.

Krok 6 — Nastavte politiku hesel

Tady se ona „volba administrátora“ mění v konkrétní nastavení, zpátky na OpenID Connect configuration → Configure:

Require password vypnuto a Require mfa zapnuto: passwordless tok popsaný na začátku návodu. Přihlášení je jméno (nebo QR) plus schválení z telefonu, nic víc.
Require password zapnuto, Password cache ponechaný na 0: heslo se vyžaduje pokaždé, navíc ke schválení — klasické dvoufaktorové ověření.
Require password zapnuto a Password cache nastavený v sekundách (třeba 2592000 pro 30 dní): v běžném provozu passwordless, heslo se znovu vyžádá až po uplynutí tohoto okna — jen aby se úplně nezapomnělo. Stejně funguje i Mfa cache pro krok schválení, pokud byste chtěli cachovat i ten.

Protože je toto nastavení platné pro celou službu, aplikace, která potřebuje jinou politiku než její sousedé, patří do vlastní služby — zpátky k volbě z kroku 1.

Když něco nefunguje

Chyba redirect_uri mismatch skoro vždy znamená lomítko na konci: některé aplikace posílají https://app.example.com, jiné https://app.example.com/, a Notakey porovnává řetězec doslovně. V logu nginx nebo aplikace najděte skutečnou hodnotu redirect_uri=, kterou aplikace poslala, a zaregistrujte přesně tu.
Pokud discovery URL vrací 404, ověřte, že se v kroku 2 opravdu uložilo zaškrtnutí Enabled — nejčastější chybou je konfigurační stránka, která vypadá správně, ale nikdy se neodeslala.
Log Authentication activities u dané služby zobrazuje každý pokus, který se k Notakey dostal. Pokud se tam pokus vůbec neobjeví, aplikace se nedostala ani k authorization endpointu — zkontrolujte nejdřív client ID a discovery URL.

Co tento návod záměrně vynechává

Klasické integrace SAML 2.0 pro aplikace, které umí jen SAML — Google Workspace, AWS a podobné — nejdou přes OIDC popsané výše, ale přes samostatného SAML identity providera Notakey. Mimo tento návod zůstává i LDAP/Active Directory jako uživatelský repozitář, multi-tenant nasazení a vlastní branding. Všechno najdete v referenci CLI a API i s kompletními tabulkami parametrů; tento návod je rychlá cesta od nuly k funkčnímu přihlášení bez hesla.

Vyzkoušejte si to, než začnete stavět

Nejrychlejší způsob, jak posoudit, jak se to uživatelům bude přihlašovat, je vyzkoušet schvalovací tok sami: vyzkoušejte živé demo a podepište žádost z vlastního telefonu — zabere to zhruba dvě minuty —, nebo požádejte o demo a my namapujeme vaše aplikace a politiku hesel na pilotní provoz na vaší vlastní infrastruktuře.