Technická dokumentace pro implementaci MojeID

Vydání: 3.1

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 udaje-openid, 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.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 SAML

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).

4.1.1.1. MojeID plugin pro WordPress

Důležité

Níže uvedený návod ještě dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s ním.

4.1.1.1.1. Instalace rozšíření
4.1.1.1.1.1. V administraci z repozitáře WordPress pluginů
  1. V administraci WordPressu klikněte na záložku Pluginy a nahoře na stránce zvolte Intalace pluginů.

  2. Vyhledejte plugin OpenID Connect Generic Client autora daggerhart, klikněte u něj na Instalovat a následně na Aktivovat. Dále postupujte podle Registrace služby do MojeID.

4.1.1.1.1.2. V administraci pomocí instalačního balíčku
  1. Stáhněte si OpenID Connect Generic plugin, který je dostupný na stránce WordPress pluginů a na GitHubu.

  2. V administraci WordPressu klikněte na záložku Pluginy a nahoře na stránce zvolte Intalace pluginů. Klikněte na tlačítko Nahrát plugin, zvolte stažený archiv a klikněte na Instalovat. Následně plugin aktivujte a postupujte podle Registrace služby do MojeID.

4.1.1.1.1.3. Nahráním souborů na server (např. FTP/SCP)
  1. Stáhněte si OpenID Connect Generic plugin, který je dostupný na stránce WordPress pluginů a na GitHubu.

  2. Stažený archiv extrahujte a celou složku přesuňte na server, na němž běží instance WordPressu, do složky /wp-content/plugins/.

  3. V administraci WordPressu klikněte na záložku Pluginy, vyberte plugin OpenID Connect Generic a klikněte na tlačítko Aktivovat.

  4. V záložce Nastavení vyberte OpenID Connect Client a poznamenejte si řetězec Redirect URI, který naleznete vespodu stránky.

4.1.1.1.2. Registrace služby do MojeID

Pokud registrujete testovací službu, přejděte na sekci Registrace testovací služby. Pokud registrujete službu jdoucí do produkce, přejděte na sekci Registrace produkční služby.

4.1.1.1.2.1. Registrace testovací služby

Více informací o testovací instanci MojeID lze najít v sekci Testovací instance MojeID.

  1. Jděte na úvodní stránku veřejné testovací instance MojeID a za pomoci přítomného návodu si založte testovací účet.

  2. Přejděte na adresu https://mojeid.regtest.nic.cz/consumer_admin/. Zde klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta a do položky Seznam URI pro přesměrování vložte řetězec adresy Redirect URI, který jste si poznamenali v posledním kroku instalace rozšíření do WordPressu.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Přihlašovací údaje v těle požadavku a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

  6. Dále postupujte dle Konfigurace rozšíření.

4.1.1.1.2.2. Registrace produkční služby
  1. Založte si MojeID účet.

  2. Přejděte na adresu https://mojeid.cz/consumer_admin/. Zde klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta a do položky Seznam URI pro přesměrování vložte řetězec adresy Redirect URI, který jste si poznamenali v posledním kroku instalace rozšíření do WordPressu.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Přihlašovací údaje v těle požadavku a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

4.1.1.1.3. Konfigurace rozšíření
  1. V administraci WordPressu klikněte na záložku Nastavení a přejděte do sekce OpenID Connect Client. Zde vyplňte ID klienta, které jste získali během registrace služby, do pole Client ID a tajemství klienta do pole Client secret.

  2. Vyplňte položku OpenID Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  3. Vyplňte adresy endpointů v závislosti na tom, zda jde o testovací instanci, nebo o instanci jdoucí do produkce:

    Konfigurace testovacích endpointů

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

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

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

    Konfigurace produkčních endpointů

    • Login Endpoint URL: https://mojeid.cz/oidc/authorization/

    • Userinfo Endpoint URL: https://mojeid.cz/oidc/userinfo/

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

  4. Nastavte hodnoty položek Identity key, Nickname Key, Email Formatting a Display Name Formatting. Jako Identity Key a Nickname Key doporučujeme použít email a možnost Identify with User Name nechat odškrtnutou.

    Varování

    Do těchto položek můžete vyplnit pouze hodnoty, které si od uživatele vyžádáte v OpenID Scope. Nelze tedy například například nastavit formát jména, pokud v OpenID Scope nevznášíte požadavek na scope profile.

  5. Odškrtněte políčko Enable Refresh Token a zaškrtněte Link Existing Users.

  6. Nastavení uložte tlačítkem Save Changes.

