Przejdź do treści

© navision.pl | Opracowano na podstawie: Microsoft Learn (CC BY 4.0)

Korzystanie z SMTP do poczty e-mail w środowisku wielodostępnym

W tym artykule wyjaśniono, jak skonfigurować dzierżawę Microsoft 365, aby aplikacja Business Central mogła wysyłać wiadomości e-mail za pośrednictwem łącznika SMTP przy użyciu protokołu OAuth 2.0 (przepływ poświadczeń klienta).

W tym artykule opisano również, jak włączyć scenariusze międzydzierżawcze. Na przykład, gdy masz rejestrację aplikacji w witrynie Azure Portal w jednej dzierżawie Microsoft Entra, ale używasz jej do wysyłania wiadomości e-mail z innej dzierżawy.

W poniższych procedurach dzierżawę Microsoft Entra, w której znajduje się rejestracja aplikacji, nazywamy "Dzierżawą A", a dzierżawę, w której jest ona używana do SMTP, nazywamy "Dzierżawą B". Dzierżawa B zawiera aplikację Business Central.

Ostrzeżenie

Exchange Online is deprecating use of Basic authentication for SMTP. This change doesn't affect tenants that currently use SMTP AUTH. However, we recommend that you use the latest version, and set up OAuth 2.0 authentication for SMTP. If you can't set up OAuth 2.0 authentication, we encourage you to explore non-Microsoft alternatives if you want to use SMTP email in earlier versions. Business Central doesn't support certificate-based authentication.

Poniższa lista zawiera przegląd kroków niezbędnych do używania protokołu OAuth 2.0 z łącznikiem SMTP. W tym artykule opisano każdy krok.

  1. Tworzenie rejestracji aplikacji w witrynie Azure Portal
  2. Przyznawanie uprawnień interfejsu API
  3. Tworzenie klucza tajnego klienta lub certyfikatu
  4. Rejestrowanie jednostki usługi w Exchange Online
  5. Przyznawanie aplikacji uprawnienia do wysyłania jako skrzynka pocztowa
  6. Weryfikowanie konfiguracji SMTP OAuth

Uwaga

Niektóre kroki wymagają uruchomienia jednego lub więcej poleceń w programie PowerShell. Pamiętaj, aby uruchamiać polecenia jako administrator.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz:

  • Dzierżawę Microsoft 365 z Exchange Online.
  • Uprawnienia administratora globalnego lub administratora Exchange.
  • Skrzynkę pocztową, na przykład service@yourdomain.com, której używasz jako adres nadawcy.
  • Środowisko Business Central online lub lokalne.
  • (Opcjonalnie) Python 3.10+ lub inne środowisko obsługujące uwierzytelnianie SMTP oparte na OAuth do celów testowych.

Tworzenie rejestracji aplikacji w witrynie Azure Portal

Pierwszym krokiem jest utworzenie rejestracji aplikacji dla aplikacji znajdującej się w "Dzierżawie A" w usłudze Microsoft Entra ID. Rejestracja aplikacji umożliwia aplikacji Business Central wysyłanie wiadomości e-mail ze skrzynki pocztowej znajdującej się w innej dzierżawie Microsoft Entra.

  1. Przejdź do witryny Azure Portal.
  2. W sekcji Usługi platformy Azure wybierz pozycję Microsoft Entra ID.
  3. W okienku nawigacji wybierz pozycję Rejestracje aplikacji.
  4. Na stronie Rejestracje aplikacji wybierz pozycję Nowa rejestracja.

  5. Na stronie Rejestrowanie aplikacji wypełnij pola w następujący sposób:

    1. W polu Nazwa wprowadź nazwę aplikacji. Na przykład SMTP_OAuth_App.
    2. W sekcji Obsługiwane typy kont wybierz opcję Konta w dowolnym katalogu organizacyjnym (dowolna dzierżawa Microsoft Entra ID - wielodostępna) i osobiste konta Microsoft (np. Skype, Xbox). To ustawienie jest wymagane do uzyskania zgody międzydzierżawczej.
    3. W sekcji Identyfikator URI przekierowania (opcjonalnie) dla platformy wybierz opcję Internet, a następnie wprowadź identyfikator URI.

  6. Wybierz pozycję Zarejestruj.

