Technická dokumentace pro implementaci MojeID

Vydání: 3.0

Právní upozornění

Omezení odpovědnosti

S výjimkou případů újmy způsobené úmyslně nebo hrubou nedbalostí, nebo újmy způsobené člověku na jeho přirozených právech, případně v maximální možné míře, ve které to umožňuje právní řád uživatele, nenese sdružení CZ.NIC v žádném případě odpovědnost za jakékoli přímé nebo nepřímé újmy vyplývající z užití (včetně instalace) služby MojeID, včetně, avšak nikoliv výlučně, újmy na pověsti či jméně, újmy vzniklé v důsledku přerušení práce, ztráty nebo poškození dat nebo jakékoliv újmy hospodářské povahy (např. ušlý zisk, nedosažení předpokládaných úspor a podobně).

Prosíme, vezměte na vědomí, že informace uvedené v této dokumentaci nemají povahu záruky, vyjádřené výslovně nebo vyplývající z okolností (implicitně), a to zejména záruky vhodnosti pro konkrétní účel či záruky použitelnosti v jiných právních řádech než je právní řád České republiky.

Ochrana osobních údajů

Služba MojeID byla vyvinuta v České republice a její politiky ochrany osobních údajů jsou v souladu s právní úpravou ochrany osobních údajů České republiky, včetně stanovisek Úřadu na ochranu osobních údajů. Před užitím služby MojeID mimo území České republiky se ujistěte, že politiky ochrany osobních údajů služby MojeID odpovídají požadavkům právních předpisů příslušné země.

Rozhodné právo a příslušnost soudu

Dokumentace k implementaci služby MojeID (a související dokumenty) se řídí a vykládá ve všech ohledech v souladu s českým právem. Veškeré spory nebo nároky vzniklé nebo související s užitím služby MojeID (nebo této dokumentace), vč. jejího výkladu, provádění, neplatnosti atd. budou s konečnou platností rozhodovány Rozhodčím soudem při Hospodářské komoře České republiky a Agrární komoře České republiky (dále jen „soud“) podle jednacího řádu tohoto soudu jedním rozhodcem jmenovaným předsedou tohoto soudu.

Podmínky užití loga MojeID

Sdružení CZ.NIC je vykonavatelem majetkových autorských práv k obrazovému označení – logu MojeID a jeho odvozených modalit. Sdružení CZ.NIC tímto uděluje oprávnění logo MojeID a jeho odvozené modality užít v souvislosti s implementací, užitím služby MojeID a její propagací či propagací sdružení CZ.NIC a jeho produktů, a to všemi obvyklými způsoby užití loga. Oprávnění logo MojeID a jeho odvozené modality užít je bezúplatné, nevýhradní, množstevně, územně neomezené a omezené časově ve vztahu k užití služby MojeID. Uživatel není povinen oprávnění užít logo MojeID a jeho odvozené modality využít. Bez souhlasu sdružení CZ.NIC nesmí být oprávnění užít logo MojeID a jeho odvozené modality postoupeno třetí osobě. Logo MojeID a jeho odvozené modality nesmí být zneužity k poškození dobrého jména sdružení CZ.NIC nebo použity v rozporu se zájmy sdružení CZ.NIC. Žádným způsobem nesmí být logo MojeID a jeho odvozené modality znevažovány či užívány nedůstojným způsobem. Logo MojeID a jeho modality musí být vyobrazeny tak, jak je uvedeno v grafickém manuálu a pouze v tomto vyobrazení smí být užívány.

1. Úvod

Tento dokument obsahuje obecný úvod do principů a fungování služby MojeID. Naleznete zde také příklady a další obecné informace, které vám pomohou navrhnout jakým způsobem implementovat podporu služby MojeID do vaší webové aplikace. Získáte tak rychlý základní přehled o krocích, které bude potřeba provést při implementaci podpory MojeID a budete moci odhadnout náročnost této implementace.

MojeID aktuálně nabízí tři autentizační protokoly, které je možné použít. Jsou to OpenID Connect, OpenID 2.0 a SAML 2.0.

Tip

Pokud zatím žádný z těchto protokolů ve svém systému nevyužíváte, doporučujeme použít OpenID Connect.

Jedná se o nejnovější z nabízených protokolů a do jeho vlastností se tak promítají zkušenosti z používání ostatních dvou protokolů. Jeho hlavními přednostmi jsou jednoduchost implementace a podpora mobilních platforem.

Samozřejmě pokud již ve svém systému máte implementován protokol OpenID 2.0 nebo SAML 2.0, je logickým krokem využít tentýž protokol i pro integraci s MojeID.

2. Terminologie

V dalších kapitolách týkajících se implementace MojeID bude používána následující terminologie:

Poskytovatel služeb

provozovatel webové aplikace (či přeneseně samotná aplikace, protože vše je řešeno automaticky bez manuálních zásahů), která požaduje ověření uživatelovy identity pomocí MojeID.

Plný přístup

varianta nasazení služby MojeID u poskytovatele služeb, pro podrobnosti viz https://www.mojeid.cz/cs/pro-poskytovatele/varianty-ceny/.

Omezený přístup

varianta nasazení služby MojeID u poskytovatele služeb, pro podrobnosti viz https://www.mojeid.cz/cs/pro-poskytovatele/varianty-ceny/.

Identita

soubor dat o uživateli, které jsou vázané na identifikátor a jsou spravované poskytovatelem OpenID.

Identifikátor

URL se schématem http nebo https, pod kterým jsou definovaná a dostupná určitá data v rámci procesu ověřování identity, např. http://specs.nic.cz/attr/contact/valid.

Realm

oblast URL poskytovatele služeb definující část prostoru URL, pro níž je žádost o ověření identity platná.

OP
Poskytovatel OpenID
OpenID poskytovatel

zřizovatel a správce OpenID2 identit, na jehož webu dochází k autentizaci. V případě MojeID vždy CZ.NIC.

OCP
Poskytovatel OpenID Connect
OpenID Connect poskytovatel

zřizovatel a správce OpenID Connect identit, na jehož webu dochází k autentizaci. V případě MojeID vždy CZ.NIC.

Jméno identity

jméno MojeID identity ve tvaru jmenoidentity.mojeid.cz, které uživatel uvede do přihlašovacího formuláře jako identitu, pod kterou se chce přihlásit, např. demo.mojeid.cz.

Prohlášený identifikátor

identifikátor vzniklý ze jména identity, pod kterým je tato identita dostupná u OpenID poskytovatele a odkud lze získat metadata k tomuto identifikátoru, např. https://demo.mojeid.cz/#JeDineCny.

Koncový bod OP

URL adresa, na které poskytovatel OpenID2 přijímá zprávy. V případě MojeID je to vždy https://mojeid.cz/endpoint/.

Registration Endpoint

adresa URL, na které je možné zaregistrovat nového poskytovatele služeb podle specifikace OpenID Connect Dynamic Client Registration.

Client ID

jednoznačný identifikátor služby využívající OpenID Connect. K jeho přidělení dojde v průbehu registrace a používá se při veškeré komunikaci přes OpenID Connect.

Client Secret

heslo, kterým se prokazuje autenticita poskytovatele služeb v souvislosti s jeho Client ID. Toto heslo je možné změnit se znalostí Registration Access Token.

Registration Access Token

token, kterým je autentizovaná jakákoliv změna údajů o službě, například Client Secret.

Authorization Endpoint

adresa URL, na kterou poskytovatelé služeb přesměrovávají uživatele za účelem příhlášení.

ID Token

obsahuje ujištění o úspěšně provedeném ověření totožnosti uživatele, jehož údaje jsou obsažené uvnitř ID Tokenu.

Access Token

token, kterým je autentizovaný požadavek na UserInfo Endpoint.

UserInfo Endpoint

adresa URL, na které je možné s využitím Access Token získat detailní údaje o uživateli, pokud nejsou přítomny v ID Tokenu.

Token Endpoint

adresa URL, na které je možné získat Access Token, případně Refresh Token, pokud nebyly získány přímo v odpovědi na autentizaci.

Refresh Token

token, který je možné použít pro získání údajů z UserInfo Endpoint i bez přítomnosti uživatele.

3. Seznámení s MojeID

Tato kapitola vás seznámí se základními principy služby MojeID, podobou identit MojeID a procesem komunikace přes podporované protokoly.

3.1. Základní principy MojeID

MojeID je služba, která dovoluje uživatelům zřídit si a centrálně spravovat svoji internetovou identitu (soubor osobních údajů, například jméno, příjmení, e-mailová adresa, telefon a další, doplněný o přihlašovací metody a údaje). S takovou identitou se pak uživatelé mohou přihlašovat na libovolných externích webových aplikacích (aplikací jiných poskytovatelů služeb než je poskytovatel identit), přičemž si nemusí vytvářet nové účty a opakovaně u nich vyplňovat základní informace a používat různá přihlašovací jména a hesla.

Služba MojeID je konkrétní implementací standardu OpenID ve verzi 2.0 a OpenID Connect ve verzi 1.0 pro decentralizovanou správu internetových identit, které definují, jak se tyto centrálně spravované identity ověřují a jak vypadají jejich identifikátory.

Účet MojeID lze propojit s Národním bodem pro identifikaci a autentizaci (NIA), čímž se ověří identita uživatele, který tak získá přístup ke službám veřejné správy. Více informací naleznete v kapitole Napojení MojeID na NIA.

MojeID je specifické pro prostředí českého internetu a nabízí poskytovatelům služeb další výhody oproti standardnímu OpenID, například rozšířenou sadu osobních údajů v identitách a jejich předávání nebo více přihlašovacích metod s možností požadovat určitou úroveň autentizace.

3.2. MojeID identita

Uživatelé si při zakládání identity musí zvolit jméno své identity, které jednoznačně určuje každou MojeID identitu a které má vždy tvar jmenoidentity.mojeid.cz (bez diakritiky!), např. demo.mojeid.cz.

Toto jméno pak uživatelé používají pro přihlašování na stránkách poskytovatele služeb.

MojeID identita obsahuje:

  • Údaje, které o sobě uživatel do identity uvede (běžné osobní údaje jako jméno, adresa, telefon, přezdívka, apod.)

  • Údaje, které jsou o uživateli poskytovány provozovatelem služby MojeID (zejména informace o fyzickém ověření identity, resp. vybraných osobních údajích uživatele tzv. validaci, či údaj o tom, zda je osoba starší 18 let.)

Tip

Konkrétní výčty údajů, které je možné z MojeID identity předat přes jednotlivé protokoly, obsahuje Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0), Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)Příloha č. 3 – Seznam údajů pro předání (SAML).

3.3. Komunikace s MojeID

V této sekci jsou obecně popsány procesy komunikace, které probíhají při přihlašování uživatele MojeID ke službě, která podporuje daný protokol.

3.3.1. Proces komunikace přes OpenID Connect

Proces přihlášení pomocí MojeID je možný několika různými způsoby (podle různých schémat), které se skládají z několika kroků. Při implementaci je možné zvolit schéma(ta) podle vašich preferencí.

Počáteční kroky jsou společné pro všechna schémata:

  1. Registrace klienta – Před použitím protokolu OpenID Connect je nutné registrovat svého klienta na serverech MojeID.

  2. Žádost o přihlášení přes MojeID – Uživatel klikne na tlačítko „Přihlásit přes MojeID“.

  3. Žádost o ověření identity – Poskytovatel služeb sestaví žádost o ověření identity a tu nepřímo skrze přesměrování uživatelova prohlížeče odešle na koncový bod poskytovatele (Authorization Endpoint) OpenID Connect, kde se uživatel autentizuje.

  4. Provedení autentizace – Uživatel se na přihlašovací stránce MojeID přihlásí pomocí některé z přihlašovacích metod a tím je jeho identita ověřena. V současnosti je podporováno heslo, digitální certifikát, jednorázové heslo a bezpečnostní token (FIDO 2).

Další kroky závisí na zvoleném schématu:

3.3.1.1. Implicitní schéma
_images/Implicit.png

  1. Odpověd s výsledkem ověření identity – Po přihlášení a potvrzení je uživatel přesměrován zpět na stránky poskytovatele služeb a prostřednictvím svého prohlížeče tak předá odpověď ze serverů MojeID s identifikátorem uživatele a ID tokenem. Pokud o to poskytovatel služeb v žádosti o ověření identity požádá, obsahuje ID token i data o uživateli.

3.3.1.2. Přístupový kód
_images/Authorization.png

  1. Odpověď s přístupovým kódem – Po přihlášení a potvrzení je uživatel přesměrován zpět na stránky poskytovatele služeb a prostřednictvím svého prohlížeče tak předá odpověď ze serverů MojeID s přístupovým kódem.

  2. Žádost o token – Poskytovatel služeb sestaví žádost o token, ve kterém použije právě získaný přístupový kód, a odešle ji na Token Endpoint.

  3. Odpověď s tokenem – Poskytovatel služeb obdrží odpověď s přístupovým tokenem a ID tokenem

  4. Žádost o data – Poskytovatel služeb sestaví žádost o uživatelská data s využitím získaného přístupového tokenu a odešle ji na UserInfo Endpoint.

  5. Odpověď s daty – Poskytovatel služeb obdrží odpověď s daty uživatele.

3.3.1.3. Hybridní schéma
_images/Hybrid.png

  1. Odpověď s přístupovým kódem – Po přihlášení a potvrzení je uživatel přesměrován zpět na stránky poskytovatele služeb a prostřednictvím svého prohlížeče tak předá odpověď ze serverů MojeID s přístupovým kódem.

  2. Žádost o token – Poskytovatel služeb sestaví žádost o token, ve kterém použije právě získaný přístupový kód, a odešle ji na Token Endpoint.

  3. Odpověď s tokenem – Poskytovatel služeb obdrží odpověď s přístupovým tokenem a ID tokenem, který obsahuje data uživatele.

3.3.1.4. Volba schématu

Pro webové služby, které běží jen v prohlížeči („bez serveru“, např. JavaScript), je nejvhodnější Implicitní schéma.

Pro serverové služby je vhodnější schéma Přístupový kód, které poskytuje vyšší úroveň zabezpečení.

Následující tabulka shrnuje základní vlastnosti jednotlivých schémat a slouží jako pomůcka pro výběr vhodného schématu přihlášení.

Vlastnost

Implicitní schéma

Přístupový kód

Hybridní schéma

Všechny tokeny jsou vráceny z Authorization Endpoint

ano

ne

ne

Všechny tokeny jsou vráceny z Token Endpoint

ne

ano

ne

Tokeny nejsou viditelné v User Agent

ne

ano

ne

Klient může použít autentizaci

ne

ano

ano

Lze získat Refresh token

ne

ano

ano

Komunikace v jednom požadavku

ano

ne

ne

Většina komunikace probíhá server-to-server

ne

ano

různé

3.3.2. Proces komunikace přes OpenID 2.0

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Proces přihlášení pomocí MojeID se skládá z několika kroků, viz následující schéma:

img-2

  1. Ustanovení asociace – Dohodnutí sdíleného tajemství, pomocí kterého se budou ověřovat zprávy od poskytovatele OpenID.

  2. Žádost o přihlášení přes MojeID – Uživatel klikne na tlačítko „Přihlásit přes MojeID“.

  3. Iniciace – V rámci iniciace se získají metadata o poskytovateli OpenID.

  4. Žádost o ověření identity – Poskytovatel služeb sestaví žádost o ověření identity a tu nepřímo skrze přesměrování uživatelova prohlížeče odešle na koncový bod poskytovatele OpenID, kde se uživatel autentizuje.

  5. Provedení autentizace – Uživatel se na přihlašovací stránce MojeID přihlásí pomocí některé z přihlašovacích metod a tím je jeho identita ověřena. V současnosti je podporováno heslo, digitální certifikát, jednorázové heslo a bezpečnostní token (FIDO 2).

  6. Odpověď s výsledkem ověření identity – Pokud o to poskytovatel služeb v žádosti o ověření identity požádá, je uživatel přesměrován zpět na stránky poskytovatele služeb a přes uživatelův prohlížeč je mu předána odpověď s výsledkem ověření identity.

  7. Ověření odpovědi – Každá zpráva, kterou poskytovatel služeb obdrží od poskytovatele OpenID nepřímo přes uživatelův prohlížeč musí být ověřena, zda opravdu pochází od poskytovatele OpenID a nebyla změněna. To se udělá buď pomocí asociace, viz bod 0 (ve valné většině případů), nebo se musí o toto ověření požádat.

  8. Zpracování odpovědi – Na základě toho, zda se jedná o úspěšné či neúspěšné přihlášení, musí aplikace poskytovatele služeb reagovat a případně zpracovat další data, která jsou z této odpovědi získána.

3.4. Favikona

Favikona je grafický prvek (ikona) asociovaný s určitou webovou stránkou nebo v případě MojeID službou. Webové prohlížeče umí zobrazit favikonu jako vizuální symbol identity webové stránky v adresním řádku, na záložkách nebo v oblíbených.

MojeID zobrazuje favikonu u názvu služby, ke které se uživatel MojeID přihlašuje, v přihlašovacím formuláři MojeID.

Příklad zobrazení favikony

Příklad zobrazení favikony

Použití favikony se liší podle protokolu.

3.4.1. Nastavení v OpenID Connect

Soubor favikony nahrajete na svůj web a jeho adresu nastavíte jako metadata (logo_uri) v registraci vašeho klienta, viz Registrace klienta.

Pokud se na nastavené URI ikona nachází, pak je ve formuláři MojeID zobrazena, a to bez ohledu na typ přístupu (plný/částečný) služby k MojeID.

3.4.2. Nastavení pro OpenID 2.0 a SAML

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Soubor favikony musíme explicitně nahrát do našeho systému.

