Zobrazení zdroje stránky Nastavení OAuth 2.0 pro odesílání e-mailů

'''Nastavení OAuth 2.0 pro odesílání e-mailů''' - součást agendy

* [[Testování E-mailové komunikace]]

Pro odesílání e-mailů je možno použít OAuth 2.0 autentizaci prostřednictvím služeb Microsoft 365 nebo Google Workspace.

Podporovány jsou následující varianty:

{| class="wikitable"
! Hodnota
! Prostředí
! Způsob odesílání
! Autentizace
|-
| '''Ne'''
| libovolné
| klasické SMTP
| bez OAuth 2.0
|-
| '''MS_SMTP'''
| Microsoft 365
| SMTP
| OAuth 2.0, Client Credentials
|-
| '''GMail_SMTP'''
| Google Workspace
| SMTP
| Service Account + Domain-Wide Delegation
|-
| '''MS_Graph_API'''
| Microsoft 365
| Microsoft Graph API
| OAuth 2.0, Client Credentials
|-
| '''GMail_API'''
| Google Workspace
| Gmail API
| Service Account + Domain-Wide Delegation
|}

Ve všech uvedených OAuth variantách je prvotní konfigurace provedena administrátorem organizace. Při následném běžném odesílání e-mailů již není vyžadováno přihlášení ani jiná interakce uživatele.

Pro nové instalace je doporučeno přednostně používat API varianty:

* Microsoft 365 - '''MS_Graph_API'''
* Google Workspace - '''GMail_API'''

SMTP varianty jsou určeny zejména pro prostředí, kde je z technických nebo provozních důvodů požadováno odesílání prostřednictvím SMTP.

Nastavení je možno ověřit pomocí [[Testování E-mailové komunikace|testování E-mailové komunikace]].


== Email KSPortálu a Email Uživatel ==

Při konfiguraci odesílání e-mailů je potřeba rozlišovat adresu odesílatele zprávy a technický účet/mailbox použitý pro její odeslání.

{| class="wikitable"
! Parametr
! Význam
! Příklad
|-
| '''[[Email KSPortálu]]'''
| E-mailová adresa použitá v odesílané zprávě jako odesílatel (From). Je možno uvést také zobrazované jméno ve formátu ''email,zobrazované jméno''.
| noreply@firma.cz,KS Portál
|-
| '''[[Email Uživatel]]'''
| Technický účet/mailbox použitý pro autentizaci nebo pro určení mailboxu, jehož prostřednictvím se zpráva odešle.
| mailer@firma.cz
|}

Pokud parametr '''Email Uživatel''' není vyplněn, použije se jako technický účet/mailbox e-mailová adresa z parametru '''Email KSPortálu'''.

Je tedy možné použít stejnou adresu pro odesílatele i technický účet:

 Email KSPortálu = mailer@firma.cz,KS Portál
 Email Uživatel  = mailer@firma.cz

nebo tyto adresy oddělit:

 Email KSPortálu = noreply@firma.cz,KS Portál
 Email Uživatel  = mailer@firma.cz

V druhém případě obsahuje odesílaná zpráva jako odesílatele:

 KS Portál <noreply@firma.cz>

zatímco jako technický účet/mailbox se použije:

 mailer@firma.cz

'''Upozornění:''' Pokud se adresa v parametru '''Email KSPortálu''' liší od technického účtu v parametru '''Email Uživatel''', musí být v prostředí Microsoft 365 nebo Google Workspace odpovídajícím způsobem povoleno odesílání za tuto adresu (např. Send As nebo povolený alias).


== Microsoft 365 - SMTP OAuth 2.0 (MS_SMTP) ==

Tato varianta používá standardní SMTP službu Microsoft Exchange Online. Místo hesla uživatele se aplikace autentizuje pomocí OAuth 2.0.

Standardní nastavení:

* SMTP server: '''smtp.office365.com'''
* Port: '''587'''
* Zabezpečení: '''STARTTLS'''

Aplikace získává OAuth access token pomocí Client Credentials Flow, tedy bez přihlášení uživatele.