Uwaga

Po zarejestrowaniu aplikacji w usłudze Microsoft Entra ID zanotuj następujące informacje. Będą potrzebne do wykonania późniejszego kroku. |Pole |Przykład |Opis | |---------|---------|---------| |Identyfikator aplikacji (klienta) | 00001111-aaaa-2222-bbbb-3333cccc4444 | Identyfikator aplikacji | |Identyfikator katalogu (dzierżawy) | aaaabbbb-0000-cccc-1111-dddd2222eeee | Identyfikator dzierżawy | |Identyfikator obiektu | aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb | Identyfikator jednostki usługi|

Przyznawanie uprawnień interfejsu API

Następnym krokiem jest nadanie aplikacji uprawnienia do wysyłania wiadomości e-mail.

  1. W witrynie Azure Portal na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API, a następnie wybierz pozycję Dodaj uprawnienie.
  2. Wybierz pozycję Interfejsy API używane przez moją organizację.
  3. Wyszukaj pozycję Office 365 Exchange Online.
  4. Wybierz pozycję Uprawnienia aplikacji.
  5. Rozwiń węzeł SMTP, a następnie wybierz pozycję SMTP.SendAsApp.
  6. Wybierz pozycję Dodaj uprawnienia.
  7. Sprawdź dokładnie, czy pozycja SMTP.SendAsApp ma zielony znacznik wyboru.

Tworzenie klucza tajnego klienta lub certyfikatu

  1. W witrynie Azure Portal na stronie aplikacji wybierz pozycję Certyfikaty i wpisy tajne.
  2. W polu Klucz tajny klienta wybierz pozycję Nowy klucz tajny klienta, nadaj mu nazwę i określ okres ważności.

Ostrzeżenie

Zanotuj Wartość klucza tajnego klienta. Wartość jest wyświetlana tylko raz i jest potrzebna do generowania tokenów.

Rejestrowanie jednostki usługi w Exchange Online

Aby dowiedzieć się więcej o jednostce usługi, przejdź do artykułu Rejestrowanie aplikacji Microsoft Entra i tworzenie jednostki usługi.

  1. W programie PowerShell użyj poniższego linku, aby wyrazić zgodę. Zastąp identyfikator dzierżawy i identyfikator klienta (identyfikator aplikacji) wartościami dla "Dzierżawy B".

https://login.microsoftonline.com/<TenantB_ID>/oauth2/v2.0/authorize?client_id=<Client_ID>&scope=https://graph.microsoft.com/.default&response_type=code&response_mode=query&prompt=consent

  1. W centrum administracyjnym Microsoft Entra przejdź do sekcji Aplikacje dla przedsiębiorstw, znajdź swoją aplikację, a następnie skopiuj wartość z pola Identyfikator obiektu. Identyfikator obiektu jest używany jako identyfikator usługi w poleceniu w następnym kroku tego procesu.
  2. Aby utworzyć nową jednostkę usługi w dzierżawie, uruchom następujące polecenie w PowerShell jako administrator.
Install-Module ExchangeOnlineManagement -Scope CurrentUser

Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName yourname@yourdomain.com

$AppId     = \<your app ID>
$ServiceId = \<your service ID> # The object id of the enterprise app 
$Display   = "SMTP_OAuth_App" # The name of the service principal you want to create

New-ServicePrincipal -AppId $AppId -ServiceId $ServiceId -DisplayName $Display

Uwaga

Jeśli jednostka usługi już istnieje, polecenie może wyświetlić błąd, ale można go bezpiecznie zignorować.

Udziel aplikacji uprawnień do wysyłania jako skrzynka pocztowa

