Zobrazení zdroje stránky Registrace aplikace iFIS-ePodatelna na platformě Microsoft identity

== '''Předpoklady''' ==
* Účet Azure, který má aktivní předplatné.
* Účet Azure musí mít oprávnění ke správě aplikací v Azure Active Directory (Azure AD). Kterákoli z následujících rolí Azure AD zahrnuje požadovaná oprávnění:
** Správce aplikace
** Vývojář aplikací
** Správce cloudových aplikací

== '''Zaregistrujte aplikaci''' ==
# Přihlaste se k Azure Portal.
# Pokud máte přístup k více tenantům, pomocí filtru '''Adresáře + odběry''' v horním menu se přepněte na tenanta, do kterého chcete aplikaci zaregistrovat.
# Vyhledejte a vyberte '''Azure Active Directory''' .
# V části '''Spravovat''' vyberte '''Registrace aplikací''' &gt; '''Nová registrace''' .
# Zadejte zobrazovaný název '''iFIS-ePodatelna'''. Zobrazovaný název můžete kdykoli změnit a stejný název může sdílet několik registrací aplikací. Automaticky vygenerované ID aplikace (klienta) jednoznačně identifikuje aplikaci v rámci Azure AD, nikoli její zobrazovaný název.
# U volby, kdo může používat aplikaci, nastavte volbu '''Účty pouze v tomto organizačním adresáři'''.
# Do pole URI přesměrování nic '''nezadávejte''' (volitelné).
# Vyberte '''Registrovat''' pro dokončení úvodní registrace aplikace.

[[Soubor:E-pod azure1.png|604x604pixelů]]

Po dokončení registrace Azure Portal zobrazí podokno '''Přehled registrace aplikace''' s '''ID aplikace (klienta)'''. Tuto hodnotu si poznamenejte, bude jí potřebovat aplikace ePodatelny pro připojení. Pro jistotu připojte i '''ID adresáře (tenanta).'''

[[Soubor:E-pod azure2.png|604x604pixelů]]

== '''Přidejte přihlašovací údaje aplikace''' ==
iFIS-ePodatelna je aplikace typu démon běžící na aplikačním serveru a v jejím případě použijeme přihlašovací údaje umožňující aplikaci autentizovat se jako sama sebe, aniž by za běhu vyžadovala interakci od uživatele.

K registraci důvěrné klientské aplikace použijeme tajný kód klienta (řetězec) jako přihlašovací údaj.

[[Soubor:E-pod azure3.png|604x604pixelů]]

=== '''Tajný kód klienta''' ===
Tajemství klienta, které se někdy nazývá ''heslo aplikace'' , je řetězcová hodnota, kterou aplikace používá k identifikaci.

# V části '''Správa''' vyberte '''Certifikáty a tajné kódy''' &gt; '''Tajné kódy klienta''' &gt; '''Nový tajný kód klienta'''.
# Přidejte popis tajného klíče klienta, např. '''Klíč 1'''.
# Vyberte vypršení platnosti tajného klíče nebo zadejte vlastní životnost, doporučujeme 24 měsíců.
# Vyberte '''Přidat'''.
# '''''Zaznamenejte hodnotu tajného kódu''''', bude jí potřebovat aplikace ePodatelny pro připojení.
{{Pozor|Tato tajná hodnota se po opuštění této stránky již nikdy nezobrazí.}}{{Poznamka|Microsoft doporučuje dobu platnosti klíče menší než 12 měsíců, nicméně ePodatelna platnosti klíče nekontroluje, ani nemůže, a po skončení platnosti klíče přestane fungovat. Proto musí exspiraci klíče hlídat administrátor, který včas zajistí vygenerování nového klíče a jeho nastavení v aplikaci.}}

[[Soubor:E-pod azure4.png|604x604pixelů]]