=== Vytvoření aplikace v Microsoft Entra ID ===

# Přihlaste se do Microsoft Entra admin center.
# Otevřete '''Identity > Applications > App registrations'''.
# Zvolte '''New registration'''.
# Zadejte název aplikace, například '''KS Mail OAuth'''.
# Pro aplikaci používanou pouze v jedné organizaci zvolte '''Accounts in this organizational directory only'''.
# Vytvořte aplikaci.

Po vytvoření aplikace si z obrazovky '''Overview''' poznamenejte:

* '''Application (client) ID'''
* '''Directory (tenant) ID'''


=== Vytvoření Client Secret ===

# V registraci aplikace otevřete '''Certificates & secrets > Client secrets'''.
# Zvolte '''New client secret'''.
# Zadejte popis a požadovanou dobu platnosti.
# Vytvořte Client Secret.
# Hodnotu '''Value''' bezpečně uložte.

'''Pozor:''' Hodnota Client Secret se po opuštění stránky již nemusí znovu zobrazit.

Pro konfiguraci aplikace budou potřeba následující hodnoty:

* Client ID
* Client Secret
* Tenant ID


=== Přidání oprávnění pro SMTP ===

# V registraci aplikace otevřete '''API permissions > Add a permission'''.
# Zvolte '''APIs my organization uses'''.
# Vyhledejte '''Office 365 Exchange Online'''.
# Zvolte '''Application permissions'''.
# Přidejte oprávnění '''SMTP.SendAsApp'''.
# Administrátor následně provede '''Grant admin consent for <organizace>'''.

Bez administrátorského souhlasu nebude app-only SMTP autentizace fungovat.


=== Registrace aplikace v Exchange Online ===

Samotná registrace aplikace v Microsoft Entra ID nestačí. Service Principal aplikace je nutné zaregistrovat také v Exchange Online.

Spusťte Exchange Online PowerShell:

 Install-Module ExchangeOnlineManagement
 Import-Module ExchangeOnlineManagement
 Connect-ExchangeOnline

Následně vytvořte Exchange Service Principal:

 New-ServicePrincipal -AppId <APPLICATION_CLIENT_ID> -ObjectId <ENTERPRISE_APPLICATION_OBJECT_ID> -DisplayName "KS Mail OAuth"

'''Pozor:''' Parametr ObjectId musí obsahovat Object ID objektu '''Enterprise Application / Service Principal''', nikoliv Object ID registrace aplikace.

Správnou hodnotu naleznete v:

 Microsoft Entra > Enterprise applications > vaše aplikace > Overview > Object ID


=== Povolení požadované schránky ===

Aplikaci je nutné povolit přístup ke schránce, která bude použita jako technický mailbox, například:

 mailer@firma.cz

Identitu Exchange Service Principal lze zjistit příkazem:

 Get-ServicePrincipal | Format-List

Následně nastavte potřebné oprávnění k požadované schránce podle bezpečnostní politiky organizace.

Pokud je '''Email KSPortálu''' odlišný od '''Email Uživatel''', musí být současně povoleno odesílání za adresu uvedenou v parametru '''Email KSPortálu'''.

Pro přesnější omezení aplikace na vybrané mailboxy lze použít také Exchange Application RBAC.


=== Nastavení aplikace ===

Nastavte následující hodnoty:

{| class="wikitable"
! Parametr
! Hodnota / příklad
! Význam
|-
| [[Email OAuth]]
| '''MS_SMTP'''
| Microsoft 365 SMTP s OAuth 2.0
|-
| [[Email KSPortálu]]
| noreply@firma.cz,KS Portál
| Adresa odesílatele zprávy (From)
|-
| [[Email Uživatel]]
| mailer@firma.cz
| Technický účet použitý pro SMTP XOAUTH2 autentizaci
|-
| [[Email SMTP]]
| smtp.office365.com,587
| SMTP server a port
|-
| [[Email OAuth ClientId]]
| Application (client) ID
| ID aplikace v Microsoft Entra
|-
| [[Email OAuth ClientSecret]]
| Client Secret
| Tajný klíč aplikace
|-
| [[Email OAuth TenantId]]
| Directory (tenant) ID
| ID adresáře Microsoft Entra
|-
| [[Email OAuth Scopes]]
| https://outlook.office365.com/.default
| OAuth scope pro Exchange Online
|-
| [[Email SSL Options]]
| StartTls
| Zabezpečení SMTP spojení
|}