Witryna Azure portal ukrywa opcję SMTP, dlatego należy użyć PowerShell, aby udzielić uprawnień do wysyłania jako skrzynka pocztowa.

  1. W PowerShell uruchom następujące polecenie:

```powershell

  $sp = Get-ServicePrincipal | Where-Object { $_.AppId -eq "{AppID}" }

   # Replace this with the mailbox you use as the from_addr / user= in XOAUTH2.
  $Mailbox = "someuser@xxx.onmicrosoft.com"

  Add-MailboxPermission -Identity $Mailbox `
      -User $sp.ObjectId `
      -AccessRights FullAccess `
      -AutoMapping:$false

   # If you have multiple users, create a group for them and then assign them.
  Get-DistributionGroupMember "Your group name" |
    ForEach-Object {
        Add-MailboxPermission -$_.PrimarySmtpAddress `
            -User $sp.ObjectId `
            -AccessRights FullAccess `
            -AutoMapping:$false
    }

  ```
  1. Aby zweryfikować uprawnienia, uruchom następujące polecenie:
Get-MailboxPermission  -Identity $Mailbox | ? {$_.User -eq $Display}

Powinieneś mieć AccessRights, SendAs lub oba.

Zweryfikuj konfigurację SMTP OAuth

  1. W PowerShell uruchom następujące polecenie, aby zweryfikować konfigurację SMTP:
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName admin@yourtenant.onmicrosoft.com
Get-CASMailbox -Identity admin@yourtenant.onmicrosoft.com | Select SmtpClientAuthenticationDisabled

# If the output is false, it's enabled. But if it's true, SMTP is disabled and you must run the following command to enable it:

Set-CASMailbox -Identity admin@yourtenant.onmicrosoft.com -SmtpClientAuthenticationDisabled $false
  1. Opcjonalnie, jeśli chcesz włączyć SMTP na poziomie całej organizacji, uruchom następujące polecenie:
Get-TransportConfig | Select SmtpClientAuthenticationDisabled

# If the output is false it's enabled. If it's true, SMTP is disabled and you must run the following command to enable it:

Set-TransportConfig -SmtpClientAuthenticationDisabled $false
  1. Aby zweryfikować, czy OAuth 2.0 jest globalnie włączony dla SMTP, uruchom następujące polecenie:
Get-TransportConfig | fl SmtpClientAuthenticationDisabled,OAuth2ClientProfileEnabled

Oczekiwane dane wyjściowe są następujące:

  • SmtpClientAuthenticationDisabled ma wartość False.
  • OAuth2ClientProfileEnabled ma wartość True.

Jeśli SmtpClientAuthenticationDisabled ma wartość True, SMTP nie jest włączony. Aby go włączyć, uruchom następujące polecenie:

Set-TransportConfig -SmtpClientAuthenticationDisabled $false

Konfiguracja łącznika SMTP w Business Central

Aby dowiedzieć się więcej o łączniku SMTP, przejdź do Konfigurowanie poczty e-mail w Business Central.

  1. W Business Central, wybierz Szukaj (Alt+Q) Szukaj w prawym górnym rogu, wprowadź Konfiguracja wspomagana, a następnie wybierz powiązane łącze.
  2. Wybierz Skonfiguruj konto SMTP.
  3. Wypełnij pola zgodnie z opisem w poniższej tabeli.
Field Przykładowa wartość Uwagi
Serwer smtp.office365.com
Port serwera 587
Typ uwierzytelniania OAuth 2.0
Identyfikator klienta 00001111-aaaa-2222-bbbb-3333cccc4444 Identyfikator aplikacji z Dzierżawy A.
Klucz tajny klienta Klucz tajny wygenerowany w aplikacji.
Tenant ID aaaabbbb-0000-cccc-1111-dddd2222eeee Identyfikator Dzierżawy B, w której znajduje się konto e-mail.
Identyfikator URI przekierowania Ten identyfikator URI dotyczy tylko Business Central lokalnego. Można dostosować wartość, ale w takim przypadku należy zaktualizować rejestrację aplikacji w witrynie Azure portal.
Użyj niestandardowej rejestracji aplikacji Jeśli chcesz użyć niestandardowej rejestracji aplikacji, włącz przełącznik.
  1. Aby zakończyć konfigurację konta, wybierz Dalej, a następnie udziel zgody.

Wyślij testową wiadomość e-mail

Poniższy przykład pokazuje sposób testowania OAuth 2.0 dla łącznika SMTP.

param(
    [string]$TenantId     = "your tenant id here",  
    [string]$ClientId     = "your client id here",  
    [string]$ClientSecret = "your client secret here",
    [string]$From         = "your from address here",
    [string]$To           = "your to address here",
    [string]$Subject      = "SMTP OAuth Test",
    [string]$Body         = "Hello! This is a test email using SMTP OAuth."
)

#---------------
# 0. Prepare & Import Module
#---------------
# If you don't have MSAL.PS module, uncomment the next line to install it
# Install-Module MSAL.PS -Scope CurrentUser
Import-Module MSAL.PS -ErrorAction Stop

#---------------
# 1. Get Access Token
#---------------
Write-Host "Getting access token from AAD..." -ForegroundColor Cyan

$secureSecret = ConvertTo-SecureString $ClientSecret -AsPlainText -Force

$tokenResult = Get-MsalToken `
    -ClientId      $ClientId `
    -ClientSecret  $secureSecret `
    -TenantId      $TenantId `
    -Scopes        "https://outlook.office365.com/.default"

$accessToken = $tokenResult.AccessToken.Trim()

function Convert-FromBase64Url {
    param([string]$InputString)

    $pad = 4 - ($InputString.Length % 4)
    if ($pad -lt 4) {
        $InputString += "=" * $pad
    }

    $InputString = $InputString.Replace('-', '+').Replace('_', '/')
    $bytes = [System.Convert]::FromBase64String($InputString)
    return $bytes
}

$parts = $accessToken.Split('.')
$payloadBytes = Convert-FromBase64Url -InputString $parts[1]
$payloadJson  = [System.Text.Encoding]::UTF8.GetString($payloadBytes)
$claims       = $payloadJson | ConvertFrom-Json

Write-Host "Access token acquired."
Write-Host "aud   =" $claims.aud
Write-Host "roles =" ($claims.roles -join ", ")
Write-Host "appid =" $claims.appid
Write-Host "tid   =" $claims.tid
Write-Host ""

#---------------
# 2. Build AUTH XOAUTH2
#---------------

function New-XOAuth2String {
    param(
        [string]$User,
        [string]$Token
    )
    $ctrlA = [char]1

    $auth  = "user=$User$ctrlA" + "auth=Bearer $Token$ctrlA$ctrlA"
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($auth)
    return [System.Convert]::ToBase64String($bytes)
}

$authB64 = New-XOAuth2String -User $From -Token $accessToken
Write-Host "AUTH (base64) generated." -ForegroundColor Cyan


$msg =
"From: $From`r`n" +
"To: $To`r`n" +
"Subject: $Subject`r`n" +
"`r`n" +
"$Body`r`n"


function Read-SmtpResponse {
    param([System.IO.StreamReader]$Reader)

    $line = $Reader.ReadLine()
    if ($line -ne $null) {
        Write-Host $line
    }
    return $line
}

$server = "smtp.office365.com"
$port   = 587

Write-Host ""
Write-Host "Connecting to $server : $port ..." -ForegroundColor Cyan

$tcpClient     = New-Object System.Net.Sockets.TcpClient($server, $port)
$networkStream = $tcpClient.GetStream()

$reader = New-Object System.IO.StreamReader($networkStream)
$writer = New-Object System.IO.StreamWriter($networkStream)
$writer.NewLine   = "`r`n"
$writer.AutoFlush = $true

# init  banner
Read-SmtpResponse -Reader $reader | Out-Null

# EHLO (before STARTTLS)
$writer.WriteLine("EHLO localhost")
do {
    $line = Read-SmtpResponse -Reader $reader
} while ($line -match "^[0-9]{3}-")

# STARTTLS
$writer.WriteLine("STARTTLS")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("220")) {
    throw "STARTTLS failed: $line"
}