Favikona se stahuje buď automaticky (1× týdně) nebo ji můžete dodat CZ.NICu přímo (např. e-mailem na adresu podpory) a my favikonu nahrajeme manuálně. Algoritmus při automatickém stahování hledá favikonu na realmu poskytovatele dle standardu W3C pro favikony, sekce Method 1.

Favikona nesmí být větší než 10 kB. Podporované formáty jsou ICO a PNG.

Zobrazení favikony u služeb komunikujících tímto protokolem je umožněno, jen pokud služba má plný přístup.

3.5. Napojení MojeID na NIA

Účet MojeID lze napojit na Národní bod pro identifikaci a autentizaci (NIA). Napojením se ověří identita uživatele, který tak získá přístup ke službám veřejné správy. Napojení účtu na NIA je možné pouze u fyzické osoby. Pokud je v účtu vyplněno pole Organizace, není napojení na NIA možné.

Předávané údaje ověřené přes NIA: Křestní jméno, Příjmení, Adresa trvalého bydliště, Datum narození. Takto ověřené údaje v účtu nelze měnit, jsou aktualizovány automaticky z registru obyvatel. Pokud chce uživatel uzamčené údaje upravit, musí zrušit napojení na NIA, čímž přijde o možnost přihlašování ke službám veřejné správy. Následnou úpravou údajů přijde i o ověření totožnosti.

MojeID podporuje dvě úrovně záruky dle eIDAS: „značná“ (substantial) a „vysoká“ (high). Poskytovatel si může vyžádat přihlášení takto ověřeným účtem pouze při použití protokolů SAML a OIDC.

Více informací, jak vyžádat takové přihlášení, naleznete v jednotlivých protokolech:

4. Implementace podpory MojeID

Tato kapitola vás podrobněji provede jednotlivými fázemi komunikačního procesu, které je potřeba při implementaci podpory protokolu zohlednit, a prerekvizitami, které je potřeba pro funkční implementaci splnit.

Důležité

MojeID z bezpečnostních důvodů nedovoluje zobrazení přihlašovací stránky v rámcích (<iframe>).

4.1. Implementace pomocí OpenID Connect (OIDC)

V této sekci se seznámíte s technickými aspekty implementace služby MojeID pomocí protokolu OpenID Connect do webových aplikací.

Znalost tohoto textu je doporučená pro dobré a přesné porozumění principů a procesů fungování MojeID / OpenID Connect. Většinu toho, co zde bude popsáno, vyřeší dostupné knihovny pro implementaci OpenID Connect, které doporučujeme využívat.

Sekce Přehled kroků implementace vás provede procesem implementace krok za krokem. Další sekce se jednotlivými kroky zabývají více dopodrobna.

Oficiální specifikaci protokolu OpenID Connect naleznete na https://openid.net/specs/openid-connect-core-1_0.html.

Server MojeID zveřejňuje základní informace o konfiguraci OIDC na adrese https://mojeid.cz/.well-known/openid-configuration/.

Pro otestování implementace je vám k dispozici Testovací instance MojeID.

Seznam údajů, které mohou být protokolem předány, (vč. jejich identifikátorů) obsahuje Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

Příklady a řešení chybových hlášek obsahuje Příloha č. 6 – Příklady a řešení chybových hlášek.

Poznámka

Všechny dále uvedené příklady zdrojových kódů ilustrují implementaci v jazyce Python za použití knihovny pyoidc.

4.1.1. Přehled knihoven a modulů

Na oficiálních stránkách OpenID Foundation najdete seznam certifikovaných implementací protokolu OIDC v několika programovacích jazycích, viz Certified OpenID Connect Implementations. Pro vás jsou zajímavé implementace pro Relying Party, která odpovídá poskytované službě.

Pro použití v mobilních aplikacích je vhodné využít knihovny pro nativní aplikace:

Dále je možné použít moduly pro nejpopulárnější platformy:

Pokud víte o nějakém dalším, který by tu neměl chybět, budeme rádi, když se s námi o tuto informaci podělíte (techsupport@mojeid.cz).

Upozornění

Upozorňujeme, že užití modulů je pouze na vlastní nebezpečí a sdružení CZ.NIC, z. s. p. o. v žádném případě neodpovídá za způsobené škody.

4.1.2. Přehled kroků implementace

Tento přehled obsahuje organizační a technické kroky, které musíte provést v rámci implementace přihlášení do vaší služby přes MojeID protokolem OpenID Connect. Jednotlivé kroky jsou pro přehlednost stručné a říkají, co je třeba udělat, zatímco cíle odkazů rozvádí, jak to udělat, nebo obsahují doplňující informace. Přehled může sloužit jako kontrolní seznam (checklist).

Příprava testovacího prostředí

  1. Zaregistrovat službu (klienta) na testovacím Registration Endpointu – tím získáte testovací metadata svojí služby (Client ID, Client Secret) a máte možnost nastavit některé parametry komunikace.

    Poznámka

    V případě Automatické registrace platnost Client Secret za určitou dobu vyprší. Pokud se rozhodnete používat Automatickou registraci, je v implementaci potřeba pamatovat na to, aby registraci prodlužovala.

  2. Poslat testovací metadata služby (Client ID) na podporu (techsupport@mojeid.cz). Podpora nastaví přístupy.

  3. Založit a nastavit testovací účty MojeID.

Implementace a ladění

Budete potřebovat: textový editor, prohlížeč, přístup k hostingu, specifikace OIDC

Pro ladění implementace se vám mohou hodit naše doporučení k ladícím nástrojům. Během ladění můžete narazit na různá chybová hlášení, při jejichž řešení vám může pomoci Příloha č. 6 – Příklady a řešení chybových hlášek.

  1. Zavést tlačítko a odkazy MojeID do (šablon/stránek) služby, přes které bude uživatel žádat o přihlášení. Dodržujte Zásady správné implementace!

  2. Získat konfiguraci testovacího poskytovatele OIDC (webfinger).

  3. Konfigurace knihovny – vyplnit testovací Client IDClient Secret, případně i testovací endpointy, pokud to knihovna neumí zjistit sama z konfigurace poskytovatele OIDC.

  4. Sestavit a odeslat požadavek na autentizaci na Authorization Endpoint.

    Poznámka

    Požadavek má mimo jiné obsahovat volbu schématu autentizace. Kroky popsané dále odpovídají schématu Přístupový kód.

  5. Zpracovat odpověď na autentizaci na návratové adrese uvedené v požadavku, která obdrží přístupový kód (code).

  6. Sestavit a odeslat požadavek o token na Token Endpoint. V požadavku použijete získaný přístupový kód.

  7. Zpracovat odpověď, z níž získáte Access Token (access_token) a ID Token (id_token, Co obsahuje ID Token?), jehož platnost musí implementace ověřit (viz ID Token Validation).

  8. Pokud je ID Token validní, sestavit a odeslat požadavek o data uživatele na UserInfo Endpoint. V požadavku použijete Access Token.

  9. Zpracovat odpověď s daty uživatele podle potřeb vaší služby.

Ověření implementace

Pokud budete chtít službu provozovat s plným přístupem, musíme před převedením služby na ostrý provoz provést uživatelské testování vaší implementace.

  1. Až dokončíte ladění implementace, zašlete na podporu (techsupport@mojeid.cz) oznámení, že je vaše implementace připravena k uživatelskému testování, a přiložte adresu testovací instance vaší služby.

  2. Jakmile společně doladíme poslední detaily, implementace bude připravena pro přechod na ostrý provoz.

Přechod na ostrý provoz

  1. Pro plný přístup nejprve podepsat smlouvu.

  2. Zaregistrovat službu (klienta) na ostrém Registration Endpointu, čímž získáte ostrá metadata svojí služby a nastavíte parametry komunikace.

  3. Poslat ostrá metadata služby (Client ID) na podporu (techsupport@mojeid.cz) a to i v případě částečného přístupu.
    Podpora zavede službu do katalogu.

  4. Získat konfiguraci ostrého poskytovatele OIDC (webfinger).

  5. Překonfigurovat implementaci s ostrými metadaty, případně i endpointy.

A je hotovo.

4.1.3. Registrace klienta

Pro komunikaci se službou MojeID přes protokol OpenID Connect je potřeba zaregistrovat klienta (službu) na serveru MojeID. Je možné využít buď ruční, či automatické registrace. Automatická registrace je vhodná pro dynamicky vytvářené klienty (JS, mobilní zařízení) a ruční registrace je vhodná pro serverové klienty.

4.1.3.1. Ruční registrace

Ruční registraci lze provést na adrese https://mojeid.cz/consumer_admin/. V případě testovací instance MojeID na adrese https://mojeid.regtest.nic.cz/consumer_admin/. Na stejné adrese lze pak spravované klienty i upravovat či mazat. Takto vytvoření klienti mají dobu platnosti nastavenou na neurčito. Specifikace jednotlivých položek lze nalézt v dokumentaci protokolu OpenID Connect (https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata).

Příklad ruční registrace klienta v testovací instanci MojeID:

  1. U libovolného účtu, který vytvoříte v testovací instanci MojeID, přejděte po přihlášení na https://mojeid.regtest.nic.cz/consumer_admin/.

  2. Přejděte na odkaz Založení nové služby. Vyplňte požadované položky Název klienta, Seznam URI a klikněte na tlačítko Uložit.

    • V seznamu spravovaných služeb se vytvoří záznam s ID klienta.

  3. Pro získání Client secret / Tajemství klienta přejděte v nově přidané službě na odkaz Aktualizovat.

    • Zobrazí se stránka pro editaci nastavení ‒ Tajemství klienta najdete v posledním řádku zobrazeného formuláře.

  4. Pro vyzkoušení vašeho nastavení v testovací instanci můžete využít testovací rozhraní na adrese https://mojeid.regtest.nic.cz:8000/consumer/oic/register/, kde zaregistrujete vytvořeného klienta. Dále pokračujte na adresu https://mojeid.regtest.nic.cz:8000/consumer/oic/start/, kde vyberte vytvořeného klienta. Zde můžete testovat různé scénáře předávání údajů.

4.1.3.2. Automatická registrace

Podrobnosti lze nalézt v dokumentaci protokolu OpenID Connect (https://openid.net/specs/openid-connect-registration-1_0.html). O potřebná nastavení by se měla postarat použitá knihovna. Takto vytvořené registrace vyprší po uplynutí 24 hodin, ale je možné je prodlužovat (viz Změna registrace).

Příklad registrace klienta s použitím knihovny:

from oic.oic.consumer import Consumer

client = Consumer(SessionDB(URL), OIC_CONFIG, client_config=OIC_CLIENT_CONFIG)
client.redirect_uris = URL + client.consumer_config['authz_page']
provider_info = client.provider_config(ISSUER)
client.register(provider_info["registration_endpoint"], response_types='code', client_name=MY_CLIENT_NAME)

Příklad registračního dotazu:

POST /oidc/registration HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: mojeid.cz

{
 "application_type": "web",
 "redirect_uris":
     ["https://client.example.org/callback",
      "https://client.example.org/callback2"],
 "client_name": "My Example",
 "logo_uri": "https://client.example.org/logo.png",
 "token_endpoint_auth_method": "client_secret_post"
}

Příklad odpovědi serveru na registrační dotaz:

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "client_id": "s6BhdRkqt3",
 "client_secret": "ZJYCqe3GGRvdrudKyZS0XhGv_Z45DuKhCUk0gBR1vZk",
 "client_secret_expires_at": 1577858400,
 "registration_access_token": "MY.SECRET.REGISTRATION.ACCESS.TOKEN",
 "registration_client_uri": "https://mojeid.cz/oidc/registration?client_id=s6BhdRkqt3",
 "token_endpoint_auth_method": "client_secret_post",
 "application_type": "web",
 "redirect_uris":
     ["https://client.example.org/callback",
      "https://client.example.org/callback2"],
 "client_name": "My Example",
 "logo_uri": "https://client.example.org/logo.png"
}

Poznámka

Vyřízení registrace a získání Client ID a Client Secret lze provést i bez knihovny, stačí třeba poslat dotaz POST přes curl.

Příklad:

curl --data '{"redirect_uris": "https://navratova-adresa.cz",
  "client_name": "Název služby"}' https://mojeid.cz/oidc/registration/

Registrace umožňuje také s registrací klienta asociovat metadata (viz Client Metadata ve specifikaci), takže si poskytovatel může nadefinovat např. název a ikonu služby, konkrétně atributy client_name, logo_uri, případně client_uri.

4.1.3.2.1. Informace o registraci

Součástí odpovědi serveru MojeID na provedenou registraci je i adresa URL, na které lze získat aktuální informace o registraci (konfigurační endpoint registration_client_uri), a přístupový kód (registration_access_token). Při dotazu GET na tuto adresu URL je nutné se autentifikovat pomocí přístupového kódu. Ten je nutné zahrnout do hlavičky Authorization požadavku HTTP.

Odpověď serveru je ve stejném formátu jako odpověď při registraci a obsahuje aktuální informace o vašem klientovi na našem serveru.

4.1.3.2.2. Změna registrace

Pomocí výše uvedeného konfiguračního endpointu je možné i editovat některé informace o registrovaném klientovi. Pro konfiguraci je nutné použít dotaz POST, opět doplněný o registration_access_token v hlavičce Authorization. Formát požadavku je stejný jako v případě registrace a stejné je i jeho zpracování na serveru s následujícími výjimkami:

  • Není možné změnit registrované redirect_uriclient_id.

  • Hodnota client_secret je ignorována. V případě přítomnosti položky v dotazu je vygenerován nový client_secret. Ten je zaslán v odpovědi na konfigurační dotaz.

Příklad konfiguračního dotazu, který zajistí vygenerování nového client_secret a změnu logo_uripolicy_uri.

POST /oidc/registration?client_id=MYCLIENTID HTTP/1.1
Accept: application/json
Host: mojeid.cz
Authorization: Bearer MY.SECRET.REGISTRATION.ACCESS.TOKEN

{
 "client_secret": null,
 "logo_uri": "https://client.example.org/another-logo.png",
 "policy_uri": "https://client.example.org/policy-page"
}

Odpověď serveru na konfigurační dotaz je stejná jako odpověď na registrační dotaz a obsahuje aktuální informace o vašem klientovi na našem serveru.

4.1.4. Žádost o přihlášení přes MojeID

Proces ověřování uživatelovy identity začne tím, že na vašich stránkách uživatel podá žádost o přihlášení přes MojeID. Pro maximální uživatelskou přívětivost stačí pouze tlačítko pro přihlášení „Přihlásit přes MojeID“, viz soubor Grafické prvky na stránce Jak zavést. Uživatelské jméno uživatel zadá později na serveru MojeID.

Přihlašování ke službě MojeID tlačítkem je jediná doporučená a správná metoda.

4.1.5. Iniciace

Abyste mohli odeslat žádost o ověření identity, potřebuje vaše knihovna znát buď identifikátor uživatele nebo koncový bod OCP.

Pomocí identifikátoru nebo koncového bodu provede vaše aplikace WebFinger dotaz pro zjištění podrobností o OpenID Connect poskytovateli. Odpověď na tento dotaz obsahuje mimo jiné i:

  • Autorizační endpoint – to je vždy https://mojeid.cz/oidc/authorization/ a na tuto adresu budou směřovány žádosti o ověření identity.

  • Token endpoint – to je vždy https://mojeid.cz/oidc/token/ a na tuto adresu jsou směřovány žádosti o token.

  • UserInfo endpoint – to je vždy https://mojeid.cz/oidc/userinfo/ a na tuto adresu jsou směřovány žádosti o uživatelská data.

Příklad dotazu na konkrétního uživatele:

GET /oidc/.well-known/webfinger?resource=acct%3Ajoe%40mojeid.cz&rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: mojeid.cz

Příklad odpovědi serveru:

HTTP/1.1 200 OK
Content-Type: application/jrd+json

{
 "subject": "acct:joe@mojeid.cz",
 "links": [
    {"rel": "http://openid.net/specs/connect/1.0/issuer",
     "href": "https://mojeid.cz/oidc/"}
 ]
}

4.1.6. Žádost o ověření identity

Jakmile znáte koncový bod OCP, zašle vaše aplikace skrze přesměrování uživatelova prohlížeče žádost o ověření identity (autentizaci). Žádost obsahuje speciální parametry pro její realizaci. O správné uvedení těchto parametrů se opět postará použitá OpenID Connect knihovna použitá pro implementaci.

Žádost o ověření identity obsahuje obvykle následující parametry:

  • Návratovou adresu (URL) aplikace – Na tuto adresu se vrátí uživatel po přihlášení ze stránek poskytovatele OpenID Connect a zde bude výsledek přihlášení zpracován.

  • Požadované skupiny údajů z MojeID – Žádost o ověření identity musí jako požadovanou skupinu údajů obsahovat alespoň openid.

  • Požadované údaje z MojeID – Do žádosti o ověření identity lze přidat i seznam jednotlivých údajů z MojeID identity, které vaše aplikace vyžaduje a které budou po úspěšném přihlášení a se souhlasem uživatele aplikaci předány. Pro každý údaj je nutné uvést jeho identifikátor. Údaje a jejich identifikátory obsahuje Příloha č. 1 – Seznam údajů pro předání (OpenID Connect). Tento seznam je ve formátu JSON specifikovaném v dokumentaci OpenID Connect. Položky mohou být označeny za povinné pomocí výrazu "essential": true.

Příklad položek v požadavku, které může žádost o ověření identity obsahovat, shrnuje následující tabulka:

Parametr (klíč)

Popis a hodnota

scope

Seznam požadovaných skupin údajů
openid address

response_type

Určení požadovaného schématu autentizace
id_token

client_id

Jednoznačný identifikátor poskytovatele služeb
test_clienti

redirect_uri

Návratová adresa z MojeID.
http://www.poskytovatel-example.cz/

claims

Podrobnější specifikace požadovaných údajů.

{"userinfo":
  {"name": null,
   "nickname": {"essential": true}}
}

