Nastavení OAuth 2.0 pro odesílání e-mailů

Z Prirucky
Verze z 25. 8. 2026, 13:22, kterou vytvořil Petrm (diskuse | příspěvky) (založena nová stránka s textem „''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''' | Mi…“)
(rozdíl) ← Starší verze | zobrazit aktuální verzi (rozdíl) | Novější verze → (rozdíl)

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

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:

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.

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

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

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

  • Application (client) ID
  • Directory (tenant) ID

Vytvoření Client Secret

  1. V registraci aplikace otevřete Certificates & secrets > Client secrets.
  2. Zvolte New client secret.
  3. Zadejte popis a požadovanou dobu platnosti.
  4. Vytvořte Client Secret.
  5. 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

  1. V registraci aplikace otevřete API permissions > Add a permission.
  2. Zvolte APIs my organization uses.
  3. Vyhledejte Office 365 Exchange Online.
  4. Zvolte Application permissions.
  5. Přidejte oprávnění SMTP.SendAsApp.
  6. 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:

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

  1. Otevřete App registrations > vaše aplikace > API permissions > Add a permission.
  2. Zvolte Microsoft Graph.
  3. Zvolte Application permissions.
  4. Vyhledejte a přidejte Mail.Send.
  5. 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

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

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

Vytvoření Service Account

  1. Otevřete IAM & Admin > Service Accounts.
  2. Zvolte Create service account.
  3. Zadejte například název KS Mail Service.
  4. 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

  1. Otevřete vytvořený Service Account.
  2. Zvolte Keys > Add key > Create new key.
  3. Vyberte typ JSON.
  4. 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.

  1. Otevřete Google Admin Console.
  2. Přejděte na Security > Access and data control > API controls.
  3. Otevřete Domain-wide delegation > Manage Domain Wide Delegation.
  4. Zvolte Add new.
  5. Do pole Client ID vložte číselné Client ID Service Accountu.
  6. Pro variantu GMail_SMTP vložte OAuth scope:
https://mail.google.com/
  1. 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

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

  1. V příslušném Google Cloud projektu otevřete APIs & Services > Library.
  2. Vyhledejte Gmail API.
  3. 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

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:

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

Citováno z „http://prirucky.ksprogram.cz/index.php?title=Nastavení_OAuth_2.0_pro_odesílání_e-mailů&oldid=52442“