$sslStream = New-Object System.Net.Security.SslStream(
    $networkStream,
    $false,
    { param($sender, $cert, $chain, $errors) return $true }
)
$sslStream.AuthenticateAsClient($server)

$reader = New-Object System.IO.StreamReader($sslStream)
$writer = New-Object System.IO.StreamWriter($sslStream)
$writer.NewLine   = "`r`n"
$writer.AutoFlush = $true

# EHLO (after STARTTLS)
$writer.WriteLine("EHLO localhost")
do {
    $line = Read-SmtpResponse -Reader $reader
} while ($line -match "^[0-9]{3}-")

# AUTH XOAUTH2
Write-Host ""
Write-Host "Sending AUTH XOAUTH2 ..." -ForegroundColor Cyan
$writer.WriteLine("AUTH XOAUTH2 $authB64")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("235")) {
    throw "AUTH failed: $line"
}

# MAIL FROM
$writer.WriteLine("MAIL FROM:<$From>")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("250")) {
    throw "MAIL FROM failed: $line"
}

# RCPT TO
$writer.WriteLine("RCPT TO:<$To>")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("250")) {
    throw "RCPT TO failed: $line"
}

# DATA
$writer.WriteLine("DATA")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("354")) {
    throw "DATA command failed: $line"
}

$writer.WriteLine($msg)
$writer.WriteLine(".")
$line = Read-SmtpResponse -Reader $reader
if (-not $line.StartsWith("250")) {
    throw "Message send failed: $line"
}