Příklad požadavku na autentizaci:

sid, location = client.begin(path=URL, scope=SCOPE)
HttpResponseRedirect(location)

Příklad dotazu požadavku na autentizaci:

Příklad vyžádání údajů pomocí „scope“ (skupiny údajů)
GET /oidc/authorization/?response_type=code&scope=openid%20profile%20email&client_id=s6BhdRkqt3&state=af0ifjsldkj&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
Host: mojeid.cz
Příklad vyžádání údajů pomocí „claims“ (jednotlivé údaje)
GET /oidc/authorization/?state=950ba54cb302a7c6a814f22a4e5c5445&redirect_uri=https%3A%2F%2Fmojeid.cz%3A8000%2Fconsumer%2Foic%2Ffinish%2F&response_type=code&client_id=8ol68PATaSpA&scope=openid&claims=%7B%22userinfo%22%3A+%7B%22name%22%3A+null%2C+%22nickname%22%3A+%7B%22essential%22%3A+true%7D%7D%7D&ui_locales=off HTTP/1.1
Host: mojeid.cz

Odpověď od serveru přijde až po kroku provedení autentizace. Příklad odpovědi je uveden v sekci Odpověď na autentizaci.

4.1.7. Provedení autentizace

V okamžiku, kdy uživatel dorazí s žádostí o ověření identity na server MojeID, je mu zobrazena přihlašovací stránka, kde proběhne samotné přihlášení.

_images/mojeid-login.png

Přihlašovací stránka MojeID

Tato autentizace je provedena servery MojeID. V rámci tohoto ověření se pokusíme provést maximum úkonů, které byly specifikovány pomocí parametrů v žádosti o ověření identity. Celý proces se odehrává pouze v systémech MojeID a z vaší strany nevyžaduje žádnou činnost.

4.1.8. Odpověď na autentizaci

Poté, co uživatel dokončí proces autentizace, obdržíte ze serverů MojeID odpověď s jejím výsledkem. Struktura a obsah této odpovědi se liší v závislosti na vybraném komunikačním schématu (viz Proces komunikace přes OpenID Connect).

V případě využití komunikace přes Implicitní schéma je v odpovědi obsažen identifikátor uživatele a ID token, který může obsahovat data o uživateli.

V případě použití komunikace přes Přístupový kód nebo Hybridní schéma obsahuje odpověď přístupový kód (access code), který je nutné použít v dalším kroku autentifikačního procesu.

Příklad zpracování odpovědi:

aresp, _, _ = client.parse_authz(request.GET.urlencode())

Příklad odpovědi serveru:

HTTP/1.1 302 Found
Location: https://client.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

4.1.9. Žádost o token

Pokud jste v předchozím kroku autentizace obdrželi přístupový kód (access code), musíte ho na Token endpointu vyměnit za platný token.

V případě použití komunikace přes Hybridní schéma obsahuje odpověď přístupový token a ID token, který může obsahovat data o uživateli. V tomto případě je proces autentizace a předání údajů dokončen.

Při komunikaci přes Přístupový kód je v odpovědi opět obsažen token a ID token, ale ten neobsahuje data o uživateli. O ta je nutné si zažádat v dalším kroku.

Příklad komunikace:

POST /oidc/token/ HTTP/1.1
Host: mojeid.cz
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "access_token": "SlAV32hkKG",
 "token_type": "Bearer",
 "refresh_token": "8xLOxBtZp8",
 "expires_in": 3600,
 "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
              yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
              NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
              fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
              AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
              Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
              NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
              QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
              K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
              XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

4.1.10. Žádost o data

V tomto kroku použijete token získaný v předchozím kroku autentizace k získání dat o uživateli. Data je nutné vyzvednout na UserInfo endpointu.

UserInfo endpoint vždy vrací v odpovědi atribut sub (subject), který jednoznačně identifikuje uživatele a měl by být použit k validaci odpovědi podle ID Token.

Data o uživateli by měla být dále zpracována jen v případě, že odpověď byla shledána validní.

Příklad žádosti o data:

state = aresp.to_dict()['state']
resp = client.complete(state)
uinfo = client.get_user_info(state)

Příklad komunikace se serverem:

GET /oidc/userinfo/ HTTP/1.1
Host: mojeid.cz
Authorization: Bearer SlAV32hkKG
HTTP/1.1 200 OK
Content-Type: application/json

{
 "sub": "248289761001",
 "name": "Jane Doe",
 "given_name": "Jane",
 "family_name": "Doe",
 "preferred_username": "j.doe",
 "email": "janedoe@example.com"
}

4.1.11. Knihovna MojeID LITE

Javascriptová knihovna MojeID LITE (nebo také MojeID Connect) umožňuje načtení údajů z identity MojeID do webové stránky na straně klienta za využití protokolu OpenID Connect.

Tuto funkcionalitu je možné využít například pro jednoduché předvyplnění webového formuláře údaji uživatele, který má aktivní účet MojeID.

Abyste existující formulář rozšířili o tuto funkcionalitu, musíte provést minimálně následující kroky:

  1. Vložit odkaz na knihovnu.

    Tuto knihovnu je možné vystavit na vlastním serveru, pokud chcete snížit závislost na externím webu. Knihovna je ke stažení na této adrese. Knihovna závisí na kryptografické knihovně jsrsasign, která je v aktuální verzi k dispozici i na našem webu, takže není nutné ji vkládat přímo. Kód skriptu pro vložení knihovny musí být v sekci <HEAD>.

    Příklad vložení knihovny:

    <script type="text/javascript"
       src="https://www.mojeid.cz/public/media/1542958574/150/"
       data-jsrsasign="https://www.mojeid.cz/public/media/1542956522/149/">
    </script>
    
  2. Zavolat funkci na vytvoření objektu MojeidConnect.

    Tento objekt reprezentuje komunikaci se serverem MojeID. Při volání vytvářející funkce je možné nastavit některé parametry, které ovlivní proces předání údajů. Kód skriptu s voláním funkce musí být v sekci <HEAD>.

    Příklad vytvoření objektu:

    <script type="text/javascript"> (function() {
       mojeid = createMojeidConnect( {
          clientName: "Ukázkový formulář",
          claims: ['phone_number', 'family_name', 'given_name', 'nickname',
             'email', 'address', 'birthdate', 'gender', 'website', 'profile']
       } );
    })();</script>
    
  3. Na tlačítko, které aktivuje předvyplnění formuláře, navěsit volání metody requestAuthentication().

    Tato metoda zajistí nastartování autentizačního procesu a vyplnění hodnot odsouhlasených údajů do formuláře.

    Příklad kódu pro tlačítko:

    <button onclick="mojeid.requestAuthentication()">
    Předvyplnit pomocí MojeID
    </button>
    

Parametry funkce createMojeidConnect(options)

Při volání této funkce je možné ve slovníkové struktuře určit některé parametry, které ovlivní komunikaci se serverem MojeID:

clientID

Je možné, že je služba již zaregistrovaná v MojeID serveru. Pokud ano má tato služba přidělené clientID a toto je možné uvést v parametru. Pokud není clientID vyplněné, dojde k dynamické registraci podle specifikace OpenID Connect s využitím adresy uvedené v parametru regEndpoint.

clientName

V případě dynamické registrace je možné zde uvést název služby, který se zobrazí uživateli při schválení předání údajů. Pokud nebude název uveden, použije se URL služby.

scope

Požadované předávané údaje v podobě skupin údajů. Hodnotou je podseznam ['openid', 'profile', 'email', 'phone', 'address'], přičemž 'openid' musí být uveden vždy. Pokud není uveden, je hodnota ['openid'].

claims

Požadované předávané údaje v podobě jednotlivých atributů. Hodnotou je seznam atributů. Úplný seznam možných atributů je k dispozici v hodnotě claims_supportedkonfiguračního souboru serveru. Jako příklad může sloužit tento seznam: ['phone_number', 'family_name', 'given_name', 'nickname', 'email', 'address', 'birthdate', 'gender', 'website', 'profile']

attrDict

Knihovna předpokládá, že položky formuláře mají stejné id jako je název atributu ze seznamu claims. Pokud toto není pravda, je v tomto parametru možné uvést mapovací seznam pro id formulářové položky a název atributu.

formCallback

Pokud nestačí mapovací slovník z attrDict, je zde možné uvést název vlastní JS funkce, která se postará o vyplnění formuláře.

display

Hodnota je buď popup nebo redirect podle toho, zda se přihlášení má provést v novém okně nebo ve stávajícím. Výchozí hodnota je popup.

regEndpoint

URL registračního endpointu podle specifikace protokolu OpenID Connect. Výchozí hodnota je https://mojeid.cz/oidc/registration/.

authEndpoint

URL autentizačního endpointu podle specifikace protokolu OpenID Connect. Výchozí hodnota je https://mojeid.cz/oidc/authorization/.

Ukázkový formulář

Pro snazší porozumění si můžete on-line prohlédnout a vyzkoušet kompletní ukázkový formulář.

4.1.12. Žádost o ověření identity účtem napojeným na NIA

Žádost o ověření identity účtem MojeID napojeným na NIA se vyžádá pomocí parametru acr_values. Hodnoty pro vyžádání konkrétní úrovně záruky shrnuje tabulka níže.

ACR value

Popis

eidas.europa.eu/LoA/substantial

eIDAS úroveň záruky „značná“

eidas.europa.eu/LoA/high

eIDAS úroveň záruky „vysoká“

Detailní informace o acr_values lze nalézt přímo v dokumentaci OpenID Connect na následujících odkazech:

4.2. Implementace pomocí OpenID 2.0

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

V této sekci se seznámíte s technickými aspekty implementace služby MojeID pomocí protokolu OpenID do webových aplikací.

Znalost tohoto textu je doporučená pro dobré a přesné porozumění principům a procesům fungování MojeID/OpenID. Většinu toho, co zde bude popsáno, vyřeší dostupné knihovny pro implementaci OpenID, které doporučujeme využívat.

Oficiální specifikaci protokolu OpenID naleznete na https://openid.net/developers/specs.

Seznam údajů, které mohou být protokolem předány, (vč. jejich identifikátorů) obsahuje Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0).

Příklady a řešení chybových hlášek obsahuje Příloha č. 6 – Příklady a řešení chybových hlášek.

4.2.1. Přehled knihoven a modulů

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Na oficiálních stránkách OpenID Foundation najdete seznam implementací protokolu OpenID 2.0 v několika programovacích jazycích, viz Libraries for Obsolete Specifications.

K dispozici vám od nás jsou ukázkové implementace pro PHP (ZIP, 140 kB) a Javu (ZIP, 3,5 MB).

Poznámka

Ukázkové implementace nelze rovnou nainstalovat a spustit, tyto implementace tak, jak jsou, nebudou s vaším systémem fungovat. Jsou určeny ke studiu jako vzor pro vytvoření vlastní implementace.

Dále pro několik nejpoužívanějších open-source platforem jsou k dispozici moduly, které jsme vytvořili, abychom implementaci do těchto systémů usnadnili:

Máme archivované i některé další (WordPress, VirtueMart, phpBB, Opencart, osCommerce, Redmine, Zencart), které rádi poskytneme, pokud si o ně zažádáte u naší podpory (techsupport@mojeid.cz).

Upozornění

Upozorňujeme, že užití modulů je pouze na vlastní nebezpečí a sdružení CZ.NIC, z. s. p. o. v žádném případě neodpovídá za způsobené škody.

4.2.2. Ustanovení asociace

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Zprávy, které obdržíte nepřímo přes uživatelův prohlížeč od poskytovatele OpenID, jsou digitálně podepsány. U každé takové zprávy je nutné podpisy ověřit a ujistit se, že opravdu pochází od poskytovatele OpenID. Je pro to možné využít dvou různých možností – tzv. stavovou a bezstavovou komunikaci mezi vaší aplikací a poskytovatelem OpenID.

Při bezstavové komunikaci musíte ověřit zprávu navázáním komunikace s poskytovatelem OpenID se žádostí o ověření konkrétní zprávy. To je náročnější na výkon a čas.

Stavová komunikace začíná dohodnutím sdíleného tajemství ještě před začátkem samotného procesu přihlašování uživatele resp. ověřování identit – tzv. ustanovení asociace. Toto sdílené tajemství má platnost nejdéle 14 dní a po jeho expiraci je nutné ustanovit asociaci znovu. Obě strany (poskytovatel OpenID i vaše aplikace) mohou také kdykoliv během platnosti sdíleného tajemství prohlásit toto sdílené tajemství za neplatné a v tomto případě je pak vhodné ustanovit asociaci znovu tak, aby nebylo nutné používat bezstavovou komunikaci.

Tip

OpenID knihovny, které je možné pro implementaci MojeID využít, mohou používat obě možnosti. Pro běžné podmínky doporučujeme používat stavovou komunikaci v co největší míře. V některých případech je nutné použít i bezstavovou komunikaci např. pokud sdílené tajemství vypršelo nebo jej jedna ze stran zneplatnila, je nutné zprávy ověřovat bezstavovou komunikací do doby, než je ustavena nová asociace.

4.2.3. Žádost o přihlášení přes MojeID

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Proces ověřování uživatelovy identity začne tím, že na vašich stránkách uživatel zažádá o přihlášení přes MojeID.

Pro maximální uživatelskou přívětivost je toto řešeno prostřednictvím tlačítka pro přihlášení. Uživatelské jméno a heslo uživatel zadá později na serveru MojeID.

_images/mojeID_buttons_prehled.png

Ukázka tlačítek pro přihlášení přes MojeID.

Přihlašování ke službě MojeID tlačítkem je jediná doporučená a správná metoda. Tlačítka jsou ke stažení dostupná na https://www.mojeid.cz/cs/pro-poskytovatele/jak-zavest/#download

4.2.4. Iniciace

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Abyste mohli odeslat žádost o ověření identity, musíte u většiny knihoven uvést buď identifikátor uživatele, nebo koncový bod OP. Pokud neznáte identifikátor uživatele (např. v případě přihlášení uživatele), uveďte místo něj koncový bod OP.

Pokud znáte identifikátor uživatele (např. znovuověření uživatele), získáte jeho pomocí metadata o uživatelově identitě a o OpenID poskytovateli včetně koncového bodu OP. Na identifikátor uživatele se pošle HTTP požadavek a v těle stránky, která je tímto požadavkem získána, se nachází mimo jiné i:

  • Prohlášený identifikátor uživatele – Výsledné URL, z něhož se vrátilo tělo stránky s metadaty.

  • Vnitřní identifikátor uživatele – Od jména identity se liší tím, že jde o identifikátor, který má tvar https://mojeid.cz/id/unikatni_retezec, kde unikatni_retezec je unikátní identifikace uživatele v systému MojeID, např. https://mojeid.cz/id/JeDineCny/. Tuto vnitřní identitu je pak potřeba v dalších fázích přihlašovacího procesu kontrolovat, neboť to je identita, kterou rozpoznává poskytovatel OpenID, viz Zpracování odpovědi.

  • Koncový bod OP – je vždy https://mojeid.cz/endpoint/ a na tuto adresu budou směrovány žádosti o ověření identity.

4.2.5. Žádost o ověření identity

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Jakmile znáte koncový bod OP, případně i prohlášený identifikátor a vnitřní identifikátor, zašle vaše aplikace skrze přesměrování uživatelova prohlížeče žádost o ověření identity (o autentizaci). Žádost obsahuje speciální parametry pro její realizaci. Tyto parametry se uvádějí pomocí svých identifikátorů do těla zprávy. Konstrukci této žádosti o ověření identity opět přímo zajistí OpenID knihovny, které budete pro implementaci používat.

Žádost o ověření identity obsahuje obvykle následující parametry:

  • Návratovou adresu (URL) aplikace poskytovatele služby - Na tuto adresu se vrátí uživatel po provedení přihlášení ze stránek poskytovatele OpenID a zde bude výsledek přihlašování vaší aplikací zpracován.

  • Oblast URL poskytovatele služeb (dále jen jako realm) – definuje část prostoru URL, pro niž je žádost o ověření identity platná. Návratová adresa poskytovatele služeb musí ležet v této oblasti URL. Na této nebo odpovídající adrese musí být k dispozici XRDS dokument nebo zveřejněna jeho poloha.

  • Volba vyžadované přihlašovací metody – volba se provede umístěním identifikátoru příslušné přihlašovací metody do žádosti o ověření identity. Služba MojeID podporuje mimo běžného přihlašování heslem i přihlašování pomocí digitálního certifikátu, jednorázového hesla (OTP) nebo bezpečnostního tokenu.

    • Přihlášení pomocí certifikátu je možné vyžádat s pomocí rozšíření PAPE použitím identifikátoru:
      http://schemas.openid.net/pape/policies/2007/06/phishing-resistant

      V případě přihlášení pomocí certifikátu se uživateli zobrazují následující hlášky:
      „Poskytovatel služby požaduje přihlášení certifikátem.“
      „The service provider wants you to login with your certificate.“

    • Přihlášení pomocí jednorázového hesla nebo aplikace MojeID Autentikátor je možné vyžádat použitím identifikátoru:
      http://schemas.openid.net/pape/policies/2007/06/multi-factor

      V případě přihlášení pomocí jednorázového hesla se uživateli zobrazují následující hlášky:
      „Poskytovatel služby požaduje přihlášení jednorázovým heslem nebo MojeID Autentikátorem.“
      „The service provider wants you to login with one time password or MojeID Autentikátor.“

    • Přihlášení pomocí bezpečnostního tokenu je možné vyžádat použitím identifikátoru:
      http://schemas.openid.net/pape/policies/2007/06/multi-factor-physical

    V případě přihlášení pomocí bezpečnostního tokenu se uživateli zobrazují následující hlášky:
    „Poskytovatel služby požaduje přihlášení druhým faktorem.“
    „The service provider wants you to login with two-factor authentication.“

  • Omezení doby přihlášení uživatele – pokud se uživatel úspěšně přihlásí, systém MojeID udržuje tohoto uživatele „přihlášeného“. Pokud se uživatel v této době přihlašuje k jinému poskytovateli služeb, nemusí se na přihlašovací stránce MojeID znovu autentizovat. Máte ovšem možnost omezit svoji žádost o ověření identity na libovolnou dobu od poslední autentizace, pokud to považujete za potřebné, např. z hlediska bezpečnosti. Tuto volbu je možné vyžádat použitím pole max_auth_age rozšíření PAPE. Pokud se uživatel nepřihlásil do MojeID za posledních max_auth_age sekund, je po něm vyžadováno nové přihlášení.

  • Prohlášený identifikátor uživatele, který bude ověřován – Jméno identity odpovídající tomuto prohlášenému identifikátoru bude uživateli zobrazeno na přihlašovací stránce MojeID. Pokud uživatel vybírá identifikátor u OP, obsahuje zvláštní hodnotu.

  • Požadované údaje z MojeID identity – do žádosti o ověření identity lze přidat i seznam jednotlivých údajů z MojeID identity, které vaše aplikace vyžaduje a které budou po úspěšném přihlášení a se souhlasem uživatele vaší aplikaci předány. Pro každý údaj je nutné uvést jeho identifikátor. MojeID podporuje vyžádání následujících údajů (podrobnosti a formáty jednotlivých položek lze nalézt přímo na uvedené adrese identifikátoru údaje; některé z těchto údajů – jméno, přezdívka, e-mail, datum narození, PSČ a stát – lze získat jednodušším identifikátorem rozšíření SReg). Seznam možných údajů obsahuje Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0).

