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

== 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, ze které bude odesílat, 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.
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
|-
| Email OAuth
| '''MS_SMTP'''
|-
| [[Email SMTP]]
| smtp.office365.com,587
|-
| [[Email Uživatel]]
| mailer@firma.cz
|-
| [[Email OAuth ClientId]]
| Application (client) ID
|-
| [[Email OAuth ClientSecret]]
| Client Secret
|-
| [[Email OAuth TenantId]]
| Directory (tenant) ID
|-
| [[Email OAuth Scopes]]
| https://outlook.office365.com/.default
|-
| [[Email SSL Options]]
| StartTls
|}

== 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.
=== 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 odesílání pouze ze schránky:
 mailer@firma.cz
=== Nastavení aplikace ===
{| class="wikitable"
! Parametr
! Hodnota / příklad
|-
| Email OAuth
| '''MS_Graph_API'''
|-
| [[Email Uživatel]]
| mailer@firma.cz
|-
| [[Email OAuth ClientId]]
| Application (client) ID
|-
| [[Email OAuth ClientSecret]]
| Client Secret
|-
| [[Email OAuth TenantId]]
| Directory (tenant) ID
|-
| [[Email OAuth Scopes]]
| https://graph.microsoft.com/.default
|}
Parametry SMTP serveru, portu a SSL/TLS se při této variantě nepoužívají.

== 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.
'''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
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.
# 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í.
=== Nastavení aplikace ===
{| class="wikitable"
! Parametr
! Hodnota / příklad
|-
| Email OAuth
| '''GMail_SMTP'''
|-
| [[Email SMTP]]
| smtp.gmail.com,587
|-
| [[Email Uživatel]]
| mailer@firma.cz
|-
| Service Account Email
| ks-mail-service@projekt.iam.gserviceaccount.com
|-
| Private Key
| privátní klíč Service Accountu
|-
| [[Email OAuth Scopes]]
| https://mail.google.com/
|-
| [[Email SSL Options]]
| StartTls
|}
Hodnota '''Email Uživatel''' představuje skutečný Google Workspace účet, za který aplikace odesílá.

== 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
=== 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.
=== 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.
=== Nastavení aplikace ===
{| class="wikitable"
! Parametr
! Hodnota / příklad
|-
| Email OAuth
| '''GMail_API'''
|-
| [[Email Uživatel]]
| mailer@firma.cz
|-
| Service Account Email
| ks-mail-service@projekt.iam.gserviceaccount.com
|-
| Private Key
| privátní klíč Service Accountu
|-
| [[Email OAuth Scopes]]
| https://www.googleapis.com/auth/gmail.send
|}
Parametry SMTP serveru, portu a SSL/TLS se při této variantě nepoužívají.

== 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]]