4.1.1.1.3.1. Účty napojené na NIA

Je-li účet napojen na NIA, jsou všechny osobní údaje (jméno, adresy atp.) ověřené. Toho lze využít například k povolení vkládání komentářů pod příspěvky pouze ověřeným uživatelům, povolení přístupu na určité stránky pouze zletilým osobám nebo zasílání pošty pouze na ověřené adresy.

Vzorová implementace využití NIA je k nalezení zde v podobě pluginu, jenž automaticky schvaluje komentáře uživatelů, kteří jsou přihlášeni přes MojeID a mají svůj účet propojený se službami veřejné správy.

Důležité

Plugin slouží hlavně jako vzorová implementace a ukázka možností, jichž lze s MojeID dosáhnout. Neobsahuje tedy žádné WordPressové hooky, na které by se mohly napojovat další pluginy, a při implementaci je třeba buď tento plugin odpovídajícím způsobem upravit, nebo vytvořit vlastní.

4.1.1.1.3.2. Výzva k předávání údajů

V případě, že uživatel nepovolil předání nezbytných informací, jako je například email, a zaškrtl možnost Předávat při každém přihlášení, MojeID si tuto volbu zapamatuje a při každém dalším pokusu o přihlášení dojde k chybě kvůli nepředaným informacím. Pro tento účel můžete využít require prompt addon, který při každém přihlášení vyzve uživatele k potvrzení předávaných informací.

Poznámka

Tento problém může uživatel odstranit přihlášením do účtu MojeID a odstraněním služby v sekci Nastavení > Předávání údajů. Zde klikne na tlačítko u příslušné služby a zvolí Uložit. Následně se může opět zkusit přihlásit a povolit předání všech potřebných informací.

Instalace addonu

  • Stáhněte si require prompt addon.

  • V adresáři WordPressu vytvořte složku wp-content/mu-plugins/, pokud již neexistuje. Přesuňte sem soubor oidc-require-prompt-addon.php.

  • V nastavení OpenID Connect pluginu zaškrtněte možnost Require prompt a nastavení uložte.

4.1.1.1.3.3. Přihlášení pouze s účtem napojeným na NIA

Pokud chcete omezit okruh uživatelů, kteří se mohou přes MojeID přihlásit, pouze na ty, kteří mají svůj účet propojen s NIA, zadejte do pole ACR values řetězec http://eidas.europa.eu/LoA/substantial, kterým se vyžádá úrověň záruky „značná“. Pro více informací o úrovni záruky navštivte stránky Napojení MojeID na NIA a Žádost o ověření identity účtem napojeným na NIA.

Poznámka

Řetězec skutečně odkazuje na protokol http, nikoli na https.

Chcete-li po uživateli pro přihlášení vyžadovat úroveň záruky „vysoká“, zaměňte hodnotu substantial za high. Pro běžné užití však úroveň „značná“ postačuje.

4.1.1.2. MojeID plugin pro Joomla

Důležité

Níže uvedený návod ještě dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s ním.

4.1.1.2.1. Instalace rozšíření

Stáhněte si OpenID Connect plugin. V administraci Joomly přejděte do System, v kategorii Install zvolte Extensions a nahrajte sem stažený archiv.

4.1.1.2.2. Registrace služby do MojeID

Pokud registrujete testovací službu, přejděte na sekci Registrace testovací služby. Pokud registrujete službu jdoucí do produkce, přejděte na sekci Registrace produkční služby.

4.1.1.2.2.1. Registrace testovací služby