Příklad položek v požadavku, které může žádost o ověření identity obsahovat, shrnuje následující tabulka:

Parametr (klíč)

Popis (hodnota)

openid.ns

Určení použitého OpenID protokolu.
http://specs.openid.net/auth/2.0

openid.claimed_id

Prohlášený identifikátor uživatele.
http://demo.mojeid.cz/

openid.identity

Vnitřní identifikátor uživatele.
http://mojeid.cz/id/unikatni_retezec/

openid.assoc_handle

Identifikační řetězec dříve navázané asociace.
{HMAC-SHA256}{4c486ac3}{Ze6JZA==}

openid.return_to

Návratová adresa z MojeID. Ve starších specifikacích protokolu OpenID se toto pole označuje openid.trust_root.
http://www.poskytovatel-example.cz/MojeID-Navrat.html

openid.realm

Oblast URL poskytovatele služeb.
http://www.poskytovatel-example.cz/

openid.ns.ax

Určení rozšíření pro výměnu atributů. Řetězec „ax“ může být jakékoliv jiné pojmenování, které si zvolí vaše knihovna. Zde se pouze řekne, jak se na něj bude dále odkazovat.
http://openid.net/srv/ax/1.0

openid.ax.mode

Režim výměny atributů (získání, uložení).
fetch_request

openid.ax.type.firstName

Vyžádání atributu na místo firstName může být libovolný řetězec.
http://axschema.org/namePerson/first

openid.ax.type.validated

Další atribut – tentokrát informace o ověření uživatelových údajů.
http://specs.nic.cz/attr/contact/valid

openid.ax.type.jabber

http://axschema.org/contact/IM/Jabber

openid.ax.required

Seznam atributů, o kterých poskytovatel služeb tvrdí, že jsou nezbytné pro řádné založení/aktualizaci účtu resp. pro fungování aplikace poskytovatele služeb samotné (povinné položky).
firstName,validated

openid.ax.if_available

Seznam dodatečných atributů (nepovinné položky). Poskytovatel služeb by si je přál, ale nevadí, pokud je nedostane.
Jabber

openid.ns.pape

Určení rozšíření pro autentizační politiky.
http://specs.openid.net/extensions/pape/1.0

openid.pape.max_auth_age

Počet sekund od poslední autentizace. Pokud se uživatel neautentizoval v této době, musí se autentizovat znovu.
3600

openid.pape .preferred_auth_policies

Seznam identifikátorů požadovaných politik oddělených mezerou.
http://schemas.openid.net/pape/policies/2007/06/phishing-resistant

4.2.6. Provedení autentizace (XRDS a realm)

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

V okamžiku, kdy uživatel dorazí s žádostí o ověření identity od vaší aplikace na koncový bod MojeID, je mu zobrazena přihlašovací stránka, kde proběhne samotné přihlášení.

_images/mojeid-login.png

Vlastní dialog pro vložení MojeID identifikátoru na stránkách MojeID.

Tato autentizace je provedena servery MojeID. V rámci tohoto ověření se pokusíme provést maximum úkonů, které byly specifikovány pomocí parametrů v žádosti o ověření identity. Celý proces se odehrává v systémech MojeID a z vaší strany nevyžaduje žádnou činnost.

Součástí je ověření vaší návratové adresy; uživatel je o výsledku tohoto ověření informován. V rámci tohoto ověření jsou získána i další data o vás pomocí protokolu YADIS a ta jsou následně ověřena oproti údajům ve zprávě. Korektní odpověď na dotaz z protokolu YADIS vrátí buď XRDS dokument nebo HTML dokument, v němž bude zveřejněna poloha XRDS dokumentu.

4.2.6.1. XRDS dokument a jeho formát

Poloha XRDS dokumentu se zveřejňuje následující značkou META v hlavičce stránky, kterou umístíte na adresu vašeho realmu OpenID:

<meta http-equiv="x-xrds-location" content="http://www.example.cz/xrds.xml"/>

Příklad vlastního XRDS dokumentu pro přihlášení ke službě MojeID:

<?xml version="1.0" encoding="UTF-8"?>
<xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
  <XRD>
    <Service>
      <Type>http://specs.openid.net/auth/2.0/return_to</Type>
      <URI>http://www.poskytovatel-example.cz/MojeID-Navrat.html</URI>
    </Service>
  </XRD>
</xrds:XRDS>

Příklad XRDS dokumentu pro registraci ke službě MojeID:

<?xml version="1.0" encoding="UTF-8"?>
<xrds:XRDS xmlns:xrds="xri://$xrds" xmlns="xri://$xrd*($v*2.0)">
  <XRD>
    <Service>
      <Type>http://specs.openid.net/auth/2.0/assert_url</Type>
      <URI>URL rozhraní</URI>
    </Service>
  </XRD>
</xrds:XRDS>

kde ve značce URI musí být návratová adresa vaší aplikace z žádosti o ověření identity. Během celého procesu k získání dokumentu nesmí váš server vrátit přesměrování (HTTP kód 3xx), jinak je dokument považován za neplatný/podvržený.

4.2.6.2. Výběr vhodného realmu

Realm je v systému MojeID jednoznačným identifikátorem vámi poskytované služby, jeho správná volba tedy usnadní orientaci uživatelům. Dle specifikace OpenID by měl realm odpovídat části prostoru URL, pro níž je požadavek platný. V případě přihlašování by tedy realm neměl být menší než je část prostoru URL, která je pokrytá následně vzniklým sezením.

Z tohoto plyne naše doporučení používat právě jeden realm na jednu doménu druhého řádu. Protože dvě URL, které se liší byť jen schématem, jsou dle specifikací rozdílné, velmi doporučujeme použít výhradně schéma HTTPS, pokud je dostupné. Tím se také zabrání odposlechu dat uživatelů během jejich odesílání do vaší aplikace.

Pokud používáte pouze jedinou doménu druhého řádu, pak doporučujeme zvolit realm ve tvaru: https://example.cz/ nebo https://www.example.cz/.

Důležité

Návratová adresa musí mít stejnou doménu jako realm, jinak je OpenID požadavek neplatný.

Pokud používáte poddomény třetích a nižších řádů, doporučujeme využít náhražkový znak * a zvolit realm ve tvaru https://*.example.cz/. Tento realm umožňuje používat návratové adresy s libovolnou poddoménou, např. https://www.example.cz/, https://sub.example.cz/navratova/adresa/, https://pod.do.me.na.example.cz/, ale ne s doménou samotnou (v tomto případě https://example.cz/).

Dokument XRDS se bude hledat na URL, kde se znak * nahradí za „www“, tedy na https://www.example.cz/. Všechny tvary, se kterými se pracuje, musí být v protokolu HTTPS.

Důležité

Realm nesmí obsahovat IP adresu, vždy použijte doménové jméno.

4.2.7. Odpověď s výsledkem ověření identity

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

V případě, že o to vaše aplikace požádala, je jí opět nepřímo přes přesměrování uživatelova prohlížeče zaslána zpět zpráva s odpovědí resp. výsledkem ověřování identity a dalšími daty, která si vyžádala. Tato odpověď má opět formu HTTP zprávy, přičemž v těle této zprávy jsou uvedena jednotlivá data vyjadřující jednotlivé informace výstupu z procesu ověření identity.

Následují příklady položek polí odpovědi na žádost o ověření identity:

Parametr (klíč)

Popis (hodnota)

openid.claimed_id

Vrací prohlášený identifikátor uživatele, od výchozího se může lišit fragmentem. Tento řetězec použijete k párování dat specifických pro uživatele. Je důležité při porovnávání dbát zřetel na všechny části řetězce včetně schématu a fragmentu.
https://demo.mojeid.cz/#unikatni_retezec

openid.op_endpoint

MojeID endpoint URL.
https://mojeid.cz/endpoint/

openid.response_nonce

Unikátní značka odpovědi. Žádné dvě odpovědi nemají stejnou – slouží k obraně před znovu odesláním odpovědi (tzv. replay attack).
2010-07-22T16:13:08ZiEnTtR

openid.signed

Seznam polí, která jsou podepsána podpisem, viz následující klíč.
assoc_handle, claimed_id, ns, op_endpoint, pape.auth_policies, response_nonce, signed

openid.sig

Podpis vyjmenovaných polí pro ověření pravosti.
hdtOpg3jCup1n6+elCXn+yLZAYc=

openid.ax.type.firstName

Mapování oficiálního URL identifikátoru na řetězec používaný ve zprávě.
http://axschema.org/namePerson/first

openid.ax.value.firstName

Hodnota atributu identity pro uvedený řetězec.
Ondřej

openid.pape.auth_policies

Mezerou oddělený výčet přihlašovacích politik, které byly ve skutečnosti aplikovány.
http://schemas.openid.net/pape/policies/2007/06/phishing-resistant

openid.pape.auth_time

Čas kdy byla ověřena uživatelova identita na serveru (vždy v UTC).
2005-05-15T17:11:51Z

4.2.8. Ověření odpovědi

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Každá zpráva s odpovědí je digitálně podepsána a musí být ověřena. Ověřují se následující části zprávy:

  • návratová URL – Hodnota openid.return_to musí souhlasit s URL, na kterou byl požadavek doručen. Všechny parametry této URL musí být obsaženy v HTTP zprávě, již vaše aplikace obdržela.

  • prohlášený identifikátor – Metadata náležící k prohlášenému identifikátoru získaná během iniciace nebo opakováním části tohoto procesu musí souhlasit s údaji obsaženými ve zprávě – prohlášený identifikátor, vnitřní identifikátor, koncový bod OP a verze protokolu.

  • značka odpovědi – Zpráva se stejnou značkou nebyla od tohoto poskytovatele OpenID ještě přijata.

  • podpis – Všechna pole, která musí být podepsána, jsou podepsána a podpis je platný. Podpis si buď vaše aplikace ověří sama ve stavové komunikaci, nebo o kontrolu podpisu požádá poskytovatele OpenID.

Pokud jsou všechny tyto podmínky splněny, pak je zpráva platná a bylo ověřeno, že prohlášený identifikátor náleží uživateli. Všechny části by ale měla zpracovat knihovna implementující protokol.

4.2.9. Zpracování odpovědi

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Pokud je zpráva s odpovědí na žádost o ověření identity úspěšně ověřena, může vaše aplikace zpracovat data obsažená v odpovědi a dokončit tak proces přihlašování pomocí MojeID. Toto zpracování musí webová aplikace zajistit na návratové adrese, která byla obsažena v žádosti o ověření identity.

4.2.9.1. Výsledek přihlášení

Při zpracování výsledku přihlášení je potřeba ošetřit následující speciální situace týkající se úspěšného přihlášení:

  • První přihlášení uživatele – pokud je uživatel, který se úspěšně přihlásil, ve vaší webové aplikaci poprvé, je ve většině případů nutné, abyste mu založili účet, kde budou udržována data získaná z MojeID identity a samozřejmě i veškerá další data specifická pro příslušnou aplikaci. Při zakládání účtu je doporučeno:

    • využít data získaná z MojeID identity zcela místo vyplňování registračního formuláře, případně zobrazit uživateli v registračním formuláři pouze ta políčka, jejichž obsah nebyl získán z MojeID

    • a seznámit uživatele s tím, jaká data z MojeID identity příslušná aplikace potřebuje a doporučit mu, že je vhodné, aby umožnil jejich předávání při každém přihlášení.

  • Opakované přihlášení versus přihlášení nového uživatele – při každém zpracování odpovědi je třeba kontrolovat prohlášenou identitu uživatele, protože se může stát, že dva různí uživatelé mají stejné jméno identity a to tak, že jedna osoba zruší svoji MojeID identitu (a uvolní tak příslušné jméno identity) a jiná osoba si založí identitu se stejným jménem identity. Tito uživatelé jsou pak rozlišeni pomocí unikátního řetězce na konci URL prohlášené identity.

  • Přihlášení uživatele, který o něj nepožádal přímo – vaše aplikace může obdržet odpověď s úspěšným přihlášením i v případě, že o přihlášení tento uživatel nepožádal přímo v této aplikaci. Jde o normální situaci, která by neměla být považována za chybu – požadavek na přihlášení šel z jiných stránek, než na kterou se vrací data (v protokolu se neuchovává informace o aplikaci, jež vygenerovala zprávu; pokud takovou informaci vyžadujete, musíte si ji doplnit sami). Uživatel je si ovšem vždy díky upozornění na přihlašovací stránce MojeID vědom, ke které službě se přihlašuje a komu předává data.

Při zpracování výsledku přihlášení je potřeba ošetřit následující situace týkající se negativního výsledku přihlašování:

  • Zamítnutí žádosti o přihlášení – Uživatel může po příchodu na přihlašovací stránku zamítnout žádost o přihlášení např. z důvodu, že jej sám neinicioval. Vaše aplikace pak musí ošetřit tento stav.

  • Nemožnost okamžitého ověření – Vaše aplikace může vynutit ověření identity bez kontaktu s uživatelem, pokud toto ověření není poskytovatel OpenID schopen poskytnout, vrátí se tento typ odpovědi znamenající, že je třeba provést klasické ověření uživatele. Některé knihovny tento stav nerozlišují od předchozího stavu.

  • Chyba v protokolu – Poskytovatel OpenID vrátí tento typ zprávy, pokud je schopen určit návratovou adresu vaší aplikace, ale není schopen rozpoznat jiná pole ve zprávě, neboť obsahuje data, jež jsou v rozporu s protokolem. Poskytovatel OpenID vrací tento typ zpráv, např. pokud mu je doručena zpráva s vnitřním identifikátorem, jež není schopen ověřit.

4.2.9.2. Údaje z MojeID identity

Pokud je využito dotazování na údaje z MojeID identity, je nutné ošetřit následující speciální situace:

  • Opakované přihlašování uživatele – při každém opakovaném přihlášení uživatele pomocí MojeID je potřeba zkontrolovat, zda data, která jsou uložena v interním účtu vaší aplikace, jsou shodná s daty, která byla v rámci přihlášení získána z MojeID identity uživatele. V případě, že se liší, je potřeba aktualizovat data v interním účtu daty z MojeID identity; ta jsou pravděpodobně aktuální.

  • Neobdržení požadovaných údajů – uživatel má vždy možnost ovlivnit, jaké údaje budou či nebudou při přihlášení předávány vaší aplikaci. Může se tedy stát, že aplikace některé údaje vyžaduje a přesto je díky uživatelově volbě nedostane. Je doporučeno ošetřit tuto situaci, aby data, která aplikace požaduje, byla rozdělena na povinná, která jsou nutná pro fungování aplikace, a nepovinná, bez kterých se aplikace obejde. Podle tohoto rozdělení je pak vhodné navrhovat konkrétní chování dotyčné aplikace.

Zvláštním případem je možnost přihlášení pouze pro plně identifikované nebo validované (fyzicky ověřené) uživatele MojeID. Položky http://specs.nic.cz/attr/contact/validhttp://specs.nic.cz/attr/contact/status jsou předávány vždy, pokud si o ně aplikace poskytovatele s plným přístupem požádá. Údaje, u kterých uživatel nepovolil předání, jsou v těle odpovědi vráceny bez hodnoty.

4.3. Implementace pomocí SAML

SAML je protokol, který historicky předchází moderním protokolům OpenID. Pokud váš systém již podporuje SAML (například se jedná o instalaci systému Shibboleth nebo podobných) je možné využít pro napojení na MojeID i tohoto protokolu.

Implementace protokolu SAML 2.0 vychází ze specifikací na https://wiki.oasis-open.org/security/FrontPage

Pro napojení na MojeID je nutné zaslat metadata služby na adresu techsupport@mojeid.cz a případně zaregistrovat metadata MojeID, která jsou uvedena na https://mojeid.cz/saml/idp.xml. Certifikát uvedený v metadatech se může změnit a proto je potřeba čas od času tato metadata aktualizovat. Pro ověření podpisu metadat je možné použít certifikát na https://mojeid.cz/saml/cert.

Jelikož jsou SAML zprávy base64-encodeddeflated, můžete si je za účelem odlaďování převést do čitelného XML např. pomocí nástroje https://www.samltool.com/decode.php.

Seznam údajů, které mohou být protokolem předány, (vč. jejich identifikátorů) obsahuje Příloha č. 3 – Seznam údajů pro předání (SAML)Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz).

