API pro připojení systému do Identity Managementu

Potřebujete napojit koncový systém na Identity Manager (IdM)? Váš spravovaný systém nemá API, chcete jej vytvořit? Zde máte jednoduchý příklad, zadání API pro připojení systému do Identity Managementu.

IdM na základě přidělení role uživateli založí účet a nastaví práva v napojeném systému. Při změně atributů identity IdM online propíše tyto změny do napojeného systému. Při odebrání role uživateli IdM okamžitě odstraní účet uživatele z napojeného systému.

Je třeba, aby takto napojovaný systém disponoval příslušným rozhraním. Je třeba znát význam a možné hodnoty všech atributů uživatele, které má IdM spravovat. Existuje několik možností, jak systém napojit.

K IdM je možné připojit libovolný systém, který je dostupný po síti a je zjistitelná jeho struktura identit. Pro správu uživatelských účtů, oprávnění  a organizační struktury se využívají v identity manageru konektory.

Konektor je malý programový nástroj na straně IDM, který dovoluje výměnu dat s napojeným systémem pomocí jeho nativního API. Díky konektoru není třeba upravovat spravovaný systém. Snadnost napojení na koncový systém je obrovskou výhodou IdM. Seznam konektorů IdM bývá velmi rozsáhlý.

Nejčastěji používaná aplikační rozhraní konektory:

1. Webové služby přes HTTPs:
   • REST
   • SOAP, popis v WSDL
2. Přístup do databáze přes JDBC a práce s vystavenými view/procedurami
3. Volání skriptů v operačním systému (SSH nebo PowerShell konektor)

Více zde: CzechIdM API – Requirements for connected system

Moderní cestou je využívání webových služeb. Typickým příkladem REST API pro správu identit  je SCIM specifikace, která je navržena primárně pro cloud aplikace. Pro on-premise aplikace může být univerzálnost SCIM naopak nevýhodou z hlediska rychlosti.

Obecné požadavky na API na straně spravovaného systému:

1. Každý účet je unikátně identifikován.
2. API by nemělo přenášet vnitřní logiku správy uživatelských účtů ven z aplikace.
3. Pokud je požadována synchronizace dat z napojeného systému do identity manageru, je vhodné podporovat detekci změn. Například formou časové značky u změněného objektu.

Webová služba typu SOAP

Aplikace, či systém disponuje SOAP nebo RESTful webovou službou, pomocí níž lze zakládat uživatele, aktualizovat atributy a oprávnění uživatele a smazat uživatele. Webová služba musí implementovat tyto metody:

• getUser – načtení uživatele včetně všech jeho spravovaných atributů
• findUser – vyhledávání uživatele dle libovolného ze spravovaných atributů (minimálně dle loginu)
• listAllUsers – vrací seznam všech uživatelů v aplikaci
• updateUser – aktualizace atributů uživatele. Musí podporovat přejmenování uživatele (podporuje-li to samotná aplikace). Jedním ze spravovaných atributů bude seznam oprávnění uživatele v aplikaci. V případě, že lze v aplikaci, či systému uživatele zablokovat nebo deaktivovat, musí to tato metoda pomocí zadání hodnoty atributu umožňovat.
• deleteUser – smazání účtu uživatele

V případě, že bude systém sloužit zároveň jako zdroj informací o uživatelích (zdrojový systém), je nutné, aby implementoval metodu:

• syncUsers – vrací seřazený seznam dvojic [identifikátor uživatele, časová známka poslední změny] uživatelských účtů, na nichž došlo ke změně od zadaného data v parametru metody. Řazení probíhá od nejstaršího změněného záznamu po nejnovější. Pokud na uživateli došlo od zadaného data k více změnám, metoda vrací pouze datum poslední změny. Je nutné vracet všechny výsledky najednou, nikoliv stránkovaně.

Je třeba, aby metody findUser a listAllUsers vracely všechny výsledky najednou, nikoliv stránkovaně. Na straně CzechIdM pak bude implementován konektor, který s touto webovou službou bude komunikovat. Konektor bude představovat klientskou část této webové služby. Serverová část bude implementována na straně napojované aplikace.

Níže jsou uvedeny požadavky na rozhraní webových metod pro komunikaci mezi CzechIdM a napojeným systémem nebo aplikací.

Datové struktury

Metody webové služby

Příklad: API pro agendový systém eSpis

Ukázka dostupných metod v API, webové služby SOAP poměrně rozšířeného agendového systému eSpis používaného na úřadech v ČR. API slouží pro správu uživatelských účtů zaměstnanců a jejich pracovních míst. Ukázka je typickým příkladem pro většinu napojovaných systémů.

Uživatelé

Metoda pro vylistování všech osob v systému
VSTUP:

• nic

VÝSTUP:

• seznam nalezených jednoznačných identifikátorů (login) osob (uloženo v poli nebo nějaké kolekci jako String)

getEmployee

Metoda pro načtení jedné entity “Osoby” podle ID
VSTUP:

• String ID – jednoznačný identifikátor osoby login

VÝSTUP