Více informací o testovací instanci MojeID lze najít v sekci Testovací instance MojeID.

  1. Jděte na úvodní stránku veřejné testovací instance MojeID a za pomoci přítomného návodu si založte testovací účet.

  2. Přejděte na adresu https://mojeid.regtest.nic.cz/consumer_admin/. Zde klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta, do položky Seznam URL pro přesměrování vložte řetězec http://example.com/index.php?option=com_openidconnect a nahraďte v něm example.com svou vlastní doménou.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Základní HTTP autentifikace a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

4.1.1.2.2.2. Registrace produkční služby
  1. Založte si MojeID účet.

  2. Přejděte na adresu https://mojeid.cz/consumer_admin/. Zde klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta, do položky Seznam URL pro přesměrování vložte řetězec http://example.com/index.php?option=com_openidconnect a nahraďte v něm example.com svou vlastní doménou.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Základní HTTP autentifikace a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

4.1.1.2.3. Konfigurace rozšíření
  1. V administraci Joomly v záložce System zvolte Global Configuration a v postranní liště vyberte OpenID Connect.

  2. Vyplňte ID klienta, které jste získali během registrace služby, do pole Client ID a tajemství klienta do pole Client secret.

  3. Vyplňte adresy endpointů v závislosti na tom, zda jde o testovací instanci, nebo o instanci jdoucí do produkce:

    Konfigurace testovacích endpointů

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

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

    • Userinfo endpoint URL: https://mojeid.regtest.nic.cz/oidc/userinfo/

    Konfigurace produkčních endpointů

    • Authorization endpoint URL: https://mojeid.cz/oidc/authorization/

    • Token endpoint URL: https://mojeid.cz/oidc/token/

    • Userinfo endpoint URL: https://mojeid.cz/oidc/userinfo/

  4. Vyplňte položku OpenID Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  5. Volitelně zaškrtněte možnost Require prompt, která při každém přihlášení vyzve uživatele k potvrzení předávaných informací. Tato možnost se hodí v případě, že uživatel nepovolil předání nezbytných informací, jako je například email, a zaškrtl možnost Předávat při každém přihlášení. MojeID si tuto volbu zapamatuje a při každém dalším pokusu o přihlášení proto dojde k chybě kvůli nepředaným informacím.

    Poznámka

    Tento problém může uživatel odstranit přihlášením do účtu MojeID a odstraněním služby v sekci Nastavení > Předávání údajů. Zde klikne na tlačítko u příslušné služby a zvolí Uložit. Následně se může opět zkusit přihlásit a povolit předání všech potřebných informací.

  6. Do kolonky Post-login redirect URL vyplňte relativní cestu stránky, na kterou má být uživatel po přihlášení přesměrován, například index.php.

  7. Nastavení potvrďte tlačítkem Save navrchu stránky.

4.1.1.2.4. Umístění tlačítka pro přihlášení
  1. Stáhněte si balíček grafických prvků a extrahujte jej.

  2. V administraci Joomly otevřete v postranní nabídce položku Content a klikněte na tlačítko + vedle Site Modules.

  3. Zvolte modul Custom. V editoru klikněte na tlačítko CMS Content a vyberte Media.

  4. V okně Media, které se otevře, klikněte v horní části na Upload a nahrajte tlačítko pro přihlášení. Lze nahrát pouze obrázky formátu PNG. Toto tlačítko vyberte a klikněte na Insert Media.

  5. Označte kliknutím obrázek, který jste vložili, v liště editoru rozklikněte menu (…) a zvolte ikonu linku (Insert/Edit link). Do pole URL vložte řetězec https://example.com/index.php?option=com_openidconnect&task=login a nahraďte v něm example.com svou vlastní doménou, volitelně můžete obrázek vycentrovat. Modul uložte kliknutím na Save.

  6. V liště na pravé straně zvolte v rozbalovací nabídce Position umístění tlačítka.

  7. Pokud chcete na stránce skrýt název modulu, přepněte přepínač Title. Pokud chcete název zobrazit, nazvěte modul Přihlásit přes MojeID. Nastavení uložte.

4.1.1.3. MojeID plugin pro PrestaShop

Důležité