Pokud '''Email Uživatel''' není zadán, použije se pro SMTP OAuth autentizaci e-mailová adresa z parametru '''Email KSPortálu'''.


== Microsoft 365 - Microsoft Graph API (MS_Graph_API) ==

Toto je doporučená varianta pro nové instalace používající Microsoft 365.

SMTP se v tomto případě nepoužívá. Aplikace získá OAuth 2.0 access token a e-mail odešle prostřednictvím Microsoft Graph API.

Používá se operace:

 POST /v1.0/users/{mailbox}/sendMail

Autentizace probíhá pomocí Client Credentials Flow, takže není potřeba přihlášení uživatele.

Hodnota `{mailbox}` je určena parametrem '''Email Uživatel'''. Pokud není parametr vyplněn, použije se adresa z parametru '''Email KSPortálu'''.


=== Registrace aplikace ===

V Microsoft Entra ID vytvořte App Registration stejným způsobem jako u varianty '''MS_SMTP'''.

Budou potřeba:

* Client ID
* Client Secret
* Tenant ID

Pokud již pro aplikaci existuje vhodná App Registration, není nutné vytvářet další.


=== Přidání oprávnění Microsoft Graph ===

# Otevřete '''App registrations > vaše aplikace > API permissions > Add a permission'''.
# Zvolte '''Microsoft Graph'''.
# Zvolte '''Application permissions'''.
# Vyhledejte a přidejte '''Mail.Send'''.
# Proveďte '''Grant admin consent for <organizace>'''.

Oprávnění '''Mail.Send''' typu Application umožňuje aplikaci odesílat e-maily bez přihlášeného uživatele.


=== Omezení na konkrétní schránky ===

Oprávnění '''Mail.Send''' je silné oprávnění. Doporučuje se proto aplikaci omezit pouze na mailboxy, které skutečně potřebuje používat.

Pro nové konfigurace lze použít '''Exchange Application RBAC''' a oprávnění '''Application Mail.Send''' společně s odpovídajícím Management Scope.

Tím lze například povolit aplikaci přístup pouze k technickému mailboxu:

 mailer@firma.cz

Pokud se adresa '''Email KSPortálu''' liší od technického mailboxu '''Email Uživatel''', musí konfigurace Microsoft 365 umožňovat odesílání zpráv s požadovanou adresou odesílatele.


=== Nastavení aplikace ===

{| class="wikitable"
! Parametr
! Hodnota / příklad
! Význam
|-
| [[Email OAuth]]
| '''MS_Graph_API'''
| Odesílání prostřednictvím Microsoft Graph API
|-
| [[Email KSPortálu]]
| noreply@firma.cz,KS Portál
| Adresa odesílatele zprávy (From)
|-
| [[Email Uživatel]]
| mailer@firma.cz
| Technický mailbox použitý v /users/{mailbox}/sendMail
|-
| [[Email OAuth ClientId]]
| Application (client) ID
| ID aplikace v Microsoft Entra
|-
| [[Email OAuth ClientSecret]]
| Client Secret
| Tajný klíč aplikace
|-
| [[Email OAuth TenantId]]
| Directory (tenant) ID
| ID adresáře Microsoft Entra
|-
| [[Email OAuth Scopes]]
| https://graph.microsoft.com/.default
| OAuth scope pro Microsoft Graph
|}

Parametry '''Email SMTP''', '''Email SSL Options''' a '''Email EnableSSL''' se při této variantě nepoužívají.

Pokud '''Email Uživatel''' není zadán, použije se jako technický mailbox e-mailová adresa z parametru '''Email KSPortálu'''.

Příklad:

 Email KSPortálu = noreply@firma.cz,KS Portál
 Email Uživatel  = mailer@firma.cz