Příklady a řešení chybových hlášek obsahuje Příloha č. 6 – Příklady a řešení chybových hlášek.

4.3.1. Žádost o ověření identity účtem napojeným na NIA

Žádost o ověření identity účtem MojeID napojeným na NIA se vyžádá pomocí třídy AuthnContextClassRef (Authentication Context Class Reference). Hodnoty pro vyžádání konkrétní úrovně záruky shrnuje tabulka níže.

AuthnContextClassRef

Popis

eidas.europa.eu/LoA/substantial

eIDAS úroveň záruky „značná“

eidas.europa.eu/LoA/high

eIDAS úroveň záruky „vysoká“

Příklad použití:

<saml:AuthnContextClassRef>
    urn:oasis:names:tc:SAML:2.0:ac:classes:eidas.europa.eu/LoA/substantial
</saml:AuthnContextClassRef>

4.4. Problémy při implementaci

Tato sekce upozorňuje na některé problémy při implementování a naznačuje jejich řešení nebo obejití.

4.4.1. Rozdíly mezi protokoly

Závažným rozdílem mezi protokoly je, že každý protokol je schopný předat jen některé údaje z identity MojeID a tato množina údajů je u každého protokolu jiná.

Pracujeme na jejich sjednocení, ale v současnosti není možné předat všechny údaje identity přes každý z podporovaných protokolů.

Předávané údaje jsou vypsány pro jednotlivé protokoly v přílohách:

4.4.2. Přechod na jiný protokol

Obecně probíhá přechod na jiný protokol tak, že se uživatel přes nějakou ze stávajících přihlašovacích metod přihlásí do služby a poté se přihlásí znovu pomocí nového protokolu. Tím může poskytovatel služby přiřadit existujícímu uživateli identifikátor nového protokolu.

Přechod z protokolu OpenID 2.0 na nový protokol OpenID Connect

Chcete-li přejít z původního protokolu OpenID 2.0 na aktuální protokol OpenID Connect, odešlete žádost o ověření identity protokolem OpenID Connect s parametrem scope rozšířeným o hodnotu openid2 a zpět obdržíte identitu OpenID 2.0 spolu s identitou OpenID Connect.

Více informací o procesu migrace najdete v těchto specifikacích.

4.4.3. Ladění komunikace se serverem MojeID

Pro ladění problémů v komunikaci doporučujeme použít vývojářské nástroje ve webovém prohlížeči. Ty umožňují prohlížet síťové aktivity, tedy dotazy a odpovědi zasílané mezi klientem (vaše implementace) a serverem MojeID. To vám může pomoct odhalit případnou chybu v předávaných datech.

Poznámka

U složitějších problémů, kdy se musíte obrátit na naši technickou podporu, je užitečné pro analýzu problému přidat k popisu i zachycený výpis komunikace.

Ve Firefoxu je možné použít vestavěné nástroje nebo doplněk (např. FireBug):

  1. Nástroje pro vývojáře zapnete přes hlavní menu ‣ Vývojář nebo klávesovou zkratkou Ctrl+Shift+I.

  2. Poté přepněte na záložku Síť (nebo vyvolejte přímo záložku klávesovou zkratkou Ctrl+Shift+Q).

Chrome je též možné použít vestavěné nástroje:

  1. Nástroje pro vývojáře zapnete přes hlavní menu ‣ Další nástroje ‣ Nástroje pro vývojáře nebo klávesovou zkratkou Ctrl+Shift+I.

  2. Poté přepněte na záložku Network.

4.4.3.1. Odlaďování v popup okně

Pokud ověření uživatele přes MojeID implementujete pomocí nového popup okna, je pro odchyt komunikace potřeba:

  1. Poprvé nechat vygenerovat popup okno.

  2. Před odesláním požadavku na server MojeID v něm kliknout pravým tlačítkem myši a otevřít ladicí nástroj výběrem položky v nabídce:

    • Chromium: Prozkoumat

    • Firefox: Prozkoumat prvek

    • FireBug plugin: Prozkoumat prvek ve firebug

  3. Vyvolat obnovení popup okna (např. F5 nebo Ctrl+R).

  4. Standardně pokračovat v odchytu síťové komunikace v ladicím nástroji.

5. Rozhraní pro zakládání účtů MojeID

Tato kapitola popisuje mechanismus registrace účtů MojeID prostřednictvím vaší aplikace.

5.1. Žádost o založení účtu MojeID

Uživatel si ve vaší aplikaci zvolí možnost založit účet MojeID. Toto vygeneruje v prohlížeči uživatele HTTPS POST požadavek na registrační server na adrese https://direct.mojeid.cz/registration/direct/. V parametrech požadavku jsou spolu s požadovaným uživatelským jménem všechny evidované údaje o daném uživateli (Seznam údajů pro registraci obsahuje Příloha č. 5 – Seznam údajů pro registraci) a navíc:

  • identifikátor poskytovatele služeb (realm) – volitelné URI, jehož hodnota závisí na komunikačním protokolu:

    • v případě OpenID 2.0 by se mělo jednat o stejnou hodnotu, která se používá pro přihlašování ke službě MojeID,

    • v případě OpenID Connect se musí jednat o přidělené client_id,

  • jednoznačný identifikátor transakce (registration_nonce) – slouží ke spárování odpovědi na tento požadavek.

Také máte možnost volbou adresy https://mojeid.cz/transfer/endpoint/ nabídnout uživateli převod existujícího kontaktu v centrálním registru. V takovém případě se ignorují zaslané údaje o uživateli a je vyplněno uživatelské jméno, neboli identifikátor kontaktu, který nelze měnit. Pokud je identifikátor nevalidní, nelze ho převést do MojeID, uživatel musí kontaktovat určeného registrátora pro změnu.

Dále je uživateli zobrazen formulář se seznamem údajů, které se po registraci vloží do MojeID. U základních údajů se zobrazí i hodnota a je možné je změnit. Uživatel na registračním formuláři následně:

  • odsouhlasí pravidla používání služby,

  • bude ověřen pomocí CAPTCHA.

5.2. Kontrola validity dat

Registrační server po odeslání formuláře zkontroluje validitu dat a nechá uživatele opravit chyby. V případě, že jsou data validní, je zahájen proces registrace nového účtu. Do tohoto účtu registrační server uloží požadovaná data a připojí vaši identifikaci (identifikátor poskytovatele služeb, realm). Následně je zahájena identifikace uživatele odesláním PIN1 a PIN2.

Následujícím krokem je informovat vaši aplikaci o úspěšné registraci.

V případě komunikace přes OpenID 2.0 se s pomocí URI, jež označuje váš realm, server pokusí nalézt XRDS dokument s alespoň jedním elementem <xrd:Service> obsahujícím elementy:

  • <xrd:Type> s hodnotou http://specs.nic.cz/registration/assert_url a

  • <xrd:URI> s URL rozhraní, na které se zašle informace o registraci.

Během tohoto procesu nesmí dojít k přesměrování a URL rozhraní musí ležet v URI poskytovatele služeb (realmu), viz https://openid.net/specs/openid-authentication-2_0.html#realms.

V případě komunikace přes OpenID Connect musí být URL pro zasílání informací zadány v průběhu registrace klienta pomocí assertion_uris klíče, do kterého se vkládá seznam adres (zakódovaný do JSON), na které se mají zprávy odesílat.

Vaší aplikaci je přímo poslána HTTPS POST zpráva na rozhraní dané adresou URL. Obsahem zprávy jsou tři parametry:

  • registration_nonce – jednoznačný identifikátor transakce pro spárování s původním požadavkem,

  • identifikátor uživatele MojeID v závislosti na použitém protokolu:

    • claimed_id – v případě protokolu OpenID 2.0,

    • sub – v případě protokolu OpenID Connect,

  • status – stav s hodnotou REGISTERED.

Vaše aplikace musí tuto zprávu nejprve ověřit:

  • musí zkontrolovat, že zpráva byla doručena na některou z adres uvedených v bodě Žádost o založení účtu MojeID,

  • musí ověřit, že transakce registration_nonce byla opravdu vytvořena,

  • musí ověřit, že klientský certifikát, který byl použit pro vytvoření SSL tunelu, je platný a podepsaný certifikační autoritou CZ.NIC. Tento certifikát je dostupný na adrese https://www.mojeid.cz/cs/pro-poskytovatele/jak-zavest/#download pro produkční i testovací prostředí. Certifikát je potřeba pro notifikace na produkci i na testu.

Pokud nepoužíváte HTTPS a chcete na testovacím prostředí zkoušet přihlašování a zakládání účtů, tento certifikát není třeba.

Pokud HTTPS používáte a jde o testovací prostředí, je tento certifikát potřeba pro zasílání notifikací z registrace. Pro přihlášení není třeba (mezi MojeID a vaším serverem se přenáší jen obecná veřejná data, takže není třeba ověřovat „totožnost“ toho, kdo je žádá).

Notifikace se posílají po registraci, částečné identifikaci (PIN1 a PIN2) a identifikaci (PIN3) na assert_url, které je uvedeno v XRDS dokumentu na realmu. Toto je funkční i na testu. Aby vaše aplikace dostávala notifikace, musíte mít realm s HTTPS. Dále pak po přijetí notifikace je třeba odpovědět řetězcem 'mode:accept\n', kde \n je znak nové řádky.

Tip

Ověřování klientského certifikátu umí zajistit HTTP server např. Apache s použitím konfigurační volby SSLVerifyClient.

Pokud jsou všechny podmínky splněny, může vaše aplikace při zpracování této zprávy spárovat MojeID identifikátor se svým záznamem o uživateli pro účely autentizace přes MojeID.

Poznámka

Pokud není možné zaslat tuto zprávu bezpečným způsobem protokolem HTTPS, pokračuje registrace bez zaslání této zprávy.

5.3. Dokončení registrace

Vaše aplikace odešle odpověď na zprávu z bodu Kontrola validity dat v těle HTTP odpovědi ve formátu klíč-hodnota OpenID protokolu:

  • výsledek (mode) – hodnota accept nebo reject značící, zda uživatelův účet byl úspěšně spárován,

  • důvod zamítnutí (reason) – nepovinný parametr obsahující důvod, proč k párování nedošlo.

Pokud nebude obdržena odpověď ve správném formátu, bude zpráva s výsledkem registrace poslána na další adresu z bodu Kontrola validity dat, dokud nebude získána odpověď nebo nebudou adresy vyčerpány.

Registrace pak pokračuje buď přímou výzvou k vyplnění PIN1 a PIN2 a vstoupením do profilu, kde si uživatel zvolí heslo, nebo je uživateli zobrazena informace o dokončení registrace.

Pokud máte aktivován plný přístup, budou vaší aplikaci zasílány informace i o změně stavu uživatelova účtu. Tyto zprávy jsou posílány podobně jako v bodě Kontrola validity dat, se dvěma parametry v každé zprávě:

  • identifikátor uživatele MojeID v závislosti na použitém protokolu:

    • claimed_id – v případě OpenID 2.0,

    • sub – v případě OpenID Connect,

  • status – stav účtu, jedna z hodnot:

    • CONDITIONALLY_IDENTIFIED – částečně identifikovaný (zadán PIN1 a PIN2),

    • IDENTIFIED – identifikovaný (zadán PIN1, PIN2 a PIN3 1),

    • VALIDATED – validovaný (zadán PIN1, PIN2, PIN3 2 a příznak validace).

Pokud selže odesílání této zprávy nebo na ni nebude správně odpovězeno, bude informace o změně stavu zaslána opakovaně každých 5 minut po dobu 6 hodin, dokud je vaše aplikace nepřijme nebo neodmítne. Oproti tomu zpráva o dokončení registrace je synchronní – posílá se jen jednou.

1

PIN3 pro identifikaci účtu MojeID není povinný. Identifikaci lze získat napojením účtu na NIA či validací. Může tedy nastat situace, kdy uživatel má identifikovaný účet, ale má zadaný jen PIN1 a PIN2.

2

PIN3 pro validaci účtu MojeID není povinný. Může tedy nastat situace, kdy uživatel má validovaný účet, ale má zadaný jen PIN1 a PIN2.

Od července 2022 nelze ověřit účty fyzických osob pomocí PIN3. Ověření pomocí PIN3 je možné pouze u účtů s vyplněným polem Organizace.

6. Odhlašování od služby MojeID

Z principu fungování MojeID vaše služba uživatele odhlásit z MojeID automaticky nemůže, protože by ho tak odhlásila i od dalších služeb, ke kterým je uživatel přihlášen přes MojeID. Ve výjimečných případech ale může uživatel potřebovat i odhlášení z MojeID, například pokud se přihlásil z cizího zařízení.

Pak je vhodné, aby při nebo po odhlášení z vaší služby, byla uživateli nabídnuta možnost odhlášení i ze služby MojeID.

Pokud uživatel tuto možnost zvolí, uživatele přesměrujte nebo odkažte na adresu https://mojeid.cz/logout/, kde uživatel odhlášení potvrdí.

Doporučujeme tuto možnost zavést, pokud se k vaší službě přistupuje z veřejných počítačů (např. v knihovně nebo internetové kavárně) a zároveň to není bezpečně řešeno např. smazáním dat po ukončení práce s prohlížečem.

Jinak ale její zavedení není povinné.

7. Testovací instance MojeID

Pro účely testování implementace můžete využít naši testovací instanci služby MojeID, na níž můžete testovat přihlášení uživatelů MojeID, registrace nových účtů a převody účtů z centrálního registru.

Před zahájením testování zašlete na adresu techsupport@mojeid.cz metadata, pod kterými budete testovat. Tato metadata jsou pro každý protokol jiná, viz informace k jednotlivým protokolům níže.

Důležité

Použijte jiná metadata než pro ostrý provoz!

My vám na testovacím serveru povolíme přístupy a nastavíme pro účely testování tzv. plný přístup, aby vám mohly být předávány všechny údaje účtu MojeID, včetně údajů status, valid a dalších, které jsou předávány pouze poskytovatelům s plným přístupem.

7.1. Testovací účty

Pro testování MojeID doporučujeme založit 3 testovací uživatele v různých stupních ověření:

  • částečně identifikovaného, u kterého bude zadaný jen PIN1 a PIN2,

  • identifikovaného, u kterého bude zadaný PIN1, PIN2 a PIN3 (PIN3 není pro identifikaci účtu povinný, viz Dokončení registrace),

  • validovaného, u kterého bude zadaný PIN1, PIN2, PIN3 a příznak validace.

Tím je možné otestovat vracené hodnoty v parametru status pro obě varianty identifikace a validaci.

Na adrese https://mojeid.regtest.nic.cz/registration/ si založte jednotlivé testovací účty. Kontaktní údaje můžete vyplnit libovolné. PIN1, PIN2 a ověřovací dopis s PIN3 se neposílají, místo nich zadejte univerzální PINy:

  • PIN1: 11111111 (8 jedniček),

  • PIN2: 22222222 (8 dvojek),

  • PIN3: 33333333 (8 trojek).

Pro validaci účtu je potřeba vygenerovat dokument Žádost o validaci (PDF) z příslušného uživatelského profilu. Pro vygenerování dokumentu je nutné mít zadané libovolné datum narození. Vygenerovaný dokument PDF pošlete na adresu techsupport@mojeid.cz, nastavíme pak na odpovídajícím profilu příznak validace.

7.2. Společné endpointy

Část adres rozhraní je nezávislá na vybraném protokolu. Tyto adresy jsou vyjmenovány zde. Dále však budete potřebovat ještě adresy endpointů specifických pro jednotlivé protokoly, které jsou uvedeny níže.

Testovací instance s podrobnějšími výstupy v případě chyb je dostupná na následujících adresách:

  • Registrace nového účtu MojeID: https://mojeid.regtest.nic.cz/registration/endpoint/

  • Převod kontaktu do MojeID z registru domén: https://mojeid.regtest.nic.cz/transfer/endpoint/

Pro zavedení implementace MojeID na ostrý provoz budou k dispozici následující adresy:

  • Registrace nového účtu MojeID: https://mojeid.cz/registration/endpoint/

  • Převod kontaktu do MojeID z registru domén: https://mojeid.cz/transfer/endpoint/

7.3. OpenID Connect

Potřebná metadata k zaslání na podporu

  • Client_ID, pod kterým budete testovat – kombinace 12 znaků malých a velkých písmen abecedy a číslic, která je vygenerována automaticky při registraci služby

Endpointy specifické pro protokol

  • Adresy testovacích endpointů:
    • Registration Endpoint: https://mojeid.regtest.nic.cz/oidc/registration/

    • Authorization Endpoint: https://mojeid.regtest.nic.cz/oidc/authorization/

    • Token Endpoint: https://mojeid.regtest.nic.cz/oidc/token/

    • UserInfo Endpoint: https://mojeid.regtest.nic.cz/oidc/userinfo/

    Kompletní popis konfigurace OIDC ve formátu JSON: https://mojeid.regtest.nic.cz/.well-known/openid-configuration/

  • Adresy ostrých endpointů:
    • Registration Endpoint: https://mojeid.cz/oidc/registration/

    • Authorization Endpoint: https://mojeid.cz/oidc/authorization/

    • Token Endpoint: https://mojeid.cz/oidc/token/

    • UserInfo Endpoint: https://mojeid.cz/oidc/userinfo/

    Kompletní popis konfigurace OIDC ve formátu JSON: https://mojeid.cz/.well-known/openid-configuration/

7.4. OpenID 2.0

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Potřebná metadata k zaslání na podporu

Endpointy specifické pro protokol

  • testovací koncový bod: https://mojeid.regtest.nic.cz/endpoint/

  • ostrý koncový bod: https://mojeid.cz/endpoint/

7.5. SAML

Metadata testovací instance jsou na adrese: https://mojeid.regtest.nic.cz/saml/idp.xml