Níže uvedený návod ještě dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s ním.

4.1.1.3.1. Instalace rozšíření
  1. Stáhněte si OpenID Connect plugin.

  2. V administraci PrestaShopu klikněte na záložku Moduly a vyberte Správce modulů. Klikněte na tlačítko Nahrát modul a v dialogovém okně zvolte stažený archiv. Následně zvolte možnost Konfigurovat.

  3. Zkopírujte si řetězec Redirect URL z poslední kolonky na stránce. Záložku nezavírejte.

4.1.1.3.2. Konfigurace rozšíření
  1. V otevřené záložce vyplňte ID klienta, které jste získali v minulém kroku, do pole Client ID a tajemství klienta do pole Client secret. Nepovinně můžete vyplnit i jméno služby.

  2. Vyplňte adresy endpointů v závislosti na tom, zda jde o testovací instanci, nebo o instanci jdoucí do produkce:

    Konfigurace testovacích endpointů

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

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

    • Userinfo endpoint URL: https://mojeid.regtest.nic.cz/oidc/userinfo/

    Konfigurace produkčních endpointů

    • Authorization endpoint URL: https://mojeid.cz/oidc/authorization/

    • Token endpoint URL: https://mojeid.cz/oidc/token/

    • Userinfo endpoint URL: https://mojeid.cz/oidc/userinfo/

  3. Vyplňte položku Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  4. Volitelně zaškrtněte možnost Require prompt, která při každém přihlášení vyzve uživatele k potvrzení předávaných informací. Tato možnost se hodí v případě, že uživatel nepovolil předání nezbytných informací, jako je například email, a zaškrtl možnost Předávat při každém přihlášení. MojeID si tuto volbu zapamatuje a při každém dalším pokusu o přihlášení proto dojde k chybě kvůli nepředaným informacím.

    Poznámka

    Tento problém může uživatel odstranit přihlášením do účtu MojeID a odstraněním služby v sekci Nastavení > Předávání údajů. Zde klikne na tlačítko u příslušné služby a zvolí Uložit. Následně se může opět zkusit přihlásit a povolit předání všech potřebných informací.

  5. Nastavení potvrďte tlačítkem Uložit.

4.1.1.4. MojeID plugin pro OpenCart

Důležité

Níže uvedený návod ještě dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s ním.

4.1.1.4.1. Instalace rozšíření
  1. Stáhněte si OpenID Connect plugin.

  2. V administraci Opencartu přejděte do Extensions, v kategorii Installer klikněte na tlačítko Upload (šipka vzhůru) a nahrajte sem stažený archiv.

  3. V seznamu Installed Extensions najděte plugin OpenID Connect a klikněte u něj na zelené tlačítko +.

  4. V kategorii Extensions přejděte do Extensions a v rozbalovací nabídce Choose the extension type vyberte Modules.

  5. V seznamu Modules najděte OpenID Connect, aktivujte jej kliknutím na zelené tlačítko + a vstupte do nastavení kliknutím na ikonu tužky.

  6. Zkopírujte si řetězec Redirect URL vespodu stránky a záložku nezavírejte.

4.1.1.4.2. Konfigurace rozšíření
  1. V otevřené záložce OpenID Connect vyplňte ID klienta, které jste získali během registrace služby, do pole Client ID a tajemství klienta do pole Client secret.

  2. Vyplňte adresy endpointů v závislosti na tom, zda jde o testovací instanci, nebo o instanci jdoucí do produkce:

    Konfigurace testovacích endpointů

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

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

    • Userinfo endpoint URL: https://mojeid.regtest.nic.cz/oidc/userinfo/

    Konfigurace produkčních endpointů

    • Authorization endpoint URL: https://mojeid.cz/oidc/authorization/

    • Token endpoint URL: https://mojeid.cz/oidc/token/

    • Userinfo endpoint URL: https://mojeid.cz/oidc/userinfo/

  3. Vyplňte položku OpenID Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  4. Volitelně zaškrtněte možnost Require prompt, která při každém přihlášení vyzve uživatele k potvrzení předávaných informací. Tato možnost se hodí v případě, že uživatel nepovolil předání nezbytných informací, jako je například email, a zaškrtl možnost Předávat při každém přihlášení. MojeID si tuto volbu zapamatuje a při každém dalším pokusu o přihlášení proto dojde k chybě kvůli nepředaným informacím.

    Poznámka

    Tento problém může uživatel odstranit přihlášením do účtu MojeID a odstraněním služby v sekci Nastavení > Předávání údajů. Zde klikne na tlačítko u příslušné služby a zvolí Uložit. Následně se může opět zkusit přihlásit a povolit předání všech potřebných informací.

  5. Nastavení potvrďte tlačítkem Save vespodu stránky.