== '''Nastavte Oprávnění rozhraní API''' ==
iFIS-ePodatelna potřebuje přistupovat k rozhraní IMAP aplikace Office 365 Exchange Online, takže je potřeba nastavit příslušná oprávnění k API.<br />Stejná oprávnění je třeba definovat také pro protokol SMTP, pokud bude ePodatelna odesílat odpovědi na e-maily prostřednictvím Office 365 Exchange Online, a nikoliv přes lokální poštovní server.
{{Poznamka|POZN.: Pokud Azure AD přiřadil zaregistrované aplikaci ePodatelny nějaká výchozí oprávnění k jiným API, tak je předem odeberte.}}<ol style="list-style-type: decimal;">
<li><p>V části '''Správa''' vyberte '''Oprávnění rozhraní API''' &gt; '''Přidat oprávnění''' &gt; '''Rozhraní API, která používá moje organizace'''.</p></li>
<li><p>Do dotazovacího pole napište ''Office 365'' a vyberte položku '''Office 365 Exchange Online'''.</p></li>
<li><p>Zvolte typ oprávnění '''Oprávnění aplikace''' a zaškrtněte volby u oprávnění:</p>
<ul>
<li><p>IMAP</p>
<ul>
<li><p>IMAP.AccessAsApp</p></li>
<li><p>Mail.ReadWrite</p></li>
<li><p>Mail.Send</p></li></ul>
</li></ul>

<ul>
<li><p>SMTP</p>
<ul>
<li><p>SMTP.SendAsApp</p></li></ul>
</li></ul>
</li>
<li><p>Vyberte '''Přidat oprávnění'''.</p></li></ol>

[[Soubor:E-pod azure5.png|604x604pixelů]]

Nyní je potřeba ještě udělit souhlas správce pro váš tenant.

[[Soubor:E-pod azure6.png]]

== '''Delegujte oprávnění ke schránce''' ==
Bohužel tuto část oprávnění nelze nastavit v prostředí administrace Office 365 Exchange a je nutné jí provést prostřednictvím Exchange Online PowerShell. Lze provést i vzdáleně z PowerShell na PC.

=== '''Předpoklady''' ===
Nejprve si zjistěte potřebná ID z portálu Azure AD, pro:

* '''APPLICATION_ID''': Registrace aplikací &gt; iFIS-ePodatelna &gt; Základní údaje &gt; ID aplikace (klienta)
* '''ORGANIZATION_ID''': Registrace aplikací &gt; iFIS-ePodatelna &gt; Základní údaje &gt; ID adresáře (tenanta)
* '''OBJECT_ID''': Podnikové aplikace &gt; iFIS-ePodatelna &gt; ID objektu
{{Pozor|OBJECT_ID je ID objektu ze stránky Přehled uzlu Enterprise Application (Podnikové aplikace) pro aplikaci ePodatelny. Není to ID objektu z Přehledu uzlu Registrace aplikací. Použití nesprávného ID objektu způsobí nefunkčnost ověřování a přístupu do schánky.}}

Pro použití Cmdlet New-ServicePrincipal, nejprve nainstalujte ExchangeOnlineManagement a připojte se ke svému tenantovi, jak je znázorněno v následujícím příkladu:<syntaxhighlight lang="powershell">
Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <ORGANIZATION_ID>
</syntaxhighlight>Pokud se při spuštění Cmdlet New-ServicePrincipal stále zobrazuje chyba i po provedení těchto kroků, je to pravděpodobné, že uživatel nemá dostatečná oprávnění na serveru Exchange Online k provedení operace.

Registrace aplikace ePodatelny jako služby Azure AD do Exchange:<syntaxhighlight lang="powershell">
New-ServicePrincipal -AppId <APPLICATION_ID> -ServiceId <OBJECT_ID> -DisplayName ePodatelna [-Organization <ORGANIZATION_ID>]
</syntaxhighlight>Identifikátor SERVICE_PRINCIPAL_ID = ID registrované služby můžete získat pomocí Get-ServicePrincipal:<syntaxhighlight lang="powershell">
Get-ServicePrincipal [-Organization <ORGANIZATION_ID>] | Select-Object -Property DisplayName,AppId,Id | fl
</syntaxhighlight>Nyní přidáme oprávnění ke konkrétní poštovní schránce, kterou je implementována funkce ePodatelny:<syntaxhighlight lang="powershell">
Add-MailboxPermission -Identity "epodatelna@your_domain.cz" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess
</syntaxhighlight>