vede k použití endpointu:

 /users/mailer@firma.cz/sendMail

zatímco odesílaná MIME zpráva obsahuje:

 From: KS Portál <noreply@firma.cz>


== Google Workspace - SMTP OAuth 2.0 (GMail_SMTP) ==

Tato varianta používá Gmail SMTP:

* SMTP server: '''smtp.gmail.com'''
* Port: '''587'''
* Zabezpečení: '''STARTTLS'''

Aplikace nepoužívá heslo uživatele.

Pro bezobslužnou autentizaci se používá:

'''Google Service Account + Domain-Wide Delegation'''

Service Account se při získávání OAuth tokenu vydává za konkrétního uživatele Google Workspace.

Tento uživatel je určen parametrem '''Email Uživatel'''. Pokud parametr není vyplněn, použije se adresa z parametru '''Email KSPortálu'''.

'''Poznámka:''' Tato bezobslužná varianta je určena pro organizace používající Google Workspace. Není určena pro běžné osobní účty @gmail.com.


=== Vytvoření Google Cloud projektu ===

# Přihlaste se do Google Cloud Console.
# Vytvořte nový projekt, například '''KS Mail OAuth''', nebo použijte vhodný existující projekt organizace.


=== Vytvoření Service Account ===

# Otevřete '''IAM & Admin > Service Accounts'''.
# Zvolte '''Create service account'''.
# Zadejte například název '''KS Mail Service'''.
# Vytvořte Service Account.

Service Account získá adresu například:

 ks-mail-service@nazev-projektu.iam.gserviceaccount.com

Service Account není e-mailová schránka. Jde o identitu aplikace, která bude oprávněna jednat jménem konkrétního uživatele Google Workspace.


=== Vytvoření privátního klíče ===

# Otevřete vytvořený Service Account.
# Zvolte '''Keys > Add key > Create new key'''.
# Vyberte typ '''JSON'''.
# Stažený soubor bezpečně uložte.

JSON obsahuje mimo jiné:

* '''client_email'''
* '''client_id'''
* '''private_key'''

Pro nastavení KS portálu jsou důležité zejména:

* hodnota '''client_email''' - zadává se do parametru '''Email OAuth ClientId''',
* hodnota '''private_key''' - zadává se do parametru '''Email OAuth ClientSecret'''.

'''Pozor:''' Název parametru '''Email OAuth ClientId''' je v případě Google pouze společným názvem konfiguračního parametru. U Google se do něj nezadává číselné client_id, ale hodnota '''client_email''' Service Accountu.

Privátní klíč je přihlašovacím údajem aplikace a musí být odpovídajícím způsobem chráněn.


=== Nastavení Domain-Wide Delegation ===

Tento krok musí provést administrátor Google Workspace.

# Otevřete Google Admin Console.
# Přejděte na '''Security > Access and data control > API controls'''.
# Otevřete '''Domain-wide delegation > Manage Domain Wide Delegation'''.
# Zvolte '''Add new'''.
# Do pole '''Client ID''' vložte číselné '''client_id''' Service Accountu ze staženého JSON souboru.
# Pro variantu '''GMail_SMTP''' vložte OAuth scope:

 https://mail.google.com/

# Potvrďte pomocí '''Authorize'''.

Tím administrátor povolí Service Accountu jednat jménem uživatelů organizace v rozsahu uvedeného oprávnění.

'''Pozor:''' Číselné `client_id` používané při nastavení Domain-Wide Delegation není stejná hodnota, která se v KS portálu zadává do parametru '''Email OAuth ClientId'''. V KS portálu je v tomto parametru u Google variant použita hodnota '''client_email'''.


=== Nastavení aplikace ===