4.1.1.4.3. Umístění tlačítka pro přihlášení

Tlačítko pro přihlášení pomocí MojeID musí být přidáno ručně do zdrojového kódu šablony stránky. Šablony můžete upravovat v záložce Design > Theme Editor > commmon.

4.1.1.4.3.1. Příklady implementace

Tlačítko v záhlaví stránky

Do šablony header.twig vložte mezi řádky 56 a 57 následující kód, v němž nahradíte example.com svou vlastní doménou:

<li><a href="http://example.com/index.php?route=extension%2Fopenidconnect%2Fmodule%2Fopenidconnect.login" class="dropdown-item">Přihlásit přes MojeID</a></li>

Důležité

Pokud jste již v šabloně dělali změny, číslo řádku se může lišit. Kód vložte do třídy dropdown-menu dropdown-menu-right mezi statementy {%if not logged%} a {%else%} a ujistěte se, že jej nevkládáte do jiné položky třídy dropdown-item. Těsně před Vámi vloženým kódem musí být html tag </li>.

Tlačítko v zápatí stránky

Stáhněte si balíček grafických prvků a obrázek tlačítka pro přihlášení nahrajte na server do složky image instance OpenCartu. Doporučujeme formát SVG.

Do šablony footer.twig vložte mezi řádky 43 a 44 následující kód, v němž nahradíte example.com svou vlastní doménou a X číslem obrázku, který chcete pro tlačítko použít:

{% if not logged %}
<li>
<a href="http://example.com/index.php?route=extension%2Fopenidconnect%2Fmodule%2Fopenidconnect.login">
<img src="/image/mojeid_tlacitko_Prihlasit_0X.svg" width=70%></a>
</li>
{% endif %}

Důležité

Pokud jste již v šabloně dělali změny, číslo řádku se může lišit. Kód vložte do třídy list-unstyled a ujistěte se, že jej nevkládáte do jiné položky této třídy. Těsně před Vámi vloženým kódem musí být html tag </li>.

Poznámka

Příklad ilustruje implementaci tlačítka s českým nápisem. Pokud chcete použít tlačítko s anglickým nápisem, upravte odpovídajícím způsobem cestu zdroje obrázku.

4.1.1.5. MojeID plugin pro Drupal

Důležité

Níže uvedený návod ještě dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s ním.

4.1.1.5.1. Instalace rozšíření
  1. Pomocí PHP composeru nainstalujte OpenID Connect plugin. Řiďte se přitom verzí PHP a Drupalu. Pro instalaci s Drupalem 10 a PHP 8.1 spusťte v kořenovém adresáři Drupalu příkaz composer require 'drupal/openid_connect:^3.0@alpha'. Pro jiné verze zvolte odpovídající příkaz na stránce pluginu.

  2. V administraci Dupalu přejděte do sekce Nastavení a v kategorii Uživatelé zvolte OpenID Connect.

    Testovací instalace

    Klikněte na tlačítko + Generic OAuth 2.0 a nastavte jméno služby, doporučujeme MojeID.

    Produkční instalace

    Pokud chcete pro svoji službu použít přednastavený scope informací, které budou po uživateli požadovány, klikněte na tlačítko + MojeID a nastavte jméno služby, doporučujeme MojeID. Při konfiguraci pak postupujte dle sekce Přednastavená konfigurace. Přednastaveny jsou hodnoty openid profile email.

    Pokud chcete zvolit svůj vlastní scope, zvolte + Generic OAuth 2.0, nastavte jméno služby a během konfigurace postupujte dle sekce Pokročilá konfigurace.

  3. Jméno potvrďte stisknutím klávesy Enter nebo kliknutím do prázdného místa na stránce.

  4. Poznamenejte si řetězec Redirect URL, který naleznete vespodu stránky. Záložku s Drupalem nezavírejte.

