|
značky: ruční vrácení zpět vyprázdnění |
| Řádek 1: |
Řádek 1: |
| ''Nastavení OAuth 2.0 pro odesílání e-mailů''
| |
|
| |
|
| ''OAuth 2.0 pro odesílání e-mailů''
| |
|
| |
| 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]]
| |
