OAuth instellen

Er zijn veel verschillende e-mailsoorten die je vanuit Intramed kunt versturen. In de e-mailinstellingen leg je de instellingen vast, die gelden binnen de praktijk of instelling.

Let op! Intramed kan hierbij geen ondersteuning bieden, omdat deze instellingen aangemaakt moeten worden binnen jouw eigen e-mailserveromgeving.
Onderstaande stappen zijn gericht op SMTP via smtp.office365.com, om te gebruiken binnen Intramed. In deze handleiding leggen we precies uit waar je dient te klikken, zodat je een stap voor stap handleiding hebt om dit in te stellen.

  • Ga naar https://portal.azure.com
  • Log in met jouw Microsoft 365 account
  • Klik links in het rijtje onder Beheren op App-registraties of App-registrations
  • Klik bovenaan op + Nieuwe registratie of + New registration
App registratie toevoegen in Microsoft Entra
  • 5. Vul bij Naam of Name bijvoorbeeld “Intramed”
  • 6.Laat de standaardindeling bij Supported account types
  • Klik op Register of Registreer

Samenvatting
English: Azure AD → App registrations → + New registration → Register.
Nederlands: Azure AD → App registratie → + Nieuwe registratie → Registreer.

 Nadat je een nieuwe App-registratie hebt aangemaakt, kun je de Client Secret aan gaan maken. Volg daarvoor onderstaande stappen voor:

  • Ga naar het menu aan de linkerkant Certificates & secrets/Certificaten en geheimen of naar Client credentials/Clientreferenties en klik op “Add a certificate or secret/Een certificaat of geheim toevoegen”.
  • Geef het Secret een naam, bijvoorbeeld Intramed Secret en klik op Add/toevoegen.
  • Je ziet nu een value/waarde, kopieer deze meteen, want later zie je hem niet meer

Samenvatting

  • English: App → Certificates & secrets → + New client secret → Add.
    Nederlands: App → Certificaten en geheimen → + Nieuwe clientreferentie → Toevoegen
Client ID aanmaken in Microsoft Entra

Om gebruik te maken van de OAuth in Intramed, heb je de SMTP OAuth permissions/toestemming nodig.

  • Klik op API permissions/API-machtigingen
  • Klik op + Add a permission/+ Een machtiging toevoegen.
  • Kies APIs my organization uses/APIS die mijn organisatie gebruikt
  • Zoek op: Office 365 Exchange Online en klik erop.
  • Kies Application permissions/Applicatie machtigingen (voor app-login zonder gebruiker).
    SMTP.SendAsApp
  • Klik op Add permissions/Applicatie machtigingen

Korte samenvatting:

  • App → API permissions → + Add a permission → Exchange Online → permissions selecteren → Add.
  • App → API-machtigingen → + Machtiging toevoegen → Exchange Online → machtigingen selecteren → Toevoegen
Api machtigingen instellen in Microsoft Entra

Vervolgens zorg je ervoor dat er Admin toestemming is. Zonder deze stap, werkt SMTP OAuth niet!

  • Ga opnieuw naar API permissions
  • Bovenaan staat een knop Grant admin consent for .
  • Alleen een tenant-admin kan hierop klikken en bevestigen

Korte samenvatting:

  • App → API permissions → Grant admin consent.

LET OP! Je moet de Service Principals nog instellen wil alles naar behoren werken. In het volgende artikel kan je lezen hoe je dit instelt.

Vervolgens dien je ervoor te zorgen dat de SMTP AUTH aan staat voor de mailbox. SMTP AUTH staat vaak uit in moderne tenants. Dat moet AAN. Dit doet de admin in Exchange Online PowerShell.

Onderstaande Powershell commando’s zijn belangrijk om de koppeling correct op te bouwen.

  • Aan voor één mailbox:
    Set-CASMailbox -Identity [Het ingestelde e-mail adres] -SmtpClientAuthenticationDisabled:$false
  • Controleren tenantbreed:
    Get-TransportConfig | fl SmtpClientAuthenticationDisabled
  • Zo nodig tenant-aanpassing:
    Set-TransportConfig -SmtpClientAuthenticationDisabled $false
  • Graph verbinden
    Connect-MgGraph -Scopes “Application.ReadWrite.All”,”Directory.ReadWrite.All”
  • App registration opzoeken
    Get-MgApplication -Filter “AppId eq ‘CLIENT-ID'” | Select-Object DisplayName, Id, AppId
  • Service principal opzoeken
    Get-MgServicePrincipal -All | Where-Object {$_.AppId -eq “CLIENT-ID”} | Select-Object DisplayName, Id, AppId
  • Service principal aanmaken
    New-MgServicePrincipal -AppId “CLIENT-ID”
  • Exchange verbinden
    Connect-ExchangeOnline -UserPrincipalName admin@tenant.onmicrosoft.com
  • Exchange service principal registreren
    New-ServicePrincipal -AppId “CLIENT-ID” -ObjectId “SERVICE-PRINCIPAL-ID” -DisplayName “Intramed”
  • Mailboxrechten geven
    Add-MailboxPermission -Identity [Het ingestelde e-mail adres] -User “SERVICE-PRINCIPAL-ID” -AccessRights FullAccess
  • SMTP AUTH tenant controleren
    Get-TransportConfig | Select-Object SmtpClientAuthenticationDisabled
  • SMTP AUTH mailbox controleren
    Get-CASMailbox [Het ingestelde e-mail adres] | Select-Object SmtpClientAuthenticationDisabled
  • Mailbox controleren
    Get-Mailbox [Het ingestelde e-mail adres] | Select-Object DisplayName,PrimarySmtpAddress,RecipientTypeDetails,EmailAddresses