4.1.1.5.2. Registrace služby do MojeID

Pokud registrujete testovací službu, přejděte na sekci Registrace testovací služby. Pokud registrujete službu jdoucí do produkce, přejděte na sekci Registrace produkční služby.

4.1.1.5.2.1. Registrace testovací služby

Více informací o testovací instanci MojeID lze najít v sekci Testovací instance MojeID.

  1. Jděte na úvodní stránku veřejné testovací instance MojeID a za pomoci přítomného návodu si založte testovací účet.

  2. Na nástěnce účtu klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta a do položky Seznam URI pro přesměrování vložte řetězec adresy Redirect URL z posledního kroku instalace rozšíření do PrestaShopu.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Základní HTTP autentifikace a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

  6. Dále postupujte dle Konfigurace rozšíření.

4.1.1.5.2.2. Registrace produkční služby
  1. Založte si MojeID účet.

  2. Na nástěnce účtu klikněte na tlačítko Založení nové služby.

  3. Vyplňte položku Název klienta a do položky Seznam URI pro přesměrování vložte řetězec adresy Redirect URL z posledního kroku instalace rozšíření do PrestaShopu.

  4. V rozbalovací nabídce položky Přihlašovací metoda pro token endpoint vyberte Základní HTTP autentifikace a do políčka Požadované typy odpovědí vepište code. Následně klikněte na tlačítko Uložit.

  5. Poznamenejte si řetězec znaků v poli ID klienta u služby, kterou jste právě vytvořili. Dále u služby klikněte na tlačítko Aktualizovat a poznamenejte si hodnotu položky Tajemství klienta.

4.1.1.5.3. Konfigurace rozšíření

V otevřené záložce nastavení OpenID Connect vyplňte ID klienta, které jste získali během registrace služby, do pole Client ID a tajemství klienta do pole Client secret.

Pokud testujete funkčnost služby, postupujte podle návodu Testovací konfigurace. Pokud zavádíte již otestovanou službu, postupujte dle Přednastavená konfigurace, nebo dle Pokročilá konfigurace.

4.1.1.5.3.1. Testovací konfigurace
  1. Vyplňte adresy endpointů:

    • 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/

  2. Vyplňte položku OpenID Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  3. Nastavení potvrďte tlačítkem Create OpenID Connect client.

4.1.1.5.3.2. Přednastavená konfigurace

Pokud jste vybrali možnost + MojeID a vyplnili jste položky Client ID a Client secret, není již potřeba žádná konfigurace, nastavení pouze potvrďte tlačítkem Create OpenID Connect client.

4.1.1.5.3.3. Pokročilá konfigurace

Pokud chcete nastavit jiný scope informací, které budou po uživateli požadovány, než je přednastaven v MojeID přihlášení, postupujte následovně:

  1. Vyplňte adresy endpointů:

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

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

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

  2. Vyplňte položku OpenID Scope v závislosti na tom, které informace po uživateli požadujete. Povinná je kategorie openid, pro přihlašování doporučujeme požadovat také email. Dalšími možnostmi jsou profile phone address, pro více informací navštivte dokumentaci OpenID Connect a Příloha č. 1 – Seznam údajů pro předání (OpenID Connect).

  3. Nastavení potvrďte tlačítkem Create OpenID Connect client.

4.1.1.5.4. Umístění tlačítka pro přihlášení
  1. V administraci Drupalu vstupte do kategorie Struktura > Umístění bloků. Zde si zvolte umístění tlačítka pro přihlášení.

  2. U příslušného umístění klikněte na tlačítko Umístěte blok, zvolte OpenID Connect client a klikněte na Umístit blok. Jako nadpis zvolte Přihlásit přes MojeID a nastavení uložte.

  3. Vespodu stránky klikněte na tlačítko Uložit bloky.