• všechny atributy evidované v systému pro danou osobu
  • String Jméno
  • String Příjmení
  • String Login
  • String Zkratka
  • String Příslušnost ke spisovému uzlu
  • String ID funkčního místa
• pokud nebyla nalezena entita s daným ID, vrátí NULL

createEmployee

Metoda pro založení jedné entity “Osoba”

VSTUP

• všechny atributy, které lze nastavit
  • String Login
  • String Jméno
  • String Příjmení
  • String Heslo
  • String Zkratka
  • String Příslušnost ke spisovému uzlu
  • String ID funkčního místa

VÝSTUP

•  String errorMessage – chybová zpráva, pokud se založení nezdařilo; v případě úspěchu NULL

updateEmployee

Metoda pro aktualizaci jedné entity “Osoba”

VSTUP

• String ID – jednoznačný identifikátor osoby
•  všechny atributy, které lze nastavit
  • String Login
  • String Jméno
  • String Příjmení
  • String Heslo
  • String Zkratka
  • String Příslušnost ke spisovému uzlu

VÝSTUP

• String errorMessage – chybová zpráva, pokud se aktualizace nezdařila; v případě úspěchu NULL

deleteEmployee

Metoda pro odstranění jedné entity “Osoba” pomocí aktualizace příznaku platnosti

VSTUP

• String ID – jednoznačný identifikátor osoby

VÝSTUP

• String errorMessage – chybová zpráva, pokud se aktualizace nezdařila; v případě úspěchu NULL

Organizační struktura

Jednoznačným identifikátorem funkčních míst v systému je jejich název

listPositions

Metoda pro vylistování všech funkčních míst v systému

VSTUP: nic

VÝSTUP

• seznam jednoznačných identifikátorů (názvů) nalezených funkčních míst

getPosition

Metoda pro načtení jednoho funkčního místa

• String Název – identifikátor funkčního místa

• všechny atributy funkčního místa evidované v systému
  • String Název
  • String Zkratka
  • String Obvod
  • String Účetní okruh
  • String Login uživatele
  • String Role z katalogu práv
  • String Instance práva (modul)
  • String Agendová kniha
• pokud nebyla nalezena entita s daným ID, vrátí NULL

createPosition

Metoda pro založení jednoho funkčního místa

VSTUP

• String positionId – identifikátor funkčního místa
• všechny atributy, které bude funkční místo v systému potřebovat
  • String Název
  • String Zkratka
  • String Obvod
  • String Účetní okruh
  • String Login uživatele
  • String Role z katalogu práv
  • String Instance práva (modul)
  • String Agendová kniha

VÝSTUP

• String errorMessage – chybová zpráva, pokud se založení nezdařilo; v případě úspěchu NULL

updatePosition

1. pro aktualizaci jednoho funkčního místa,
2. pro přiřazení uživatele na dané funkční místo,
3. pro přiřazení oprávnění funkčnímu místu.

• String Název – identifikátor funkčního místa
• všechny atributy,  které bude funkční místo v systému potřebovat
  • String Název
  • String Zkratka
  • String Obvod
  • String Účetní okruh
  • String Login uživatele
  • String Role z katalogu práv
  • String Instance práva (modul)
  • String Agendová kniha

VÝSTUP

• String errorMessage – chybová zpráva, pokud se aktualizace nezdařila; v případě úspěchu NULL

deletePosition

• String positionId – identifikátor funkčního místa

• String errorMessage – chybová zpráva, pokud se aktualizace nezdařila; v případě úspěchu NULL

Závěr jak na API pro IdM?

Velkým přínosem IdM je snadnost připojení koncového systému bez nutnosti jeho přizpůsobení nebo dokonce i restartu. Možností napojení koncových systémů je mnoho. Někdy je vhodné naopak na straně koncového systému připravit univerzální API pro správu identit.

Výše zmíněný příklad je obecný pro většinu Identity Managerů.

Děkuji kolegům za podklady – Vláďovi Kotýnkovi, Zdendovi Burdovi a ostatním.

Mohlo by vás také zajímat:

Seriál o Identity Managementu:

1. Co je to Identity Management?
2. Jak vybrat IDM?
3. Jak migrovat Identity Management?
4. Modely spolupráce s dodavatelem IDM.
5. Jak zabrátit vendor lock-in?
6. Jak z personalistiky identifikovat vedoucího pro IDM?
7. Jak se zbavit rutinních úkolů při správě IT systému automatizací Identity Managementu?
8. Jak správně testovat IdM?
9. Jak správně nasadit IDM do produktivního provozu?
10. API pro připojení systému do IDM
11. Co je to SCIM?
12. IdM nebo formulářový systém?
13. Netradiční využití IdM 1, 2, 3

O CzechIdM:

1. Podporované konektory
2. Základní funkce 
3. Seznam podporovaných konektorů
4. Jak na samoregistraci a žádost o VPN?
5. Jak na reset hesel z Windows? Password filtr
6. Napojení JIP/KAAS.
7. Správa MS-Acess.
8. IdM a napojení Moodle
9. Jak přidělovat licence o365.
10. CzechIdM a Salesforce.

Další témata