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:

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.

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

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

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, 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:

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

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

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

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

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.

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 ze staženého JSON souboru.
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í.

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

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

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.

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

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

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:

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