Tento manuál popisuje kompletní nastavení přihlašování do CDESK přes Active Directory Federation Services (AD FS) pomocí protokolu SAML 2.0. Přihlášení funguje jen tehdy, když jsou nastaveny obě strany a znají se navzájem, proto se dokument skládá ze dvou částí:
- v Části A nakonfigurujete konektor na straně CDESK,
- v Části B nakonfigurujete samotnou službu AD FS.
Obě části na sebe navazují — hodnoty vytvořené v CDESK (ACS a EntityId) se vkládají do AD FS.
Role v SAML: V tomto scénáři je CDESK poskytovatel služby (Service Provider, SP) a AD FS poskytovatel identity (Identity Provider, IdP). CDESK samo nikoho neautentizuje — ověření jména a hesla (případně automatické přihlášení u konta přihlášeného do domény) řeší AD FS a CDESK pouze ověří a zpracuje výsledek.
Princip fungování
Přihlášení probíhá jako SP-initiated SAML tok. Uživatel na přihlašovací obrazovce CDESK klikne na tlačítko konektoru, CDESK vytvoří požadavek AuthnRequest a přesměruje prohlížeč na AD FS. Po ověření identity AD FS odešle podepsanou SAML odpověď zpět na tzv. Assertion Consumer Service (ACS) adresu CDESK, kde ji CDESK ověří, vytáhne z ní jednoznačný identifikátor uživatele (GUID) a podle něj najde a přihlásí konto v CDESK.
Předpoklady
- Funkční server AD FS s přístupem správce (role AD FS Management) a běžícím federačním endpointem (např. https://adfs.domena.com).
- CDESK dostupný přes HTTPS na vlastní doméně.
- Podpisový veřejný X.509 certifikát z AD FS (token-signing certificate) ve formě řetězce (bez hlaviček BEGIN/END CERTIFICATE).
- Uživatelé, kteří se mají přihlašovat přes SSO, musí mít v CDESK vyplněn jednoznačný identifikátor (id_external) shodný s hodnotou posílanou z AD FS — jinak je CDESK po přihlášení nedokáže spárovat. Typicky jde o ObjectGUID z Active Directory.
Klíčová podmínka spárování: SSO nepřihlašuje na základě jména, ale na základě GUID. Pokud konto v CDESK nemá vyplněn odpovídající id_external, přihlášení skončí přesměrováním s příznakem user_not_found. GUID se do CDESK zpravidla dostane synchronizací přes konektor AD / LDAP nebo Microsoft Entra ID.
Část A – Konfigurace konektoru v CDESK
- Konektor přidáte v části Globální nastavení → Konektory, API tlačítkem + Přidat konektor, kde zvolíte typ SSO (AD FS & SAML 2.0) a potvrdíte tlačítkem Pokračovat. Vyplňte následující pole a uložte tlačítkem Vytvořit:
- Název – libovolný název pro identifikaci konektoru v seznamu (např. ADFS SSO). Zobrazí se i jako popis tlačítka na přihlašovací obrazovce.
- EntityId – identifikátor CDESK jako SP (URI). Při prvním uložení ho CDESK vygeneruje automaticky z názvu serveru a administrátora ve tvaru urn:federation:<host>-<admin>; po vytvoření je pole editovatelné. Stejnou hodnotu použijete v AD FS jako Relying party trust identifier. Příklad: urn:federation:example-com.
- IdP URL – základní adresa AD FS bez koncového lomítka, např. https://adfs.domena.com. CDESK k ní při přihlášení doplňuje cestu /adfs/ls.
- Public x509 certificate – veřejný podpisový certifikát AD FS (řetězec Base64). Používá se k ověření podpisu SAML odpovědi.
- Jednoznačný identifikátor – určuje, podle čeho se páruje uživatel: ObjectGUID (výchozí) nebo vlastní atribut.
- Název atributu, ve kterém je jednoznačný identifikátor – zobrazí se jen při volbě vlastní atribut. Uvedete název claimu, ve kterém AD FS posílá identifikátor.
- Automatické přihlášení z přihlašovací obrazovky – zapne True SSO, tedy CDESK po otevření přihlašovací obrazovky automaticky přesměruje na AD FS. Volitelně je možné přesměrování zpozdit polem Zpozdit automatické přihlášení o počet sekund.
- Assertion Consumer Service (ACS) – zobrazí se až po uložení (pole je jen pro čtení). Je to adresa, kam AD FS posílá SAML odpověď, a vkládá se do AD FS. Tvar: https://<host>/api/auth/adfs/acs/<GUID-konektoru>.
- Odkaz na přihlašovací obrazovku bez automatického přihlášení – zobrazí se po uložení, pokud je zapnuté automatické přihlášení. Je to adresa s parametrem, který přesměrování vypne a zobrazí standardní formulář (pro přihlášení jménem a heslem bez SSO).
Pořadí kroků: ACS adresu znáte až po uložení konektoru (předtím se pole nezobrazuje). Proto nejprve vytvořte konektor v CDESK, zkopírujte si z něj ACS i EntityId, a až potom přejděte na konfiguraci AD FS.
Část B – Konfigurace serveru AD FS
Na serveru AD FS vytvořte novou důvěryhodnou stranu (Relying Party Trust) a nastavte pravidla pro vydávání claimů. Následující kroky odpovídají průvodci Add Relying Party Trust Wizard.
- Add Relying Party Trust → klikněte na Start.
- Select Data Source: zvolte Enter data about the relying party manually → klikněte na Next.
- Specify Display Name: zadejte název (např. SSO CDESK) → klikněte na Next.
- Configure Certificate: přeskočte tlačítkem Next (certifikát SP se nepoužívá).
- Configure URL: zaškrtněte Enable support for the SAML 2.0 WebSSO protocol a vložte ACS adresu z konektoru CDESK → klikněte na Next.
- Configure Identifiers: do Relying party trust identifier vložte hodnotu EntityId z konektoru CDESK (např. urn:federation:example-com) a přidejte tlačítkem Add → klikněte na Next.
- Choose Access Control Policy: Permit everyone → klikněte na Next.
- Ready to Add Trust → klikněte na Next → Finish (ponechte zaškrtnuté Configure claims issuance policy for this application).
Pravidlo vydávání claimů (Claim Issuance Policy)
V okně Edit Claim Issuance Policy přidejte tlačítkem Add Rule… jedno pravidlo typu Send LDAP Attributes as Claims (Attribute store: Active Directory).
Následně namapujte tyto atributy:
- ObjectGUID → claim GUID – povinné. Podle této hodnoty CDESK páruje uživatele (proti id_external).
- E-Mail-Addresses → claim E-mail Address – slouží pouze k identifikaci uživatele v logech CDESK.
- atribut s osobním číslem zaměstnance (např. cn nebo samAccountName) – volitelné, pro pozdější ověřování proti osobnímu číslu. Doporučuje se ověřit už nyní, zda ho AD FS dokáže posílat.
Nastavení jednoznačného identifikátoru uživatele pomocí ObjectGUID:
Při použití LDAP atributu ObjectGUID doporučujeme v ADFS namapovat tento atribut na odchozí claim s názvem GUID. CDESK při výchozím nastavení jednoznačného identifikátoru „Atribut GUID“ očekává právě tento claim.
Pokud chcete k identifikaci uživatele použít jiný LDAP atribut (např. employeeID nebo vlastní atribut), namapujte tento atribut v ADFS na příslušný Outgoing Claim Type. V nastavení CDESK potom v poli Název atributu zadejte stejný název claimu (např. employeeID) nebo jeho úplný tvar URI:
(např. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeID). CDESK podporuje oba způsoby zadání.
Praktická poznámka k ObjectGUID:
Atribut ObjectGUID nemusí být v pravidle Send LDAP Attributes as Claims dostupný v rozbalovacím seznamu LDAP atributů. V takovém případě je potřeba zadat ho manuálně do pole LDAP Attribute.
SAML konfigurace CDESK (parametry SP pro nastavení ADFS)
CDESK v tomto scénáři vystupuje jako SAML Service Provider (SP). Následující hodnoty definují SAML parametry CDESK, které je potřeba použít při konfiguraci Identity Provideru (ADFS).
- SP EntityId – hodnota z pole EntityId, kterou se CDESK identifikuje proti ADFS.
- ACS URL / binding – /api/auth/adfs/acs/{guid}, HTTP-POST. Na tuto adresu ADFS odesílá ověřenou SAML odpověď po úspěšném přihlášení uživatele.
- IdP SSO URL / binding – {IdP URL}/adfs/ls, HTTP-Redirect. Adresa přihlašovacího endpointu ADFS.
- Podpisový certifikát IdP – hodnota z pole Public x509 certificate, který CDESK používá k ověření podpisu přijaté SAML odpovědi.
- NameID Format – urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
- Podpisový / digest algoritmus – RSA-SHA256 / SHA256.
Interní validační nastavení SP (CDESK):
- strict – false
- wantAssertionsSigned – false (CDESK nevyžaduje samostatný podpis elementu Assertion; ověřuje podpis podle nakonfigurovaného certifikátu).
Jak CDESK zpracuje odpověď (technické detaily)
SAML odpověď přichází na endpoint POST /api/auth/adfs/acs/{guid}, kde {guid} je identifikátor konektoru. Zpracování probíhá v AdfsController::postAcs() a využívá knihovnu OneLogin SAML2:
- Ověření odpovědi – odpověď se validuje proti nastavení SP/IdP a podpisu (veřejný certifikát z pole Public x509 certificate). Pokud ověření selže, CDESK přesměruje na přihlašovací obrazovku s příznakem thirdparty_not_verified.
- Získání GUID – z atributů odpovědi se načte claim GUID (nebo vlastní atribut podle nastavení). Pokud jde o ObjectGUID zakódovaný v Base64, CDESK ho převede na hexadecimální řetězec (např. olW/vipj5UeGUVRezrAa+w== → a255bfbe2a63e5478651545eceb01afb).
- Spárování uživatele – CDESK hledá aktivní konto, které má id_external rovné získanému GUID a patří pod daného administrátora (jeho konto nebo podřízená konta). Pokud se nenajde, přesměruje s příznakem user_not_found.
- Přihlášení – po nalezení konta CDESK vytvoří přihlašovací token (typ WEB_APP), zaznamená přihlášení (způsob ADFS) a nastaví přihlašovací cookies.
Testování
Na přihlašovací obrazovce CDESK se zobrazí tlačítko s názvem konektoru (např. ADFS SSO). Po kliknutí se prohlížeč přesměruje na AD FS. Pokud je uživatel přihlášen do domény, AD FS ho zpravidla přihlásí automaticky a CDESK ho po ověření pustí dovnitř. Při zapnutém automatickém přihlášení (True SSO) se přesměrování na AD FS spustí hned po otevření přihlašovací obrazovky; pro přihlášení bez SSO použijte Odkaz na přihlašovací obrazovku bez automatického přihlášení.
Řešení problémů
- user_not_found – GUID z AD FS se neshoduje s žádným aktivním kontem v CDESK. Zkontrolujte, zda má uživatel vyplněn id_external a zda AD FS posílá správný ObjectGUID (pravidlo Send LDAP Attributes as Claims).
- thirdparty_not_verified – SAML odpověď se nepodařilo ověřit. Nejčastěji jde o nesprávný nebo neaktuální podpisový certifikát, případně nesoulad EntityId/ACS mezi CDESK a AD FS.
- „Konektor není nakonfigurován, nebo zapnut“ – konektor podle GUID neexistuje nebo je neaktivní. Zkontrolujte stav konektoru v Konektory, API.
- Prázdná hodnota GUID – AD FS neposlal claim GUID. Chybí nebo je nesprávně nastaveno pravidlo Send LDAP Attributes as Claims.
Logování: Průběh zpracování SAML odpovědi se zapisuje do logu pod kanálem extsys-adfs (včetně NameID, atributů a případných chyb). Při ladění konfigurace je to první místo, kam se vyplatí podívat.
Poznámka k příkladům: Adresy a certifikát v tomto manuálu jsou ilustrační. Ve vlastní instalaci použijte reálnou doménu CDESK, adresu AD FS a certifikát z vašeho prostředí.