4.1.1.6. Přihlášení k MojeID pomocí PHP klienta

Návod obsahuje postup instalace pluginu pro přihlášení k MojeID pomocí PHP klienta a příklad použití.

4.1.1.6.1. Prerekvizity

Než budete moci pokračovat, je třeba provést následující:

4.1.1.6.2. Instalace
  1. Ve složce s pluginem php-mojeid-oidc spusťte následující příkazy:

    cd php
    composer install
    
    # vytvoření konfiguračního souboru pro konkrétní službu
    cp config.{template,local}.php
    
    # spuštění webového serveru
    sudo docker compose -f ../docker/docker-compose.yml up
    
  2. Proveďte ruční registraci klienta MojeID.

    • Do seznamu URI je třeba vyplnit URI, přes kterou Váš webový prohlížeč přistupuje k PHP aplikaci (složce php z tohoto příkladu). Při použití přiloženého dockerového řešení na vlastním počítači lze zadat https://localhost:8443/.

      • Adresu, se kterou webový server pracuje, můžete zjistit z metody OpenIDConnectClient::getRedirectURL().

      • Pokud neodpovídá tomu, co potřebujete, nastavte správnou adresu metodou OpenIDConnectClient::setRedirectURL().

  3. V souboru config.local.php vyplňte požadované údaje:

    • OPEN_ID_PROVIDER_URL je základní URL služby, ke které se chcete připojit

    • OPEN_ID_CLIENT_ID je ID klienta ze stránky https://mojeid.regtest.nic.cz/consumer_admin/

    • OPEN_ID_CLIENT_SECRET je Tajemství klienta ze stránky s podrobnostmi dané služby

      • na výše uvedené stránce přejděte v příslušném řádku na odkaz Aktualizovat

4.1.1.6.3. Použití
  1. Navštivte webovou stránku ukázky (https://localhost:8443/).

  2. Po případném potvrzení certifikátu s vlastním podpisem budete přesměrováni na přihlašovací stránku MojeID.

  3. Po prvním přihlášení budete vyzváni k souhlasu s předáním údajů.

  4. Po potvrzení budete přesměrováni zpět na stránku naší aplikace, kde uvidíte křestní jméno zadaného uživatele (pokud jste udělili příslušný souhlas).

Důležité

Uvedené moduly dále testujeme. Budeme rádi, pokud se s námi podělíte o svoje zkušenosti s nimi.

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.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).

Pozor: automatickou (dynamickou) registraci nelze využít pro Plný přístup.

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. Pozor: automatickou (dynamickou) registraci nelze využít pro Plný přístup.

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

http://eidas.europa.eu/LoA/substantial

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

http://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í 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.2.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

http://eidas.europa.eu/LoA/substantial

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

http://eidas.europa.eu/LoA/high

eIDAS úroveň záruky „vysoká“

Příklad použití:

<saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    http://eidas.europa.eu/LoA/substantial
</saml:AuthnContextClassRef>

4.3. 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.3.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.3.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.3.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.3.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 zadáním ověřovacích kódů zaslaných na e-mail a telefonní číslo.

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 (ověření e-mailu a telefonu) a identifikaci (zadán PIN3, pouze do roku 2024) 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 ověření e-mailové adresy a telefonního čísla 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ý.
      • Účet s ověřeným e-mailem a telefonním číslem.

      • U účtů do roku 2024 zadán PIN1 a PIN2.

    • IDENTIFIED – identifikovaný (zadán PIN1, PIN2 a PIN3 [1]).
      • Pouze u účtů do roku 2024.

    • VALIDATED – validovaný (účet s příznakem validace).
      • Validovaný účet právnické osoby nebo účet fyzické osoby napojený na systémy veřejné správy (NIA).

      • U účtů do roku 2024 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.

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.

Důležité