{| class="wikitable"
! Parametr
! Hodnota / příklad
! Význam
|-
| [[Email OAuth]]
| '''GMail_SMTP'''
| Google Workspace SMTP s OAuth 2.0
|-
| [[Email KSPortálu]]
| noreply@firma.cz,KS Portál
| Adresa odesílatele zprávy (From)
|-
| [[Email Uživatel]]
| mailer@firma.cz
| Google Workspace účet impersonovaný Service Accountem a použitý pro SMTP XOAUTH2
|-
| [[Email SMTP]]
| smtp.gmail.com,587
| SMTP server a port
|-
| [[Email OAuth ClientId]]
| ks-mail-service@projekt.iam.gserviceaccount.com
| Hodnota '''client_email''' Service Accountu
|-
| [[Email OAuth ClientSecret]]
| -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----
| Hodnota '''private_key''' Service Accountu
|-
| [[Email OAuth TenantId]]
| ''nevyplňuje se''
| Google Workspace tuto hodnotu pro tento způsob autentizace nepoužívá
|-
| [[Email OAuth Scopes]]
| https://mail.google.com/
| OAuth scope pro Gmail SMTP
|-
| [[Email SSL Options]]
| StartTls
| Zabezpečení SMTP spojení
|}

Pokud '''Email Uživatel''' není zadán, použije se jako impersonovaný Google Workspace účet e-mailová adresa z parametru '''Email KSPortálu'''.

Pokud je '''Email KSPortálu''' odlišný od '''Email Uživatel''', musí být v Google Workspace technickému účtu povoleno odesílání za požadovanou adresu, například prostřednictvím odpovídajícího Send As/alias nastavení.


== Google Workspace - Gmail API (GMail_API) ==

Toto je doporučená varianta pro nové instalace používající Google Workspace.

Autentizace funguje stejně jako u varianty '''GMail_SMTP''':

'''Service Account + Domain-Wide Delegation'''

Rozdíl spočívá ve způsobu odeslání zprávy. SMTP se nepoužívá a MIME zpráva je odeslána přímo prostřednictvím Gmail API pomocí operace:

 users.messages.send

Service Account při získávání přístupu impersonuje účet uvedený v parametru '''Email Uživatel'''. Pokud parametr není vyplněn, použije se adresa z parametru '''Email KSPortálu'''.


=== Zapnutí Gmail API ===

# V příslušném Google Cloud projektu otevřete '''APIs & Services > Library'''.
# Vyhledejte '''Gmail API'''.
# Zvolte '''Enable'''.


=== Service Account ===

Vytvořte Service Account a jeho privátní klíč podle postupu uvedeného u varianty '''GMail_SMTP'''.

Stejný Service Account lze použít pro obě Google varianty.

Do parametrů KS portálu se zadávají:

* '''Email OAuth ClientId''' = hodnota '''client_email''' Service Accountu,
* '''Email OAuth ClientSecret''' = hodnota '''private_key''' Service Accountu.


=== Nastavení Domain-Wide Delegation ===

V Google Admin Console otevřete:

 Security > Access and data control > API controls > Domain-wide delegation

Pro variantu '''GMail_API''' povolte scope:

 https://www.googleapis.com/auth/gmail.send

Tento scope umožňuje aplikaci odesílat e-maily a je výrazně užší než:

 https://mail.google.com/

Proto je vhodnější pro aplikace, jejichž účelem je pouze odesílání zpráv.

Do nastavení Domain-Wide Delegation se jako Client ID zadává číselné '''client_id''' Service Accountu.

'''Pozor:''' Do parametru KS portálu '''Email OAuth ClientId''' se naproti tomu zadává hodnota '''client_email''' Service Accountu.


=== Nastavení aplikace ===

{| class="wikitable"
! Parametr
! Hodnota / příklad
! Význam
|-
| [[Email OAuth]]
| '''GMail_API'''
| Odesílání prostřednictvím Gmail API
|-
| [[Email KSPortálu]]
| noreply@firma.cz,KS Portál
| Adresa odesílatele MIME zprávy (From)
|-
| [[Email Uživatel]]
| mailer@firma.cz
| Google Workspace účet impersonovaný Service Accountem
|-
| [[Email OAuth ClientId]]
| ks-mail-service@projekt.iam.gserviceaccount.com
| Hodnota '''client_email''' Service Accountu
|-
| [[Email OAuth ClientSecret]]
| -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----
| Hodnota '''private_key''' Service Accountu
|-
| [[Email OAuth TenantId]]
| ''nevyplňuje se''
| Google Workspace tuto hodnotu pro tento způsob autentizace nepoužívá
|-
| [[Email OAuth Scopes]]
| https://www.googleapis.com/auth/gmail.send
| OAuth scope umožňující odesílání prostřednictvím Gmail API
|}