Potřebná metadata k zaslání na podporu

  • řetězec entityID, pod kterým budete testovat – maximální délka 1024 znaků, specifikace doporučuje, aby řetězec měl podobu adresy URL a obsahoval doménové jméno poskytovatele nebo poskytované služby

    Příklad: https://sluzba.example.cz

  • soubor XML s metadaty služby (EntityDescriptor), který obsahuje totéž entityID

    Získat soubor s metadaty vám může pomoci tento článek o přípravě metadat.

Endpointy specifické pro protokol

  • testovací koncový bod: https://mojeid.regtest.nic.cz/saml/

  • ostrý koncový bod: https://mojeid.cz/saml/

8. Přílohy

8.1. Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)

Údaj

Indentifikátor claimu

Datový typ

OpenID2 identifikátor pro migraci ze staršího protokolu

openid2_id

SINGLE_OPTIONAL_STRING

Jméno

Celé jméno

name

SINGLE_OPTIONAL_STRING

Křestní jméno

given_name

SINGLE_OPTIONAL_STRING

Příjmení

family_name

SINGLE_OPTIONAL_STRING

Přezdívka

nickname

SINGLE_OPTIONAL_STRING

E-mail

Hlavní

email

SINGLE_OPTIONAL_STRING

Příznak – E-mail ověřen

email_verified

SINGLE_OPTIONAL_BOOLEAN

Notifikační

mojeid_email_notify

SINGLE_OPTIONAL_STRING

Další

mojeid_email_next

SINGLE_OPTIONAL_STRING

Adresa trvalého bydliště / sídla firmy

Kompletní adresa

mojeid_address_def

OPTIONAL_ADDRESS_STRING

Ulice

mojeid_address_def_street

SINGLE_OPTIONAL_STRING

Ulice 2

mojeid_address_def_street2

SINGLE_OPTIONAL_STRING

Ulice 3

mojeid_address_def_street3

SINGLE_OPTIONAL_STRING

Město

mojeid_address_def_city

SINGLE_OPTIONAL_STRING

Stát

mojeid_address_def_state

SINGLE_OPTIONAL_STRING

PSČ

mojeid_address_def_postal_code

SINGLE_OPTIONAL_STRING

Země

mojeid_address_def_country

SINGLE_OPTIONAL_STRING

Korespondenční adresa

Kompletní adresa

address

OPTIONAL_ADDRESS

Ulice

mojeid_address_mail_street

SINGLE_OPTIONAL_STRING

Ulice 2

mojeid_address_mail_street2

SINGLE_OPTIONAL_STRING

Ulice 3

mojeid_address_mail_street3

SINGLE_OPTIONAL_STRING

Město

mojeid_address_mail_city

SINGLE_OPTIONAL_STRING

Stát

mojeid_address_mail_state

SINGLE_OPTIONAL_STRING

PSČ

mojeid_address_mail_postal_code

SINGLE_OPTIONAL_STRING

Země

mojeid_address_mail_country

SINGLE_OPTIONAL_STRING

Příznak – Adresa ověřena
Pouze pro Plný přístup
("true"/"false")
Od července 2022 příznak nelze získat u nových
osobních účtů, protože je nelze ověřit pomocí PIN3.

mojeid_address_mail_verified

SINGLE_OPTIONAL_BOOLEAN

Fakturační adresa

Kompletní adresa

mojeid_address_bill

OPTIONAL_ADDRESS_STRING

Ulice

mojeid_address_bill_street

SINGLE_OPTIONAL_STRING

Ulice 2

mojeid_address_bill_street2

SINGLE_OPTIONAL_STRING

Ulice 3

mojeid_address_bill_street3

SINGLE_OPTIONAL_STRING

Město

mojeid_address_bill_city

SINGLE_OPTIONAL_STRING

Stát

mojeid_address_bill_state

SINGLE_OPTIONAL_STRING

PSČ

mojeid_address_bill_postal_code

SINGLE_OPTIONAL_STRING

Země

mojeid_address_bill_country

SINGLE_OPTIONAL_STRING

Doručovací adresa

Kompletní adresa

mojeid_address_ship

OPTIONAL_ADDRESS_STRING

Jméno společnosti

mojeid_address_ship_company_name

SINGLE_OPTIONAL_STRING

Ulice

mojeid_address_ship_street

SINGLE_OPTIONAL_STRING

Ulice 2

mojeid_address_ship_street2

SINGLE_OPTIONAL_STRING

Ulice 3

mojeid_address_ship_street3

SINGLE_OPTIONAL_STRING

Město

mojeid_address_ship_city

SINGLE_OPTIONAL_STRING

Stát

mojeid_address_ship_state

SINGLE_OPTIONAL_STRING

PSČ

mojeid_address_ship_postal_code

SINGLE_OPTIONAL_STRING

Země

mojeid_address_ship_country

SINGLE_OPTIONAL_STRING

Telefon

Mobil

phone_number

SINGLE_OPTIONAL_STRING

Příznak – Mobil ověřen
("true"/"false")

phone_number_verified

SINGLE_OPTIONAL_BOOLEAN

Další

mojeid_phone_mobile

SINGLE_OPTIONAL_STRING

Domácí

mojeid_phone_home

SINGLE_OPTIONAL_STRING

Pracovní

mojeid_phone_office

SINGLE_OPTIONAL_STRING

Fax

mojeid_phone_fax

SINGLE_OPTIONAL_STRING

Další údaje

Datum narození

birthdate

SINGLE_OPTIONAL_STRING

Pohlaví

gender

SINGLE_OPTIONAL_STRING

Věk

mojeid_age

SINGLE_OPTIONAL_INT

Číslo OP

mojeid_ident_card

SINGLE_OPTIONAL_STRING

Číslo pasu

mojeid_ident_pass

SINGLE_OPTIONAL_STRING

Identifikátor MPSV

mojeid_ident_ssn

SINGLE_OPTIONAL_STRING

Číslo ISIC
Pouze pro Plný přístup

mojeid_isic

SINGLE_OPTIONAL_STRING

Příznak – Starší 18 let
("true"/"false")

mojeid_is_adult

SINGLE_OPTIONAL_BOOLEAN

Příznak – Student
Pouze pro Plný přístup
("true"/"false")

mojeid_student

SINGLE_OPTIONAL_BOOLEAN

Příznak – Validace
Pouze pro Plný přístup
("true"/"false")

mojeid_valid

SINGLE_OPTIONAL_BOOLEAN

IČO

mojeid_vat

SINGLE_OPTIONAL_STRING

DIČ

mojeid_ident_vat

SINGLE_OPTIONAL_STRING

Veřejný PGP klíč

mojeid_public_pgp

SINGLE_OPTIONAL_STRING

Bankovní účet

mojeid_bank_account

SINGLE_OPTIONAL_STRING

Bankovní účet (IBAN)

mojeid_bank_account_iban

SINGLE_OPTIONAL_STRING

Datová schránka

mojeid_isds

SINGLE_OPTIONAL_STRING

Příznak - NIA
Pouze pro Plný přístup
("true"/"false")

mojeid_nia

SINGLE_OPTIONAL_BOOLEAN

URL

Hlavní

profile

SINGLE_OPTIONAL_STRING

Osobní

website

SINGLE_OPTIONAL_STRING

Blog

mojeid_url_blog

SINGLE_OPTIONAL_STRING

Pracovní

mojeid_url_office

SINGLE_OPTIONAL_STRING

RSS

mojeid_url_rss

SINGLE_OPTIONAL_STRING

Facebook

mojeid_url_facebook

SINGLE_OPTIONAL_STRING

Twitter

mojeid_url_twitter

SINGLE_OPTIONAL_STRING

LinkedIN

mojeid_url_linkedin

SINGLE_OPTIONAL_STRING

instagram

mojeid_url_instagram

SINGLE_OPTIONAL_STRING

pinterest

mojeid_url_pinterest

SINGLE_OPTIONAL_STRING

tumblr

mojeid_url_tumblr

SINGLE_OPTIONAL_STRING

wordpress

mojeid_url_wordpress

SINGLE_OPTIONAL_STRING

foursquare

mojeid_url_foursquare

SINGLE_OPTIONAL_STRING

youtube

mojeid_url_youtube

SINGLE_OPTIONAL_STRING

blogger

mojeid_url_blogger

SINGLE_OPTIONAL_STRING

gravatar

mojeid_url_gravatar

SINGLE_OPTIONAL_STRING

about_me

mojeid_url_about_me

SINGLE_OPTIONAL_STRING

Flickr

mojeid_url_flickr

SINGLE_OPTIONAL_STRING

Vimeo

mojeid_url_vimeo

SINGLE_OPTIONAL_STRING

IM

ICQ

mojeid_im_icq

SINGLE_OPTIONAL_STRING

Skype

mojeid_im_skype

SINGLE_OPTIONAL_STRING

Jabber

mojeid_im_jabber

SINGLE_OPTIONAL_STRING

Hangouts

mojeid_im_google_talk

SINGLE_OPTIONAL_STRING

Windows Live

mojeid_im_windows_live

SINGLE_OPTIONAL_STRING

SINGLE_OPTIONAL_BOOLEAN

Boolean nebo null

SINGLE_OPTIONAL_INT

Celé číslo nebo null

SINGLE_OPTIONAL_STRING

Řetězec nebo null

OPTIONAL_ADDRESS

Objekt nebo null

Schéma objektu OPTIONAL_ADDRESS
{
   "formatted": SINGLE_OPTIONAL_STRING,
   "street_address": SINGLE_OPTIONAL_STRING,
   "locality": SINGLE_OPTIONAL_STRING,
   "region": SINGLE_OPTIONAL_STRING,
   "postal_code": SINGLE_OPTIONAL_STRING,
   "country": SINGLE_OPTIONAL_STRING,
}
OPTIONAL_ADDRESS_STRING

Řetězec nebo null; řetězec obsahuje serializovaný objekt OPTIONAL_ADDRESS, např. "{\"formatted\": \"Pražská 5, Praha\"}".

8.2. Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)

Varování

Protokol OpenID 2.0 je zastaralý a jeho podpora bude brzy ukončena. Návod k přechodu na jiný protokol naleznete v kapitole Přechod na jiný protokol.

Poznámka

Hodnoty všech údajů jsou předávané jako řetězce.

Příznaků (uvedeno v tabulce) lze konkrétně očekávat hodnoty "true" anebo "false" s proměnlivou velikostí písmen.

Pokud údaj není vyplněn, není předána žádná hodnota, pouze je vrácen její klíč.

Údaj

Identifikátor AX

Identifikátor SReg

Jméno

Celé jméno

http://axschema.org/namePerson

fullname

http://specs.nic.cz/attr/contact/name

Křestní jméno

http://axschema.org/namePerson/first

http://specs.nic.cz/attr/contact/name/first

Příjmení

http://axschema.org/namePerson/last

http://specs.nic.cz/attr/contact/name/last

Přezdívka

http://axschema.org/namePerson/friendly

nickname

http://specs.nic.cz/attr/contact/nickname

E-mail

Hlavní

http://axschema.org/contact/email

e-mail

http://specs.nic.cz/attr/email/main

Notifikační

http://specs.nic.cz/attr/email/notify

Další

http://specs.nic.cz/attr/email/next

Adresa trvalého bydliště / sídla firmy

Ulice

http://axschema.org/contact/postalAddress/home

http://specs.nic.cz/attr/addr/main/street

Ulice2

http://axschema.org/contact/postalAddressAdditional/home

http://specs.nic.cz/attr/addr/main/street2

Ulice3

http://specs.nic.cz/attr/addr/main/street3

Město

http://axschema.org/contact/city/home

http://specs.nic.cz/attr/addr/main/city

Stát

http://axschema.org/contact/state/home

http://specs.nic.cz/attr/addr/main/sp

Země

http://axschema.org/contact/country/home

http://specs.nic.cz/attr/addr/main/cc

PSČ

http://axschema.org/contact/postalCode/home

http://specs.nic.cz/attr/addr/main/pc

Korespondenční adresa

Ulice

http://specs.nic.cz/attr/addr/mail/street

Ulice2

http://specs.nic.cz/attr/addr/mail/street2

Ulice3

http://specs.nic.cz/attr/addr/mail/street3

Město

http://specs.nic.cz/attr/addr/mail/city

Stát

http://specs.nic.cz/attr/addr/mail/sp

Země

http://specs.nic.cz/attr/addr/mail/cc

PSČ

http://specs.nic.cz/attr/addr/mail/pc

Příznak – Adresa ověřena
Pouze pro Plný přístup
("true"/"false")
Od července 2022 příznak nelze získat u nových
osobních účtů, protože je nelze ověřit pomocí PIN3.

http://specs.nic.cz/attr/addr/mail/verified

Fakturační adresa

Ulice

http://axschema.org/x/contact/postalAddress/billing

http://specs.nic.cz/attr/addr/bill/street

Ulice2

http://axschema.org/x/contact/postalAddressAdditional/billing

http://specs.nic.cz/attr/addr/bill/street2

Ulice3

http://specs.nic.cz/attr/addr/bill/street3

Město

http://axschema.org/x/contact/city/billing

http://specs.nic.cz/attr/addr/bill/city

Stát

http://axschema.org/x/contact/state/billing

http://specs.nic.cz/attr/addr/bill/sp

Země

http://axschema.org/x/contact/country/billing

http://specs.nic.cz/attr/addr/bill/cc

PSČ

http://axschema.org/x/contact/postalCode/billing

http://specs.nic.cz/attr/addr/bill/pc

Doručovací adresa

Firma

http://specs.nic.cz/attr/addr/ship/company_name

Ulice

http://axschema.org/x/contact/postalAddress/shipping

http://specs.nic.cz/attr/addr/ship/street

Ulice2

http://axschema.org/x/contact/postalAddressAdditional/shipping

http://specs.nic.cz/attr/addr/ship/street2

Ulice3

http://specs.nic.cz/attr/addr/ship/street3

Město

http://axschema.org/x/contact/city/shipping

http://specs.nic.cz/attr/addr/ship/city

Stát

http://axschema.org/x/contact/state/shipping

http://specs.nic.cz/attr/addr/ship/sp

Země

http://axschema.org/x/contact/country/shipping

http://specs.nic.cz/attr/addr/ship/cc

PSČ

http://axschema.org/x/contact/postalCode/shipping

http://specs.nic.cz/attr/addr/ship/pc

Telefon

Mobil

http://axschema.org/contact/phone/default

http://specs.nic.cz/attr/phone/main

Další

http://axschema.org/contact/phone/cell

http://specs.nic.cz/attr/phone/mobile

Domácí

http://axschema.org/contact/phone/home

http://specs.nic.cz/attr/phone/home

Pracovní

http://axschema.org/contact/phone/business

http://specs.nic.cz/attr/phone/work

Fax

http://axschema.org/contact/phone/fax

http://specs.nic.cz/attr/phone/fax

Další údaje

Datum narození

http://axschema.org/birthDate

dob

http://specs.nic.cz/attr/contact/ident/dob

Věk

http://specs.nic.cz/attr/contact/age

Pohlaví

http://axschema.org/person/gender

gender

http://specs.nic.cz/attr/contact/gender

Číslo OP

http://specs.nic.cz/attr/contact/ident/card

Číslo pasu

http://specs.nic.cz/attr/contact/ident/pass

Identifikátor MPSV

http://specs.nic.cz/attr/contact/ident/ssn

Číslo ISIC
Pouze pro Plný přístup

http://specs.nic.cz/attr/contact/isic

Příznak – Starší 18 let
("true"/"false")

http://specs.nic.cz/attr/contact/adult

Příznak – Student
Pouze pro Plný přístup
("true"/"false")

http://specs.nic.cz/attr/contact/student

Příznak – Validace
Pouze pro Plný přístup
("true"/"false")

http://specs.nic.cz/attr/contact/valid

Stav účtu
Pouze pro Plný přístup

http://specs.nic.cz/attr/contact/status

Obrázek (base64)

http://specs.nic.cz/attr/contact/image

Jméno společnosti

http://axschema.org/company/name

http://specs.nic.cz/attr/contact/org

IČO

http://specs.nic.cz/attr/contact/ident/vat_id

DIČ

http://specs.nic.cz/attr/contact/vat

Veřejný PGP klíč

http://specs.nic.cz/attr/public_pgp

Bankovní účet

http://specs.nic.cz/attr/bank/national

Bankovní účet (IBAN)

http://specs.nic.cz/attr/bank/iban

Datová schránka

http://specs.nic.cz/attr/contact/isds

Příznak - NIA
Pouze pro Plný přístup
("true"/"false")

http://specs.nic.cz/attr/contact/nia

Internetové adresy

Hlavní

http://axschema.org/contact/web/default

http://specs.nic.cz/attr/url/main

Blog

http://axschema.org/contact/web/blog

http://specs.nic.cz/attr/url/blog

Osobní

http://specs.nic.cz/attr/url/personal

Pracovní

http://specs.nic.cz/attr/url/work

RSS

http://specs.nic.cz/attr/url/rss

Facebook

http://specs.nic.cz/attr/url/facebook

Twitter

http://specs.nic.cz/attr/url/twitter

LinkedIN

http://specs.nic.cz/attr/url/linkedin

instagram

http://specs.nic.cz/attr/url/instagram

pinterest

http://specs.nic.cz/attr/url/pinterest

tumblr

http://specs.nic.cz/attr/url/tumblr

wordpress

http://specs.nic.cz/attr/url/wordpress

foursquare

http://specs.nic.cz/attr/url/foursquare

youtube

http://specs.nic.cz/attr/url/youtube

blogger

http://specs.nic.cz/attr/url/blogger

gravatar

http://specs.nic.cz/attr/url/gravatar

about_me

http://specs.nic.cz/attr/url/about_me

Flickr

http://specs.nic.cz/attr/url/flickr

Vimeo

