Beta verzia novej dokumentácie.

Prejsť na starú verziu
Prejsť na cdesk.sk

ADFS / SSO konektor – technický manuál konfigurácie

Tento manuál popisuje kompletné nastavenie prihlasovania do CDESK cez Active Directory Federation Services (AD FS) pomocou protokolu SAML 2.0. Prihlásenie funguje len vtedy, keď sú nastavené obe strany a poznajú sa navzájom, preto sa dokument skladá z dvoch častí:

  • v Časti A nakonfigurujete konektor na strane CDESK,
  • v Časti B nakonfigurujete samotnú službu AD FS.

Obe časti na seba nadväzujú — hodnoty vytvorené v CDESK (ACS a EntityId) sa vkladajú do AD FS.

Roly v SAML: V tomto scenári je CDESK poskytovateľ služby (Service Provider, SP) a AD FS poskytovateľ identity (Identity Provider, IdP). CDESK samo nikoho neautentifikuje — overenie mena a hesla (prípadne automatické prihlásenie pri konte prihlásenom do domény) rieši AD FS a CDESK iba overí a spracuje výsledok.

Princíp fungovania

Prihlásenie prebieha ako SP-initiated SAML tok. Používateľ na prihlasovacej obrazovke CDESK klikne na tlačidlo konektora, CDESK vytvorí požiadavku AuthnRequest a presmeruje prehliadač na AD FS. Po overení identity AD FS odošle podpísanú SAML odpoveď späť na tzv. Assertion Consumer Service (ACS) adresu CDESK, kde ju CDESK overí, vytiahne z nej jednoznačný identifikátor používateľa (GUID) a podľa neho nájde a prihlási konto v CDESK.

Obrázok: Automatická synchronizácia kont z Microsoft Entra ID do CDESK