== '''Povolte SMTP AUTH ke schránce ePodatelny''' ==
Aby bylo možné odesílat zprávy z poštovní schránky ePodatelny, je nutné povolení SMTP AUTH v prostředí Microsoft 365 admin center.

Postupujte takto:

# Otevřete [https://admin.microsoft.com/ Centrum pro správu Microsoft 365] a přejděte do části '''Uživatelé''' &gt; '''Aktivní uživatelé''' .
# Vyhledejte a vyberte uživatele ePodatelny v nabídce a klikněte na '''Pošta'''.
# V části '''E-mailové aplikace''' klikněte na '''Spravovat e-mailové aplikace'''.
# Zaškrtněte v nastavení '''SMTP s ověřením'''.
# Až budete hotovi, klikněte na '''Uložit změny'''.

[[Soubor:E-pod azure7.png|604x604pixelů|Obsah obrázku text, snímek obrazovky, software, Počítačová ikona Obsah generovaný pomocí AI může být nesprávný.]]<syntaxhighlight lang="powershell">
Set-CASMailbox -Identity "epodatelna@your_domain.cz" -SmtpClientAuthenticationDisabled $false
</syntaxhighlight>

== '''Otestování přístupu''' ==
Otestování je možné provést pomocí PowerShell skriptu, viz [https://translate.google.com/website?sl=auto&tl=cs&hl=cs&u=https://github.com/DanijelkMSFT/ThisandThat/blob/main/Get-IMAPAccessToken.ps1 Testování IMAP OAuth pomocí skriptu powershell].

Předem nainstalujte knihovny MSAL.PS, PowerShell se musí spustit jako správce:<syntaxhighlight lang="powershell">
Set-ExecutionPolicy RemoteSigned
Install-Module -Name MSAL.PS
</syntaxhighlight>Pomocí výše uvedeného odkazu GitHubu stáhněte soubor Get-IMAPAccessToken.ps1, který obsahuje testovací skript, ten umístěte do pracovního adresáře. Nezapomeňte odblokovat zabezpečení proti spuštění ve vlastnostech souboru.

Pak můžete provést test podle následujícího příkladu:<syntaxhighlight lang="powershell">
Get-IMAPAccessToken.ps1 -tenantID "your_domain.cz" -clientId <APPLICATION_ID> -clientsecret "<tajný_kód_klienta>" -targetMailbox "epodatelna@your_domain.cz"
</syntaxhighlight>Pokud je vše v pořádku, skript provede autentizaci pomocí OAuth a vypíše seznam došlé pošty do ePodatelny. Je možné, že bude přechodně hlásit chybu, že nemá přístup ke schránce, pak vyčkejte cca 10 minut, než se vše promítne v Azure AD a Exchange Online.

== '''Předání informací pro nastavení ePodatelny''' ==
Pro potřeby nastavení aplikace ePodatelny potřebujeme následující informace:

* '''APPLICATION_ID''': Registrace aplikací &gt; iFIS-ePodatelna &gt; Základní údaje &gt; ID aplikace (klienta)
* '''ORGANIZATION_ID''': Registrace aplikací &gt; iFIS-ePodatelna &gt; Základní údaje &gt; ID adresáře (tenanta)
* '''Tajný kód klienta''': Registrace aplikací &gt; Certifikáty a tajné kódy &gt; Tajné kódy klienta &gt; Nový tajný kód klienta
* '''Identifikaci tenenta:''' textový řetězec, který obvykle odpovídá vaší doméně.
* '''Cílový mailbox:''' adresa mail schránky vaší ePodatelny.
[[Kategorie:E-podatelna]]