http://specs.nic.cz/attr/url/vimeo

Instant Messaging

ICQ

http://axschema.org/contact/IM/ICQ

http://specs.nic.cz/attr/im/icq

Skype

http://axschema.org/contact/IM/Skype

http://specs.nic.cz/attr/im/skype

Jabber

http://axschema.org/contact/IM/Jabber

http://specs.nic.cz/attr/im/jabber

Hangouts

http://specs.nic.cz/attr/im/google_talk

Windows Live

http://specs.nic.cz/attr/im/windows_live

8.3. Příloha č. 3 – Seznam údajů pro předání (SAML)

Obecné identifikátory

Údaj

Identifikátor (URI formát)

Identifikátor (BASIC formát)

Jméno

Celé jméno

urn:oid:2.5.4.3

urn:mace:dir:attribute-def:cn

Křestní jméno

urn:oid:2.5.4.42

urn:mace:dir:attribute-def:givenName

Příjmení

urn:oid:2.5.4.4

urn:mace:dir:attribute-def:sn

Přezdívka

urn:oid:2.5.4.65

urn:mace:dir:attribute-def:pseudonym

E-mail

Hlavní

urn:oid:0.9.2342.19200300.100.1.3

urn:mace:dir:attribute-def:mail

Adresa trvalého bydliště / sídla firmy

Kompletní adresa

urn:oid:2.5.4.16

urn:mace:dir:attribute-def:postalAddress

Ulice

urn:oid:2.5.4.9

urn:mace:dir:attribute-def:street

Město

urn:oid:2.5.4.7

urn:mace:dir:attribute-def:l

Stát

urn:oid:2.5.4.8

urn:mace:dir:attribute-def:st

Země

urn:oid:2.5.4.6

urn:mace:dir:attribute-def:c

PSČ

urn:oid:2.5.4.17

urn:mace:dir:attribute-def:postalCode

Telefon

Mobil

urn:oid:2.5.4.20

urn:mace:dir:attribute-def:telephoneNumber

Fax

urn:oid:2.5.4.23

urn:mace:dir:attribute-def:facsimileTelephoneNumber

Další údaje

Datum narození

urn:oid:1.3.6.1.4.1.2428.90.1.3

urn:mace:dir:attribute-def:norEduPersonBirthDate

Věk

http://www.stork.gov.eu/1.0/age

Pohlaví

urn:oid:1.3.6.1.4.1.25178.1.2.2

Obrázek (base64)

urn:mace:dir:attribute-def:photo

Jméno společnosti

urn:oid:2.5.4.10

urn:mace:dir:attribute-def:o

URL

Hlavní

urn:oid:1.3.6.1.4.1.27630.2.1.1.17

Pracovní

urn:oid:1.3.6.1.4.1.27630.2.1.1.120

eduID identifikátory

Údaj

Identifikátor (URI formát)

eduID

eduPersonPrincipalName

urn:oid:1.3.6.1.4.1.5923.1.1.1.6

eduPersonScopedAffiliation

urn:oid:1.3.6.1.4.1.5923.1.1.1.9

eduPersonTargetedID

urn:oid:1.3.6.1.4.1.5923.1.1.1.10

eduPersonUniqueId

urn:oid:1.3.6.1.4.1.5923.1.1.1.13

8.4. Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)

specs.nic.cz identifikátory

Údaj

Identifikátor

Jméno

Celé jméno

http://specs.nic.cz/attr/contact/name

Křestní jméno

http://specs.nic.cz/attr/contact/name/first

Příjmení

http://specs.nic.cz/attr/contact/name/last

Přezdívka

http://specs.nic.cz/attr/contact/nickname

E-mail

Hlavní

http://specs.nic.cz/attr/email/main

Notifikační

http://specs.nic.cz/attr/email/notify

Další

http://specs.nic.cz/attr/email/next

Adresa trvalého bydliště / sídla firmy

Ulice

http://specs.nic.cz/attr/addr/main/street

Ulice2

http://specs.nic.cz/attr/addr/main/street2

Ulice3

http://specs.nic.cz/attr/addr/main/street3

Město

http://specs.nic.cz/attr/addr/main/city

Stát

http://specs.nic.cz/attr/addr/main/sp

Země

http://specs.nic.cz/attr/addr/main/cc

PSČ

http://specs.nic.cz/attr/addr/main/pc

Korespondenční adresa

Ulice

http://specs.nic.cz/attr/addr/mail/street

Ulice2

http://specs.nic.cz/attr/addr/mail/street2

Ulice3

http://specs.nic.cz/attr/addr/mail/street3

Město

http://specs.nic.cz/attr/addr/mail/city

Stát

http://specs.nic.cz/attr/addr/mail/sp

Země

http://specs.nic.cz/attr/addr/mail/cc

PSČ

http://specs.nic.cz/attr/addr/mail/pc

Příznak – Adresa ověřena
Pouze pro Plný přístup
("0"/"1"/"true"/"false")
Od července 2022 příznak nelze získat u nových
osobních účtů, protože je nelze ověřit pomocí PIN3.

http://specs.nic.cz/attr/addr/mail/verified

Fakturační adresa

Ulice

http://specs.nic.cz/attr/addr/bill/street

Ulice2

http://specs.nic.cz/attr/addr/bill/street2

Ulice3

http://specs.nic.cz/attr/addr/bill/street3

Město

http://specs.nic.cz/attr/addr/bill/city

Stát

http://specs.nic.cz/attr/addr/bill/sp

Země

http://specs.nic.cz/attr/addr/bill/cc

PSČ

http://specs.nic.cz/attr/addr/bill/pc

Doručovací adresa

Firma

http://specs.nic.cz/attr/addr/ship/company_name

Ulice

http://specs.nic.cz/attr/addr/ship/street

Ulice2

http://specs.nic.cz/attr/addr/ship/street2

Ulice3

http://specs.nic.cz/attr/addr/ship/street3

Město

http://specs.nic.cz/attr/addr/ship/city

Stát

http://specs.nic.cz/attr/addr/ship/sp

Země

http://specs.nic.cz/attr/addr/ship/cc

PSČ

http://specs.nic.cz/attr/addr/ship/pc

Telefon

Mobil

http://specs.nic.cz/attr/phone/main

Další

http://specs.nic.cz/attr/phone/mobile

Domácí

http://specs.nic.cz/attr/phone/home

Pracovní

http://specs.nic.cz/attr/phone/work

Fax

http://specs.nic.cz/attr/phone/fax

Další údaje

Datum narození

http://specs.nic.cz/attr/contact/ident/dob

Věk

http://specs.nic.cz/attr/contact/age

Pohlaví

http://specs.nic.cz/attr/contact/gender

Číslo OP

http://specs.nic.cz/attr/contact/ident/card

Číslo pasu

http://specs.nic.cz/attr/contact/ident/pass

Identifikátor MPSV

http://specs.nic.cz/attr/contact/ident/ssn

Číslo ISIC
Pouze pro Plný přístup

http://specs.nic.cz/attr/contact/isic

Příznak – Starší 18 let
("0"/"1"/"true"/"false")

http://specs.nic.cz/attr/contact/adult

Příznak – Student
Pouze pro Plný přístup
("0"/"1"/"true"/"false")

http://specs.nic.cz/attr/contact/student

Příznak – Validace
Pouze pro Plný přístup
("0"/"1"/"true"/"false")

http://specs.nic.cz/attr/contact/valid

Stav účtu
Pouze pro Plný přístup

http://specs.nic.cz/attr/contact/status

Obrázek (base64)

http://specs.nic.cz/attr/contact/image

Jméno společnosti

http://specs.nic.cz/attr/contact/org

IČO

http://specs.nic.cz/attr/contact/ident/vat_id

DIČ

http://specs.nic.cz/attr/contact/vat

Veřejný PGP klíč

http://specs.nic.cz/attr/public_pgp

Bankovní účet

http://specs.nic.cz/attr/bank/national

Bankovní účet (IBAN)

http://specs.nic.cz/attr/bank/iban

Datová schránka

http://specs.nic.cz/attr/contact/isds

Příznak - NIA
Pouze pro Plný přístup
("0"/"1"/"true"/"false")

http://specs.nic.cz/attr/contact/nia

Internetové adresy

Hlavní

http://specs.nic.cz/attr/url/main

Blog

http://specs.nic.cz/attr/url/blog

Osobní

http://specs.nic.cz/attr/url/personal

Pracovní

http://specs.nic.cz/attr/url/work

RSS

http://specs.nic.cz/attr/url/rss

Facebook

http://specs.nic.cz/attr/url/facebook

Twitter

http://specs.nic.cz/attr/url/twitter

LinkedIN

http://specs.nic.cz/attr/url/linkedin

instagram

http://specs.nic.cz/attr/url/instagram

pinterest

http://specs.nic.cz/attr/url/pinterest

tumblr

http://specs.nic.cz/attr/url/tumblr

wordpress

http://specs.nic.cz/attr/url/wordpress

foursquare

http://specs.nic.cz/attr/url/foursquare

youtube

http://specs.nic.cz/attr/url/youtube

blogger

http://specs.nic.cz/attr/url/blogger

gravatar

http://specs.nic.cz/attr/url/gravatar

about_me

http://specs.nic.cz/attr/url/about_me

Flickr

http://specs.nic.cz/attr/url/flickr

Vimeo

http://specs.nic.cz/attr/url/vimeo

Instant Messaging

ICQ

http://specs.nic.cz/attr/im/icq

Skype

http://specs.nic.cz/attr/im/skype

Jabber

http://specs.nic.cz/attr/im/jabber

Hangouts

http://specs.nic.cz/attr/im/google_talk

Windows Live

http://specs.nic.cz/attr/im/windows_live

8.5. Příloha č. 5 – Seznam údajů pro registraci

Údaj

Formát

Registrace

Jméno

Křestní jméno

řetězec o maximální délce 50 znaků

first_name

Příjmení

řetězec o maximální délce 50 znaků

last_name

E-mail

Hlavní

e-mailová adresa o maximální délce 200 znaků STD-EMAIL

email__default__email

Notifikační

e-mailová adresa o maximální délce 200 znaků STD-EMAIL

email__notify__email

Další

e-mailová adresa o maximální délce 200 znaků STD-EMAIL

email__next__email

Adresa trvalého bydliště / sídla firmy

Ulice

řetězec o maximální délce 200 znaků

address__default__street1

Ulice2

řetězec o maximální délce 200 znaků

address__default__street2

Ulice3

řetězec o maximální délce 200 znaků

address__default__street3

Město

řetězec o maximální délce 200 znaků

address__default__city

Stát

řetězec o maximální délce 200 znaků

address__default__state

PSČ

řetězec o maximální délce 50 znaků

address__default__postal_code

Země

kód země podle ISO3166 STD-COUNTRY

address__default__country

Fakturační adresa

Ulice

řetězec o maximální délce 200 znaků

address__billing__street1

Ulice2

řetězec o maximální délce 200 znaků

address__billing__street2

Ulice3

řetězec o maximální délce 200 znaků

address__billing__street3

Město

řetězec o maximální délce 200 znaků

address__billing__city

Stát

řetězec o maximální délce 200 znaků

address__billing__state

PSČ

řetězec o maximální délce 50 znaků

address__billing__postal_code

Země

kód země podle ISO3166 STD-COUNTRY

address__billing__country

Doručovací adresa

Firma

řetězec o maximální délce 200 znaků

address__shipping__company_name

Ulice

řetězec o maximální délce 200 znaků

address__shipping__street1

Ulice2

řetězec o maximální délce 200 znaků

address__shipping__street2

Ulice3

řetězec o maximální délce 200 znaků

address__shipping__street3

Město

řetězec o maximální délce 200 znaků

address__shipping__city

Stát

řetězec o maximální délce 200 znaků

address__shipping__state

PSČ

řetězec o maximální délce 50 znaků

address__shipping__postal_code

Země

kód země podle ISO3166 STD-COUNTRY

address__shipping__country

Korespondenční adresa

Ulice

řetězec o maximální délce 200 znaků

address__mailing__street1

Ulice2

řetězec o maximální délce 200 znaků

address__mailing__street2

Ulice3

řetězec o maximální délce 200 znaků

address__mailing__street3

Město

řetězec o maximální délce 200 znaků

address__mailing__city

Stát

řetězec o maximální délce 200 znaků

address__mailing__state

PSČ

řetězec o maximální délce 50 znaků

address__mailing__postal_code

Země

kód země podle ISO3166 STD-COUNTRY

address__mailing__country

Telefon

Mobil

řetězec odpovídající regulárnímu výrazu: ^+[0-9]{1,3}.[0-9]{1,14}$

phone__default__number

Pracovní

řetězec odpovídající regulárnímu výrazu: ^+[0-9]{1,3}.[0-9]{1,14}$

phone__office__number

Další

řetězec odpovídající regulárnímu výrazu: ^+[0-9]{1,3}.[0-9]{1,14}$

phone__mobile__number

Domácí

řetězec odpovídající regulárnímu výrazu: ^+[0-9]{1,3}.[0-9]{1,14}$

phone__home__number

Telefon - Fax

řetězec odpovídající regulárnímu výrazu: ^+[0-9]{1,3}.[0-9]{1,14}$

phone__fax__number

Další údaje

Datum narození

datum ve formátu RFC3339 (YYYY-MM-DD) STD-DATE

birth_date

Pohlaví

hodnota „M“ nebo „F“

gender

Číslo OP

řetězec o maximální délce 50 znaků

id_card_num

Číslo pasu

řetězec o maximální délce 50 znaků

passport_num

Identifikátor MPSV

řetězec o maximální délce 50 znaků

ssn_id_num

Číslo ISIC

řetězec o maximální délce 50 znaků

card_isic

Jméno společnosti

řetězec o maximální délce 200 znaků

organization

IČO

řetězec o maximální délce 50 znaků

vat_id_num

DIČ

řetězec o maximální délce 50 znaků

vat_reg_num

Internetové adresy

Hlavní

řetězec o maximální délce 255 znaků

urladdress__main__url

Blog

řetězec o maximální délce 255 znaků

urladdress__blog__url

Osobní

řetězec o maximální délce 255 znaků

urladdress__personal__url

Pracovní

řetězec o maximální délce 255 znaků

urladdress__office__url

RSS

řetězec o maximální délce 255 znaků

urladdress__rss__url

Facebook

řetězec o maximální délce 255 znaků

urladdress__facebook__url

Twitter

řetězec o maximální délce 255 znaků

urladdress__twitter__url

LinkedIN

řetězec o maximální délce 255 znaků

urladdress__linkedin__url

instagram

řetězec o maximální délce 255 znaků

urladdress__instagram__url

pinterest

řetězec o maximální délce 255 znaků

urladdress__pinterest__url

tumblr

řetězec o maximální délce 255 znaků

urladdress__tumblr__url

wordpress

řetězec o maximální délce 255 znaků

urladdress__wordpress__url

foursquare

řetězec o maximální délce 255 znaků

urladdress__foursquare__url

youtube

řetězec o maximální délce 255 znaků

urladdress__youtube__url

blogger

řetězec o maximální délce 255 znaků

urladdress__blogger__url

gravatar

řetězec o maximální délce 255 znaků

urladdress__gravatar__url

about_me

řetězec o maximální délce 255 znaků

urladdress__about_me__url

Instant Messaging

ICQ

řetězec o maximální délce 255 znaků

imaccount__icq__username

Skype

řetězec o maximální délce 255 znaků

imaccount__skype__username

Windows Live

řetězec o maximální délce 255 znaků

imaccount__windows_live__username

Jabber

řetězec o maximální délce 255 znaků

imaccount__jabber__username

Hangouts

řetězec o maximální délce 255 znaků

imaccount__google_talk__username

STD-EMAIL

E-mailová adresa ve formátu podle RFC 2822

STD-COUNTRY

Kód země podle ISO 3166

STD-DATE

Datum ve formátu RFC 3339

8.6. Příloha č. 6 – Příklady a řešení chybových hlášek

Následující článek popisuje nejčastější chybové hlášky, které při implementaci MojeID mohou vzniknout. V textu jsou dále popsána doporučení, jak chybu řešit, případně na co se zaměřit.

8.6.1. Chybové hlášky na testovací instanci

Chyby se vypisují přímo z použitých knihoven. Zde jsou vypsány ty nejdůležitější:

  • „Error parsing document as XML“„Not a XRDS document“ – Obojí znamená chybný XRDS dokument. Tato hláška obvykle značí problém v XRDS dokumentu, že XML kód není validní (nejčastěji kvůli obsahu nestandardních unicode znaků). Na adrese http://www.xmlvalidation.com je možné si zdrojový kód překontrolovat a zjistit tak, kde se chyba nachází.

  • „No XRD present in tree“ – XRDS dokument nemá žádný XRD element. Překontrolujte obsah XRDS dokumentu, viz sekci XRDS dokument a jeho formát. Pozor také na velikost písmen ve značkách!

  • „HTTP Response status from identity URL host is not 200. Got status XXX“ – dotaz na realm nebo XRDS dokument vrátil stavový kód HTTP jiný než 200.

  • Chyby z cURLu jsou ve tvaru „(XX, …)“, kde XX je číslo chyby ze seznamu chyb libcURL viz https://curl.haxx.se/libcurl/c/libcurl-errors.html

8.6.2. Problémy s ověřením návratové adresy

V případě, že se nepodaří ověřit návratovou adresu služby, je zobrazena uživateli některá z následujících zpráv podle toho, ve které fázi došlo k negativnímu výsledku:

  1. Pokud se nepodařilo spojit se službou

„Nelze ověřit důvěryhodnost služby, kam se přihlašujete přes MojeID. Buďte zvláště obezřetní při předávání údajů z MojeID této službě.“
„We can not validate authenticity of the service where you want to login with MojeID. Use extra caution when handing over the data from MojeID.“