Predpoklady

  • Funkčný server AD FS s prístupom správcu (rola AD FS Management) a bežiacim federačným endpointom (napr. https://adfs.domena.com).
  • CDESK dostupný cez HTTPS na vlastnej doméne.
  • Podpisový verejný X.509 certifikát z AD FS (token-signing certificate) vo forme reťazca (bez hlavičiek BEGIN/END CERTIFICATE).
  • Používatelia, ktorí sa majú prihlasovať cez SSO, musia mať v CDESK vyplnený jednoznačný identifikátor (id_external) zhodný s hodnotou posielanou z AD FS — inak ich CDESK po prihlásení nedokáže spárovať. Typicky ide o ObjectGUID z Active Directory.

Kľúčová podmienka spárovania: SSO neprihlasuje na základe mena, ale na základe GUID. Ak konto v CDESK nemá vyplnený zodpovedajúci id_external, prihlásenie skončí presmerovaním s príznakom user_not_found. GUID sa do CDESK zvyčajne dostane synchronizáciou cez konektor AD / LDAP alebo Microsoft Entra ID.

Časť A – Konfigurácia konektora v CDESK

  • Konektor pridáte v časti Globálne nastavenia → Konektory, API tlačidlom + Pridať konektor, kde zvolíte typ SSO (AD FS & SAML 2.0) a potvrdíte tlačidlom Pokračovať. Vyplňte nasledujúce polia a uložte tlačidlom Vytvoriť:
Obrázok: Automatická synchronizácia kont z Microsoft Entra ID do CDESK
  • Názov – ľubovoľný názov pre identifikáciu konektora v zozname (napr. ADFS SSO). Zobrazí sa aj ako popis tlačidla na prihlasovacej obrazovke.
  • EntityId – identifikátor CDESK ako SP (URI). Pri prvom uložení ho CDESK vygeneruje automaticky z názvu servera a administrátora v tvare urn:federation:<host>-<admin>; po vytvorení je pole editovateľné. Rovnakú hodnotu použijete v AD FS ako Relying party trust identifier. Príklad: urn:federation:example-com.
  • IdP URL – základná adresa AD FS bez koncového lomítka, napr. https://adfs.domena.com. CDESK k nej pri prihlásení dopĺňa cestu /adfs/ls.
  • Public x509 certificate – verejný podpisový certifikát AD FS (reťazec Base64). Používa sa na overenie podpisu SAML odpovede.
  • Jednoznačný identifikátor – určuje, podľa čoho sa páruje používateľ: ObjectGUID (predvolené) alebo vlastný atribút.
  • Názov atribútu, v ktorom je jednoznačný identifikátor – zobrazí sa len pri voľbe vlastný atribút. Uvediete názov claimu, v ktorom AD FS posiela identifikátor.
  • Automatické prihlásenie z prihlasovacej obrazovky – zapne True SSO, čiže CDESK po otvorení prihlasovacej obrazovky automaticky presmeruje na AD FS. Voliteľne je možné presmerovanie oneskoriť poľom Oneskoriť automatické prihlásenie o počet sekúnd.
  • Assertion Consumer Service (ACS) – zobrazí sa až po uložení (pole je len na čítanie). Je to adresa, kam AD FS posiela SAML odpoveď, a vkladá sa do AD FS. Tvar: https://<host>/api/auth/adfs/acs/<GUID-konektora>.
  • Odkaz na prihlasovaciu obrazovku bez automatického prihlásenia – zobrazí sa po uložení, ak je zapnuté automatické prihlásenie. Je to adresa s parametrom, ktorý presmerovanie vypne a zobrazí štandardný formulár (na prihlásenie menom a heslom bez SSO).

Poradie krokov: ACS adresu poznáte až po uložení konektora (predtým sa pole nezobrazuje). Preto najprv vytvorte konektor v CDESK, skopírujte si z neho ACS aj EntityId, a až potom prejdite na konfiguráciu AD FS.

Časť B – Konfigurácia AD FS servera

Na serveri AD FS vytvorte novú dôveryhodnú stranu (Relying Party Trust) a nastavte pravidlá pre vydávanie claimov. Nasledujúce kroky zodpovedajú sprievodcovi Add Relying Party Trust Wizard.

  1. Add Relying Party Trust → kliknite na Start.
  2. Select Data Source: zvoľte Enter data about the relying party manually → kliknite na Next.


  3. Specify Display Name: zadajte názov (napr. SSO CDESK) → kliknite na Next.


  4. Configure Certificate: preskočte tlačidlom Next (SP certifikát sa nepoužíva).


  5. Configure URL: zaškrtnite Enable support for the SAML 2.0 WebSSO protocol a vložte ACS adresu z konektora CDESK → kliknite na Next.


  6. Configure Identifiers: do Relying party trust identifier vložte hodnotu EntityId z konektora CDESK (napr. urn:federation:example-com) a pridajte tlačidlom Add → kliknite na Next.


  7. Choose Access Control Policy: Permit everyone → kliknite na Next.


  8. Ready to Add Trust → kliknite na Next → Finish (ponechajte zaškrtnuté Configure claims issuance policy for this application).





 

Pravidlo vydávania claimov (Claim Issuance Policy)

V okne Edit Claim Issuance Policy pridajte tlačidlom Add Rule… jedno pravidlo typu Send LDAP Attributes as Claims (Attribute store: Active Directory).

Následne namapujte tieto atribúty:

  • ObjectGUID → claim GUID – povinné. Podľa tejto hodnoty CDESK páruje používateľa (voči id_external).
  • E-Mail-Addresses → claim E-mail Address – slúži iba na identifikáciu používateľa v logoch CDESK.
  • atribút s osobným číslom zamestnanca (napr. cn alebo samAccountName) – voliteľné, pre neskoršie overovanie voči osobnému číslu. Odporúča sa overiť už teraz, či ho AD FS dokáže posielať.

Nastavenie jednoznačného identifikátora používateľa pomocou ObjectGUID:

Pri použití LDAP atribútu ObjectGUID odporúčame v ADFS namapovať tento atribút na odchádzajúci claim s názvom GUID. CDESK pri predvolenom nastavení jednoznačného identifikátora „Atribút GUID“ očakáva práve tento claim.

Ak chcete na identifikáciu používateľa použiť iný LDAP atribút (napr. employeeID alebo vlastný atribút), namapujte tento atribút v ADFS na príslušný Outgoing Claim Type. V nastavení CDESK potom v poli Názov atribútu zadajte rovnaký názov claimu (napr. employeeID) alebo jeho úplný URI tvar:

(napr. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeID). CDESK podporuje oba spôsoby zadania.

Praktická poznámka k ObjectGUID:
Atribút ObjectGUID nemusí byť v pravidle Send LDAP Attributes as Claims dostupný v rozbaľovacom zozname LDAP atribútov. V takom prípade je potrebné zadať ho manuálne do poľa LDAP Attribute.

SAML konfigurácia CDESK (SP parametre pre nastavenie ADFS)

CDESK v tomto scenári vystupuje ako SAML Service Provider (SP). Nasledujúce hodnoty definujú SAML parametre CDESK, ktoré je potrebné použiť pri konfigurácii Identity Providera (ADFS).

  • SP EntityId – hodnota z poľa EntityId, ktorou sa CDESK identifikuje voči ADFS.
  • ACS URL / binding – /api/auth/adfs/acs/{guid}, HTTP-POST. Na túto adresu ADFS odosiela overenú SAML odpoveď po úspešnom prihlásení používateľa.
  • IdP SSO URL / binding – {IdP URL}/adfs/ls, HTTP-Redirect. Adresa prihlasovacieho endpointu ADFS.
  • IdP podpisový certifikát – hodnota z poľa Public x509 certificate, ktorý CDESK používa na overenie podpisu prijatej SAML odpovede.
  • NameID Format – urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
  • Podpisový / digest algoritmus – RSA-SHA256 / SHA256.

 

Interné validačné nastavenia SP (CDESK):

  • strict – false
  • wantAssertionsSigned – false (CDESK nevyžaduje samostatný podpis Assertion elementu; overuje podpis podľa nakonfigurovaného certifikátu).

Ako CDESK spracuje odpoveď (technické detaily)

SAML odpoveď prichádza na endpoint POST /api/auth/adfs/acs/{guid}, kde {guid} je identifikátor konektora. Spracovanie prebieha v AdfsController::postAcs() a využíva knižnicu OneLogin SAML2:

  • Overenie odpovede – odpoveď sa validuje voči nastaveniam SP/IdP a podpisu (verejný certifikát z poľa Public x509 certificate). Ak overenie zlyhá, CDESK presmeruje na prihlasovaciu obrazovku s príznakom thirdparty_not_verified.
  • Získanie GUID – z atribútov odpovede sa načíta claim GUID (alebo vlastný atribút podľa nastavenia). Ak ide o ObjectGUID zakódovaný v Base64, CDESK ho prevedie na hexadecimálny reťazec (napr. olW/vipj5UeGUVRezrAa+w== → a255bfbe2a63e5478651545eceb01afb).
  • Spárovanie používateľa – CDESK hľadá aktívne konto, ktoré má id_external rovné získanému GUID a patrí pod daného administrátora (jeho konto alebo podriadené kontá). Ak sa nenájde, presmeruje s príznakom user_not_found.
  • Prihlásenie – po nájdení konta CDESK vytvorí prihlasovací token (typ WEB_APP), zaznamená prihlásenie (spôsob ADFS) a nastaví prihlasovacie cookies.

Testovanie

Na prihlasovacej obrazovke CDESK sa zobrazí tlačidlo s názvom konektora (napr. ADFS SSO). Po kliknutí sa prehliadač presmeruje na AD FS. Ak je používateľ prihlásený do domény, AD FS ho zvyčajne prihlási automaticky a CDESK ho po overení pustí dnu. Pri zapnutom automatickom prihlásení (True SSO) sa presmerovanie na AD FS spustí hneď po otvorení prihlasovacej obrazovky; na prihlásenie bez SSO použite Odkaz na prihlasovaciu obrazovku bez automatického prihlásenia.

Riešenie problémov

  • user_not_found – GUID z AD FS sa nezhoduje so žiadnym aktívnym kontom v CDESK. Skontrolujte, či má používateľ vyplnený id_external a či AD FS posiela správny ObjectGUID (pravidlo Send LDAP Attributes as Claims).
  • thirdparty_not_verified – SAML odpoveď sa nepodarilo overiť. Najčastejšie ide o nesprávny alebo neaktuálny podpisový certifikát, prípadne nesúlad EntityId/ACS medzi CDESK a AD FS.
  • „Konektor nie je nakonfigurovaný, alebo zapnutý“ – konektor podľa GUID neexistuje alebo je neaktívny. Skontrolujte stav konektora v Konektory, API.
  • Prázdna hodnota GUID – AD FS neposlal claim GUID. Chýba alebo je nesprávne nastavené pravidlo Send LDAP Attributes as Claims.

Logovanie: Priebeh spracovania SAML odpovede sa zapisuje do logu pod kanálom extsys-adfs (vrátane NameID, atribútov a prípadných chýb). Pri ladení konfigurácie je to prvé miesto, kam sa oplatí pozrieť.

Poznámka k príkladom: Adresy a certifikát v tomto manuáli sú ilustračné. Vo vlastnej inštalácii použite reálnu doménu CDESK, adresu AD FS a certifikát z vášho prostredia.

Prejsť na cdesk.sk