Od roku 2024 se PIN1, PIN2 a PIN3 pro ověření nepoužívají.

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í. K založení účtů využijte návod na úvodní stránce veřejné testovací instance MojeID. Kontaktní a osobní údaje můžete vyplnit libovolné.

  • Částečně identifikovaný účet:
    • Účet s ověřeným e-mailem a telefonním číslem.

  • Účet fyzické osoby napojený na služby veřejné správy:
    • Pro napojení testovacího účtu na služby veřejné správy budete potřebovat certifikovaný fyzický nebo systémový bezpečnostní klíč.

    • Založte účet fyzické osoby.

    • Klikněte na Ověřit totožnost, poté na Ověřit se jinak a vyberte Testovací profily (LoA High jako eObčanka).

    • Zvolte si libovolný testovací profil a dokončete ověření.

  • Účet právnické osoby s validací:
    • Založte účet právnické osoby.

    • Přejděte do záložky s osobními údaji a klikněte na tlačítko Validovat.

    • Stáhněte vygenerovaný PDF dokument a zašlete ho na adresu techsupport@mojeid.cz.

    • Účtu nastavíme příznak validace.

Tím je možné otestovat vracené hodnoty v parametru status pro všechny současné varianty ověření účtu.

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. 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

Organizace

mojeid_organization

SINGLE_OPTIONAL_STRING

DIČ

mojeid_vat

SINGLE_OPTIONAL_STRING

IČO

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 č. 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.3. 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.4. 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.5. 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.5.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. 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.5.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é realm.

8.5.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ý lze získat např. zde: https://letsencrypt.org/. Certifikát Vám zabezpečí chráněný přenos dat a současně vidíte, jakou úroveň ověření uživatel má.

8.5.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 implem-oid2-zadost-overeni.

8.5.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.5.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.6. 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 implem-oid-zadost-prihlaseni.

_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.1.3

Přihlášení k MojeID pomocí PHP klienta

Přidán plugin pro ukázkové přihlášení k MojeID pomocí PHP klienta

3.1.2

Kontrola validity dat
Dokončení registrace
Testovací instance MojeID
Přehled knihoven a modulů

Úpavy dokumentace kvůli zrušení ověřování pomocí PIN1 a PIN2

3.1.1

Žádost o ověření identity účtem napojeným na NIA
Implementace pomocí SAML

Oprava hodnot acr_values a AuthnContextClassRef včetně příkladu použití

MojeID plugin pro WordPress

Aktualizace návodu pro přihlášení účtem napojeným na NIA

3.1

Celá dokumentace

Odstraněny všechny části dokumentace o protokolu OpenID 2.0

3.0.9

Přehled knihoven a modulů

Přidány návody na instalaci rozšíření pro populární platformy (pouze CS verze dokumentace)

3.0.8

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

Doplněn předávaný údaj „Organizace“ u OIDC
Opraveny prohozené pojmy DIČ a IČO

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

Změněn odkaz u SSL certifikátu na certifikační službu Let’s Encrypt

Registrace klienta
Knihovna MojeID LITE

Doplněna poznámka, že automatickou (dynamickou) registraci nelze využít pro plný přístup

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)
/Prilohy/UdajePredaniOID/index
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

/SeznameniSMojeid/ProcesKomunikacePresMojeid/OpenID/index
Favikona
/ImplementacePodporyMojeid/Openid/index a všechny podkapitoly
Testovací instance MojeID
/Prilohy/UdajePredaniOID/index

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)
/Prilohy/UdajePredaniOID/index
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

/ImplementacePodporyMojeid/Openid/ZadostOOvereniIdentity/index
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
/SeznameniSMojeid/ProcesKomunikacePresMojeid/OpenID/index

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)
/Prilohy/UdajePredaniOID/index
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)
/Prilohy/UdajePredaniOID/index

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)
/Prilohy/UdajePredaniOID/index
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

/ImplementacePodporyMojeid/Openid/KnihovnyModuly

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í

/ImplementacePodporyMojeid/Openid/ProvedeniAutentizace/index

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

/Prilohy/UdajePredaniOID/index
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 /ImplementacePodporyMojeid/Openid/indexImplementace 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