# QUIT
$writer.WriteLine("QUIT")
Read-SmtpResponse -Reader $reader | Out-Null

$reader.Close()
$writer.Close()
$sslStream.Close()
$networkStream.Close()
$tcpClient.Close()

Write-Host ""
Write-Host "✅ Email sent successfully from $From to $To" -ForegroundColor Green

Rozwiązywanie problemów

Ta sekcja zawiera listę typowych problemów, ich przyczyny oraz sugestie dotyczące ich rozwiązania.

AADSTS50011: redirect_uri mismatch

  • Przyczyna: Identyfikator URI przekierowania nie jest skonfigurowany dla rejestracji aplikacji w witrynie Azure portal.
  • Rozwiązanie: Zaktualizuj rejestrację aplikacji w witrynie Azure portal, aby używać tego samego identyfikatora URI przekierowania .../oauthlanding.htm. Dowiedz się więcej w sekcji Tworzenie rejestracji aplikacji w witrynie Azure portal.

535 Authentication unsuccessful

  • Przyczyna: SMTP AUTH jest wyłączony lub ma nieprawidłowy identyfikator dzierżawy.
  • Rozwiązanie: Sprawdź Get-TransportConfig, aby upewnić się, że SmtpClientAuthentidationDisabled ma wartość False.

530 5.7.57 Klient nie jest uwierzytelniony

  • Przyczyna: Token jest brakujący lub nieprawidłowy.
  • Rozwiązanie: Sprawdź SMTP.SendAsApp i zgodę administratora.

430 błąd logowania do skrzynki pocztowej

  • Przyczyna: Brak uprawnień SendAs.
  • Rozwiązanie: Uruchom Set-CASMailbox.

550 5.7.708 Usługa niedostępna

  • Przyczyna: Nowy dzierżawca jest ograniczony lub ma nieprawidłowy identyfikator dzierżawcy. Na przykład wprowadzono identyfikator Dzierżawcy A, ale konto należy do Dzierżawcy B.
  • Rozwiązanie: Skontaktuj się z pomocą techniczną Microsoft 365 lub sprawdź identyfikator dzierżawcy.

Powiązane informacje

Konfigurowanie poczty e-mail w Business Central