Parametry '''Email SMTP''', '''Email SSL Options''' a '''Email EnableSSL''' se při této variantě nepoužívají.

Pokud '''Email Uživatel''' není zadán, použije se jako impersonovaný Google Workspace účet e-mailová adresa z parametru '''Email KSPortálu'''.

Příklad:

 Email KSPortálu = noreply@firma.cz,KS Portál
 Email Uživatel  = mailer@firma.cz

znamená, že Service Account při získání přístupu impersonuje účet:

 mailer@firma.cz

zatímco MIME zpráva obsahuje:

 From: KS Portál <noreply@firma.cz>

Pokud jsou adresy rozdílné, musí být adresa odesílatele v Google Workspace pro technický účet povolena.


== Přehled parametrů podle varianty ==

{| class="wikitable"
! Parametr
! MS_SMTP
! MS_Graph_API
! GMail_SMTP
! GMail_API
|-
| '''Email OAuth'''
| MS_SMTP
| MS_Graph_API
| GMail_SMTP
| GMail_API
|-
| '''Email KSPortálu'''
| odesílatel (From)
| odesílatel (From)
| odesílatel (From)
| odesílatel (From)
|-
| '''Email Uživatel'''
| technický účet pro XOAUTH2
| technický mailbox pro /users/{mailbox}/sendMail
| impersonovaný Workspace účet
| impersonovaný Workspace účet
|-
| '''Email SMTP'''
| smtp.office365.com,587
| nepoužívá se
| smtp.gmail.com,587
| nepoužívá se
|-
| '''Email OAuth ClientId'''
| Application (client) ID
| Application (client) ID
| Service Account client_email
| Service Account client_email
|-
| '''Email OAuth ClientSecret'''
| Client Secret
| Client Secret
| Service Account private_key
| Service Account private_key
|-
| '''Email OAuth TenantId'''
| Directory (tenant) ID
| Directory (tenant) ID
| nepoužívá se
| nepoužívá se
|-
| '''Email OAuth Scopes'''
| https://outlook.office365.com/.default
| https://graph.microsoft.com/.default
| https://mail.google.com/
| https://www.googleapis.com/auth/gmail.send
|-
| '''Email SSL Options'''
| StartTls
| nepoužívá se
| StartTls
| nepoužívá se
|}


== Doporučené varianty ==

Pro nové instalace jsou doporučeny následující varianty:

{| class="wikitable"
! Prostředí
! Doporučená metoda
! Oprávnění
|-
| Microsoft 365
| '''MS_Graph_API'''
| Mail.Send
|-
| Google Workspace
| '''GMail_API'''
| https://www.googleapis.com/auth/gmail.send
|}

API varianty nevyžadují SMTP komunikaci a umožňují přesněji řídit oprávnění aplikace.

SMTP varianty '''MS_SMTP''' a '''GMail_SMTP''' jsou vhodné zejména pro kompatibilitu se stávajícími instalacemi nebo v prostředích, kde zákazník SMTP výslovně požaduje.


== Bezpečnostní doporučení ==

Client Secret Microsoft aplikace a privátní klíč Google Service Accountu představují přihlašovací údaje aplikace.

Doporučuje se:

* neukládat Client Secret ani privátní klíč do logů,
* neposílat je běžným nešifrovaným e-mailem,
* nezobrazovat je celé v diagnostických výstupech,
* omezit aplikaci pouze na mailboxy, které skutečně potřebuje,
* používat pouze nezbytná OAuth oprávnění,
* pravidelně měnit Client Secrets a Service Account klíče,
* po výměně staré přihlašovací údaje deaktivovat nebo odstranit.


== Související odkazy ==

* [[E-mail]]
* [[Parametry (Email)]]
* [[Testování E-mailové komunikace]]
* [[Příručka KS portál]]