Tato hláška je zobrazena, pokud dotaz na realm nebo dokument XRDS vrátil stavový kód HTTP 4xx nebo 5xx. Pokud to není ten případ, může hláška značit problém s certifikátem při použití HTTPS.

Pro správné fungování HTTPS je třeba mít platný certifikát, který si můžete pořídit od certifikační autority (viz také Problém s nezašifrovaným spojením). Zároveň musíte mít i tzv. intermediate certifikáty, aby vůbec došlo k hledání XRDS dokumentu. Musí být správně nastaven serverový certifikát, např. na serveru Apache se intermediate certifikáty nastaví pomocí direktivy SSLCertificateChainFile, příp. SSLCertificateFile, viz dokumentaci nastavení SSL v Apache.

Přehled certifikačních autorit, které MojeID podporuje, naleznete na adrese: https://wiki.mozilla.org/CA/Included_Certificates

Při odlaďování problémů se SSL a certifikáty vám mohou pomoci přímé nástroje, např. programy wget nebo curl, případně nějaký mechanismus použité knihovny, které umí potíže odhalit lépe než běžné prohlížeče.

  1. Pokud se podařilo spojit se službou, ale ověření návratové adresy selhalo

„Tento požadavek na přihlášení přes MojeID o sobě tvrdí, že přichází z jiné stránky, než tomu ve skutečnosti je. Zvažte, zda vůbec chcete pokračovat s předáváním údajů z vašeho MojeID.“
„This MojeID login request claims to be from other site than it really is. Consider carefully whether you want to continue with handing over the data from your MojeID.“

Selhání při ověření návratové adresy může nastávat z těchto příčin:

  • Realm nevrátil stavový kód HTTP 200.

  • Na realmu se nenachází XRDS dokument, nemůže tak dojít k ověření služby. Umístění XRDS dokumentu na realmu musí být jedním ze tří způsobů:

    • XRDS dokument se může nacházet přímo v HTTP hlavičce

    • XRDS dokument může být uložen přímo na adrese realmu (zaslán přímo v odpovědi)

    • umístění může být uvedeno v hlavičce HTML ve značce META

  • Během procesu stahování XRDS dokumentu se objevilo přesměrování.

  • Když nesedí adresa return_to v OpenID požadavku s adresou return_to v XRDS dokumentu. Adresa return_to z OpenID požadavku může obsahovat navíc pouze další parametry, tzv. query string, nikoli podadresáře v cestě.

  • Když adresa return_to z OpenID požadavku „není rozšířením“ adresy realmu.

    Pojem adresa A „je rozšířením“ adresy B znamená, že:

    • protokol je stejný,

    • doména je stejná nebo navíc obsahuje poddoménu, pokud doména B začíná na *.,

    • port je stejný,

    • cesta je stejná nebo obsahuje podadresáře, a

    • query string (?klic=hodnota&klic2=hodnota2) stejný nebo s parametry navíc.

Příklady: adresa A „je rozšířením“ adresy B

Platnost tvrzení

Adresa A

Adresa B

Ano

https://example.com/ahoj/

https://example.com/ahoj/

Ne

http://example.com/ahoj/

https://example.com/ahoj/

Ne

https://example.com:8080/ahoj/

https://example.com/ahoj/

Ano

https://example.com/ahoj/cau/

https://example.com/ahoj/

Ne

https://example.com/ahoj/

https://example.com/cau/

Ne

https://example.com/ahoj/

https://example.com/ahoj/cau/

Ano

https://example.com/ahoj/?klic=hodnota

https://example.com/ahoj/?klic=hodnota

Ano

https://example.com/ahoj/?klic=hodnota&klic2=hodnota2

https://example.com/ahoj/?klic=hodnota

Ne

https://example.com/ahoj/?klic=hodnota

https://example.com/ahoj/?klic=hodnota&klic2=hodnota2

Ano

https://subdomain.example.com/ahoj/?klic=hodnota

https://*.example.com/

  1. Pokud oblast URL služby nelze spravovat v MojeID

„Tento realm není dobře definovaný a nelze k němu nastavit důvěru.“
„This realm is not sane and thus you can not set trust for it.“

Ověřte, že váš realm (uvedený v žádosti o ověření identity) neobsahuje IP adresu, pro URL nepovolené znaky nebo URI fragment. Viz také Výběr vhodného realmu.

8.6.3. Problém s nezašifrovaným spojením

Může se stát, že prohlížeč zobrazí při přesměrování zpět na vaše stránky následující hlášku:

„Informace, které jste zadali, budou odeslány přes nezašifrované spojení a mohly by jednoduše být přečteny třetí stranou. Určitě chcete pokračovat v odesílání?“
„The information you have entered will be sent over an unencrypted connection and could easily be read by a third party. Are you sure you want to continue sending it?“

Poznámka

Uvedená hláška pochází z Firefoxu, v jiných prohlížečích pravděpodobně bude mít odlišné znění.

Toto hlášení se může objevit u všech realmů bez HTTPS. Předávané údaje (tj. i uživatelovy osobní údaje) putují po internetu nešifrovaně, a prohlížeč hlásí, že opouští šifrované stránky MojeID směrem ke službě, která šifrování nepoužívá. Nešifrovaný protokol (HTTP) nedoporučujeme, ale chyba to není.

Tento problém se dá snadno vyřešit použitím základního SSL certifikátu, který je ke stažení zde: http://www.startssl.com/, pro nekomerční služby verze StartSSL Free a pro komerční služby verze StartSSL Verified. Tento certifikát Vám zabezpečí chráněný přenos dat a současně vidíte, jakou úroveň ověření uživatel má.

8.6.4. Volba vyžadované přihlašovací metody

Vyžadovaná přihlašovací metoda se zvolí umístěním identifikátoru příslušné přihlašovací metody do žádosti o ověření identity. Služba MojeID podporuje mimo běžného přihlašování heslem i přihlašování pomocí digitálního certifikátu, jednorázového hesla (OTP) nebo bezpečnostního tokenu.

  • V případě přihlášení pomocí certifikátu se zobrazuje následující hláška:

    „Poskytovatel služby požaduje přihlášení certifikátem.“
    „The service provider wants you to login with your certificate.“

  • V případě přihlášení pomocí jednorázového hesla nebo pomocí autentikátoru se zobrazuje následující hláška:

    „Poskytovatel služby požaduje přihlášení jednorázovým heslem nebo MojeID Autentikátorem.“
    „The service provider wants you to login with one time password or MojeID Autentikátor.“

  • V případě přihlášení pomocí bezpečnostního tokenu se zobrazuje následující hláška:

    „Poskytovatel služby požaduje přihlášení druhým faktorem.“
    „The service provider wants you to login with two-factor authentication.“

Identifikátory metod a příklad žádosti s vyžádáním přihlašovací metody naleznete v sekci Žádost o ověření identity.

8.6.5. Problémy s knihovnou pro PHP

Mezi časté chybové hlášky patří zejména „FAILED TO CREATE AUTH REQUEST: not a valid OpenID“„Ověření OpenID selhalo: No OpenID information“.

Některé chyby mohou být způsobeny chybnou konfigurací vašeho serveru. Pro jejich nápravu můžete zkusit následující kroky:

  • Je zapotřebí se ujistit, že je cURL pro danou verzi PHP nainstalováno, zapnuté (phpinfo by tak mělo hlásit) a že v php.ini není cURL zakázáno.

  • Případně může být třeba do souboru /etc/php5/conf.d/curl.ini uvést řádek extension=curl.so, pokud tam není.

  • Stáhněte si a nainstalujte nejnovější verzi cURL viz https://curl.haxx.se/download.html.

Dále Vám doporučujeme stáhnout a prostudovat si vzorovou implementaci v PHP.

8.6.6. Chybové odpovědi v JSONu (OIDC)

Chybové odpovědi obsahují kód chyby pod klíčem error ve formě ASCII řetězce. Lidsky čitelný popis chyby by se měl vyskytovat v JSON odpovědi pod klíčem error_description.

Chybové kódy, které může MojeID vrátit:

Kód chyby

Možné příčiny

unauthorized_client

Špatné client_id, špatné client_secret, špatně použitá autentifikace.

invalid_request

Chybějící povinné parametry, některý parametr nečitelný/neparsovatelný.

8.7. Příloha č. 7 – Zásady správné implementace

Při implementaci podpory služby MojeID dodržujte následující zásady:

  1. Přihlášení ke službě MojeID realizujte výhradně tlačítkem „Přihlásit přes MojeID“ dle vzoru v sekci Žádost o přihlášení přes MojeID.

_images/mojeid_tlacitko_Prihlasit.png
  1. Tlačítko „Přihlásit přes MojeID“ vhodně doplňte textovými odkazy „Proč MojeID?“ a „Založit účet MojeID“.

    1. Odkaz „Proč MojeID?“ nasměrujte na lokální stránku vysvětlující výhody využití MojeID na vašich stránkách (lokální výhody) nebo na informační stránku služby MojeID.

    2. Odkaz „Založit účet MojeID“ můžete nahradit tlačítkem „Založit účet MojeID“ dle vzoru.

      _images/mojeid_tlacitko_Zalozit.png

      Tlačítko nasměrujte na lokální registrační stránku MojeID nebo na univerzální registrační formulář služby MojeID .

      _images/mojeid_novy_ucet.png
    3. Pokud není možné doplnit tlačítko odkazy podle předchozích bodů (2.a a 2.b), doporučujeme přidat je na stránku administrace lokálního účtu uživatele.

  2. Pokud je to možné, umístěte na hlavní stránku logo „Podporuje MojeID“ dle vzoru s odkazem na místo ve vašem systému, kde je MojeID použito nebo na lokální stránku ve vašem systému s informací o službě MojeID.

_images/mojeid_tlacitko_Podporuje.png
  1. Požadované údaje pro předání musí být v souladu s vaším systémem:

    1. jako povinné musí být označeny pouze položky, které jsou povinné pro registrační proces ve vašem systému,

    2. ostatní požadované položky musí být označeny jako nepovinné,

    3. nesmíte požadovat k předání položky, které nevyužíváte v systému.

  2. Pokud při přihlášení přes MojeID vyžadujete předání údajů o uživateli, je – v případě, že se tyto údaje liší od údajů evidovaných v lokálním účtu vaší služby – doporučeno dát uživateli na výběr, zdali si přeje stávající údaje v lokálním účtu služby ponechat, nebo zda mají být přepsány údaji přenesenými z MojeID.

  3. Implementace služby MojeID musí být navržena tak, aby uživatel MojeID měl při svém prvním přístupu k vaší službě prostřednictvím MojeID na výběr z následujících dvou možností:

    1. spárování MojeID s existujícím lokálním účtem, nebo

    2. vytvoření nového lokálního účtu pomocí dat přenesených z MojeID a spárování tohoto nově založeného lokálního účtu s MojeID.

  4. V administraci lokálního účtu uživatele:

    1. doporučujeme při spárování s účtem MojeID zobrazit MojeID identifikátor uživatele,

    2. doporučujeme mít odkaz nebo tlačítko „Založit účet MojeID“ podle bodu 2. V případě, že uživatel ještě nemá spárovaný lokální účet s MojeID, a tedy pravděpodobně nemá MojeID, doporučujeme registrační formulář MojeID předvyplnit údaji z lokálního účtu uživatele,

      _images/mojeid_tlacitko_Zalozit.png
    3. musí mít uživatel možnost spárovat MojeID s existujícím lokálním účtem, pokud již není spárován.

    4. uživatel musí mít možnost odpojit lokální účet od účtu MojeID.

  5. Úpravy vzhledu tlačítek a dalších grafických prvků jsou možné jen s výslovným souhlasem sdružení CZ.NIC.

  6. Implementace MojeID musí být realizována výhradně na protokoli OpenID Connect nebo SAML dle specifikace v technické dokumentaci

Varování

Protokol OpenID 2.0 již není podporován.

9. Přehled změn

Verze

Segment

Popis změny

3.0.7

Celá dokumentace

Přejmenování mojeID na MojeID
Aktualizace obrázků a tlačítek
Oprava zastaralých a neplatných odkazů

3.0.6

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)
Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)
Dokončení registrace
Testovací instance MojeID

Odebrána možnost ověření účtů fyzických osob pomocí PIN3
Doplněna informace „Pouze pro Plný přístup“ u Korespondenční adresy

3.0.5

Základní principy MojeID
Napojení MojeID na NIA
Žádost o ověření identity účtem napojeným na NIA
Implementace pomocí SAML

Přidány informace o napojení mojeID na NIA

3.0.4

Proces komunikace přes OpenID 2.0
Favikona
Implementace pomocí OpenID 2.0 a všechny podkapitoly
Testovací instance MojeID
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)

Přidáno varování o plánovaném ukončení podpory protokolu OpenID 2.0 na všechny relevantní stránky

3.0.3

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)
Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)

Přidáno údaj Příznak - NIA do seznamu předávaných údajů
Změna pojmu Domácí adresa na Adresa trvalého bydliště / sídla firmy

3.0.2

Celá dokumentace (anglická verze)

Oprava překlepů a nepřeloženého textu

3.0.1

Jen HTML část

Přidány odkazy na jazykové verze
Logo dokumentace odkazuje na hlavní stránku webu

Celá dokumentace (anglická verze)

Pojem „disclose“ změněn na „hand over“ v kontextu předávaných údajů
Opraveny některé překlepy

3.0

Celá dokumentace

Přidána anglická verze dokumentace

2.18

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)

Doplněn předávaný údaj „country“ u OIDC

Žádost o ověření identity
Příloha č. 6 – Příklady a řešení chybových hlášek

Doplněna varianta přihlášení pomocí bezpečnostního tokenu včetně příslušných uživatelských hlášek

Proces komunikace přes OpenID Connect
Proces komunikace přes OpenID 2.0

Doplněna přihlašovací metoda – bezpečnostní token

2.17

Registrace klienta

Doplněn postup ruční registrace klienta v testovací instanci mojeID pro protokol OIDC

2.16

Přechod na jiný protokol

Změna textu sekce Přechod na jiný protokol, přidání konkrétních informací o přechodu z OID2 na OIDC

Rozdíly mezi protokoly

Přidání mezer kolem lomítka v sekci Implementace pomocí OpenID Connect (OIDC)

Implementace pomocí OpenID Connect (OIDC)

Oprava dvou velkých písmen pro větší konzistenci v sekci Žádost o ověření identity

2.15

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)
Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)

Opraveno označení Pro plný přístup u předávaných údajů

2.14

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)

Popsány datové typy předávaných údajů

2.13

Právní upozornění

Přidáno právní upozornění týkající se dokumentace

Přehled změn

Přepracován s nejnovějšími změnami nahoře

2.12

Registrace klienta, Žádost o data

Opraveny nevalidní JSON příklady

Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)
Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)
Příloha č. 5 – Seznam údajů pro registraci

Odstraněny předávané údaje „Číslo Opencard“ a „google_plus“ u všech protokolů

2.11

Všude

Opraveny odkazy na nové webové stránky mojeID

2.10

Přehled kroků implementace

Přidán přehled kroků implementace pomocí OIDC

Přehled knihoven a modulů

Přidán přehled knihoven a modulů pro OIDC

Přehled knihoven a modulů

Přidán přehled knihoven a modulů pro OID2

2.9

Favikona

Vysvětlení účelu favikony a pokyny k jejímu nastavení

Odhlašování od služby MojeID

Pokyny k možnosti odhlášení

Příloha č. 6 – Příklady a řešení chybových hlášek

Změněno doporučení k ladění SSL

2.8

Implementace podpory MojeID

Důležitá poznámka o zakázaném použití rámců

2.7

Testovací instance MojeID

Aktualizovány adresy podle nového testovacího serveru a výslovně vypsány všechny endpointy OIDC

Všude

Nová adresa na technickou podporu techsupport@mojeid.cz

2.6

Všude

Změněno pořadí protokolů – OIDC jako první

Provedení autentizace (XRDS a realm)

Změněn název kapitoly

2.5

Registrace klienta

Přidána možnost ruční registrace služby v OpenID Connect přes nové rozhraní serveru mojeID

2.4

Rozhraní pro zakládání účtů MojeID

Rozšířeno o podporu přímé registrace i přes protokol OpenID Connect

2.3

Testovací instance MojeID

Doplněny informace pro testování komunikace přes protokoly OIDC a SAML

Implementace pomocí OpenID Connect (OIDC)

Doplněny ukázky kódu a komunikace pro implementaci pomocí protokolu OIDC

Ladění komunikace se serverem MojeID

Doplněno doporučení k odlaďování komunikace

Příloha č. 6 – Příklady a řešení chybových hlášek

Přidána zmínka o chybových odpovědích v JSON u OIDC, nahrazen zastaralý odkaz

Příloha č. 2 – Seznam údajů pro předání (OpenID 2.0)
Příloha č. 1 – Seznam údajů pro předání (OpenID Connect)
Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)

Přidán údaj pro předání – datová schránka (ISDS)

2.2

Příloha č. 4 – Seznam údajů pro předání (SAML specs.nic.cz)

Přidán seznam dalších identifikátorů pro předávání údajů přes SAML

2.1

Základní principy MojeID

Přesunutí odkazů na specifikace protokolů do Implementace pomocí OpenID 2.0Implementace pomocí OpenID Connect (OIDC)

Implementace pomocí OpenID Connect (OIDC)

Přidán odkaz na konfiguraci OIDC na serveru mojeID

Registrace klienta

Přidána zmínka o metadatech klienta a doplňující info k ruční registraci

Knihovna MojeID LITE

Přidán celý segment

Implementace pomocí SAML

Přidán odkaz na certifikát pro ověření metadat a na nástroj pro dekódování zpráv SAMLu

Problémy při implementaci

Přidán celý segment

Příloha č. 6 – Příklady a řešení chybových hlášek

Přidán odkaz na nástroj k otestování nastavení SSL

Přehled změn

Přidán celý segment