LET OP: In de documentatie van Microsoft gaan ze uit van een Exchange Service Principal. Alleen dat is in dit geval niet genoeg, want daarmee is de app wel bekend in Exchange, maar heeft die nog geen toegang tot de mailbox zelf.

De app moet dus niet alleen gekoppeld zijn in Exchange, maar ook als service principal bestaan in Entra én rechten hebben op het betreffende postvak. Anders krijg je wel een token terug, maar gaat het verzenden van e-mail alsnog fout.

Vervolgens kun je gaan testen met onderstaande gegevens, deze gebruik je in jouw code/script.

SMTP-instellingen:

  • Server: smtp.office365.com
  • Port: 587
  • Encryption: STARTTLS
  • Authenticatie: XOAUTH2

OAuth token scopes
Voor app-login (client credentials):

  • https://outlook.office.com/.default

XOAUTH2 string formaat:

  • base64(“user=<email>auth=Bearer <ACCESS_TOKEN>”)

Zodra alle bovenstaande stappen zijn doorlopen, ga je testen met een mail via jouw script/app. Als er een fout komt zoals “535 Authentication failed”, controleer dan:

  • Admin consent gegeven?
  • SMTP AUTH aan voor mailbox?
  • Gebruik je het juiste token + scope?
  • Klopt je XOAUTH2 base64-string?

Zodra bovenstaande werkt, kun je de OAuth instellen binnen Intramed, daarvoor volg je onderstaande stappen.

Hoe stel je de Microsoft OAuth-authenticatie binnen Intramed in?
De Microsoft OAuth-authenticatie wordt binnen Intramed in hetzelfde scherm ingesteld als waar je de SMTP-gegevens noteerde.

  • Ga naar [Systeem] → [Organisatie] → [E-mailinstellingen].
    Hier zijn twee nieuwe velden toegevoegd: Tenant ID en Client ID. Deze zijn zichtbaar wanneer de authenticatiemethode is ingesteld op Microsoft OAuth.
    In Microsoft Azure vind je het Tenant ID en Client ID terug onder “App-registraties”.
  • Het is enorm belangrijk om het juiste e-mailadres in de praktijkgegevens in te vullen. Dit moet hetzelfde e-mailadres zijn als wat is ingevuld bij de e-mailinstellingen. Om dit te controleren ga je naar [Systeem] → [Organisatie] → [Praktijkgegevens], tabblad “1. Praktijk”.
  • De Secret Value of Secret ID vul je in bij het veld “Wachtwoord”. Vul hier dus niet het wachtwoord van het e-mailadres zelf in. Het secret heb je eerder gekopieerd bij stap 2.
  • Als het juiste e-mailadres hier genoteerd is, kun je een testmail sturen. Dit doe je via het e-mailicoontje in de praktijkgegevens.
Wachtwoord en vervaldatum van de Secret
Tenant en Client ID instellen

In deze film wordt uitgelegd hoe je de OAuth via SMPT kunt instellen in Azure

Ik krijg de melding “HTTP/1.1 401 Unautorized”. Wat moet ik doen?
Ik krijg de foutmelding “HTTP/1.1 400 Bad Request”, wat moet ik nu doen?
Ik krijg de foutmelding “SSL_read_ex failed”, wat moet ik nu doen?
Ik krijg de melding “Authentication is unsuccesfull, SmtpClientAuthentication is disabled for the tenant.”. Wat moet ik doen?
Ik krijg de foutmelding “The specified SASL handlers are not ready!!”, wat moet ik nu doen?
Ik krijg de foutmelding “Error connecting with SSL”. Wat moet ik doen?
Ik krijg de melding “Connect timed out”. Wat moet ik doen?
Ik krijg de foutmelding “SendAsDenied”, wat moet ik nu doen?
Ik krijg de foutmelding “Invalid pointer operation”. Hoe los ik dit op?
Ik krijg de melding “Authentication is unsuccesfull”. Wat moet ik doen?