====== Instellingen: e-mail via Microsoft 365 ====== MasterKey kan automatische e-mails (bijvoorbeeld rapportages en notificaties) versturen vanuit een mailbox van uw eigen organisatie in **Microsoft 365**. Daarvoor maakt uw **ICT-afdeling** een app-registratie aan in uw eigen Microsoft 365-omgeving en vult een beheerder de gegevens daarvan in MasterKey in. * MasterKey krijgt alleen het recht om e-mail te versturen vanuit de mailbox die u kiest. Er wordt geen wachtwoord van een gebruiker opgeslagen. * U bepaalt zelf vanuit welke mailbox MasterKey mag versturen. * U kunt de toegang op elk moment intrekken door het clientgeheim of de app-registratie te verwijderen. * Omdat de e-mails echt vanuit uw eigen mailbox worden verstuurd, is geen SPF-record voor MasterKey nodig en staan verzonden e-mails in de map //Verzonden items// van die mailbox. Deze pagina is bedoeld voor uw ICT-afdeling (stap 1 t/m 5) en voor de beheerder van MasterKey binnen uw organisatie (stap 6 en 7). Voor stap 1 t/m 5 is een account nodig met de rol //Toepassingsbeheerder// (//Application Administrator//) en, voor stap 5, //Exchange-beheerder// (//Exchange Administrator//). Reken op ongeveer 30 minuten. ==== In het kort ==== ^ Onderdeel ^ Waarde ^ | Soort koppeling | App-only via Microsoft Graph (OAuth 2.0 //client credentials//); MasterKey meldt geen gebruiker aan | | Ondersteunde accounttypen | Alleen accounts in deze organisatiemap (één tenant) | | Omleidings-URI (redirect/callback-URL) | **Niet nodig**, leeg laten | | Machtigingen | ''Mail.Send'' en ''Mail.ReadWrite'' (toepassingsmachtigingen, niet gedelegeerd) | | Authenticatie | Clientgeheim, maximaal 24 maanden geldig | | SMTP AUTH | Niet nodig, mag uitgeschakeld blijven | | DNS (SPF, DKIM, DMARC) | Geen wijziging nodig; de e-mail gaat via uw eigen Microsoft 365 | | Uitgaand verkeer vanaf MasterKey | ''login.microsoftonline.com'' en ''graph.microsoft.com'' (HTTPS, poort 443) | | Gegevens voor MasterKey | Mailboxadres, Directory (tenant) ID, Application (client) ID, waarde en vervaldatum van het clientgeheim | ==== Stap 1: Mailbox kiezen ==== Kies of maak de mailbox waaruit MasterKey verstuurt. Wij raden een **gedeelde mailbox** aan, bijvoorbeeld ''kwaliteit@uwbedrijf.nl''; daarvoor is geen licentie nodig. Wilt u dat antwoorden van ontvangers gelezen worden, kies dan een mailbox die iemand bijhoudt. Exchange Online heeft verzendlimieten per mailbox: maximaal 10.000 ontvangers per dag en 30 berichten per minuut. De standaard maximale berichtgrootte is 35 MB. ==== Stap 2: App-registratie aanmaken ==== - Open het **Microsoft Entra-beheercentrum** (https://entra.microsoft.com) met een account met de rol //Toepassingsbeheerder// of hoger. - Ga naar **Identiteit → Toepassingen → App-registraties → Nieuwe registratie** (//Identity → Applications → App registrations → New registration//). - Naam: bijvoorbeeld ''MasterKey mail''. - Ondersteunde accounttypen: **Alleen accounts in deze organisatiemap (één tenant)**. - Omleidings-URI: leeg laten. MasterKey meldt geen gebruikers aan, dus een callback-URL is niet nodig. - Klik op **Registreren**. Noteer op de overzichtspagina de **Directory-id (tenant)** en de **Toepassings-id (client)** (//Directory (tenant) ID// en //Application (client) ID//). ==== Stap 3: Machtigingen toevoegen ==== - Ga in de app-registratie naar **API-machtigingen → Een machtiging toevoegen → Microsoft Graph → Toepassingsmachtigingen** (//Application permissions//). - Voeg **Mail.Send** en **Mail.ReadWrite** toe. Kleine e-mails verstuurt MasterKey in één keer met Mail.Send. Voor e-mails met grote bijlagen (vanaf ongeveer 3 MB) maakt MasterKey eerst een concept in de mailbox aan, voegt de bijlagen los toe en verstuurt het concept; daarvoor is Mail.ReadWrite nodig. MasterKey leest geen andere e-mail in de mailbox. - Verwijder de standaardmachtiging //User.Read//; die is niet nodig. Met alleen deze machtigingen mag de app nog niets: in stap 5 geeft u toestemming, bij voorkeur beperkt tot één mailbox. ==== Stap 4: Clientgeheim aanmaken ==== - Ga naar **Certificaten en geheimen → Nieuw clientgeheim** (//Certificates & secrets → New client secret//). - Kies een looptijd (maximaal 24 maanden) en noteer de **vervaldatum**. - Kopieer direct de **Waarde** (//Value//) van het geheim. Deze is later niet meer te zien. Let op: gebruik niet de //Geheim-ID// (//Secret ID//). Behandel het geheim als een wachtwoord: stuur het niet per gewone e-mail. Vul het bij voorkeur zelf in MasterKey in (stap 6), samen met de beheerder van MasterKey. ==== Stap 5: Toestemming geven, beperkt tot één mailbox (aanbevolen) ==== Met een gewone beheerderstoestemming mag de app vanuit en in **alle** mailboxen van uw organisatie werken. Wij raden aan dit te beperken tot de mailbox uit stap 1 met //RBAC for Applications// in Exchange Online. Geef in dat geval **geen** beheerderstoestemming bij de API-machtigingen (of trek die weer in via **Bedrijfstoepassingen → MasterKey mail → Machtigingen**), want die toestemming geldt voor alle mailboxen en heft de beperking op. Voer in **Exchange Online PowerShell** uit. Gebruik de object-id van de app onder **Bedrijfstoepassingen** (//Enterprise applications//), niet die onder App-registraties. Install-Module ExchangeOnlineManagement # eenmalig Connect-ExchangeOnline New-ServicePrincipal -AppId -ObjectId -DisplayName "MasterKey mail" New-ManagementScope -Name "MasterKey mail" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'kwaliteit@uwbedrijf.nl'" New-ManagementRoleAssignment -App -Role "Application Mail.Send" -CustomResourceScope "MasterKey mail" New-ManagementRoleAssignment -App -Role "Application Mail.ReadWrite" -CustomResourceScope "MasterKey mail" Controleer de beperking; beide rollen moeten //InScope// ''True'' hebben. Bij een andere mailbox hoort //InScope// ''False'' te staan: Test-ServicePrincipalAuthorization -Identity -Resource kwaliteit@uwbedrijf.nl Het kan tot 2 uur duren voordat Microsoft de rechten overal heeft doorgevoerd. Meer mailboxen toestaan kan later met een aangepast filter, bijvoorbeeld een e-mailbeveiligingsgroep: ''-RecipientRestrictionFilter "MemberOfGroup -eq ''"''. Wilt u de app niet beperken, klik dan bij **API-machtigingen** op **Beheerderstoestemming verlenen voor **. Gebruikt uw organisatie //Voorwaardelijke toegang voor workload-identiteiten// (//Conditional Access for workload identities//) met een beperking op locatie? Vraag dan bij MasterKey de actuele uitgaande IP-adressen op en sta die toe voor de app ''MasterKey mail''. Gewone regels voor voorwaardelijke toegang voor gebruikers gelden niet voor deze app. ==== Stap 6: Gegevens invullen in MasterKey ==== Een beheerder in MasterKey gaat naar **Instellingen → Applicatie → E-mail** en kiest bij **Mailserver** voor **Microsoft 365**. Vul in: * **Verzenden vanuit mailbox**: de mailbox uit stap 1. * **Directory (tenant) ID** en **Application (client) ID**: uit stap 2. * **Clientgeheim (waarde)**: de waarde uit stap 4. Na het opslaan wordt het geheim versleuteld bewaard en nooit meer getoond; laat het veld later leeg om het opgeslagen geheim te houden. * **Geheim verloopt op**: de vervaldatum uit stap 4. Klik op **Opslaan** en daarna op **Testmail versturen**. MasterKey stuurt dan een testmail naar uw eigen e-mailadres. Lukt dat niet, dan toont MasterKey de melding van Microsoft, bijvoorbeeld als het geheim onjuist is of de app geen toestemming heeft voor de mailbox (zie //Veelvoorkomende meldingen//). ==== Stap 7: Voordat het clientgeheim verloopt ==== Vanaf 30 dagen voor de vervaldatum toont MasterKey bij **Instellingen → Applicatie → E-mail** een waarschuwing. Na de vervaldatum kan MasterKey geen e-mail meer versturen. Vernieuw het geheim daarom op tijd: - Laat uw ICT-afdeling een nieuw clientgeheim aanmaken (stap 4). Het oude geheim blijft tot de vervaldatum geldig. - Vul de nieuwe waarde en vervaldatum in MasterKey in, sla op en verstuur een testmail. - Laat daarna het oude geheim in Entra verwijderen. ==== Toegang intrekken ==== U kunt de koppeling op elk moment stoppen; MasterKey kan daarna direct geen e-mail meer versturen vanuit uw mailbox: * verwijder het clientgeheim, of * verwijder de app-registratie ''MasterKey mail'', of * verwijder de rechten uit stap 5 met ''Remove-ManagementRoleAssignment''. Kies daarna in MasterKey bij **Instellingen → Applicatie → E-mail** een andere mailserver, anders worden er geen e-mails meer verstuurd. ==== Hoe MasterKey het clientgeheim bewaart ==== * Het clientgeheim wordt bij het opslaan direct versleuteld (AES-256-GCM) en alleen versleuteld in de database van MasterKey bewaard, bij de instellingen van uw organisatie. * De sleutel waarmee het geheim versleuteld is, staat niet in de database maar apart, in een afgeschermde omgeving van de MasterKey-servers. Met alleen een kopie van de database is het geheim dus niet te lezen. * Het geheim wordt nooit teruggestuurd naar de browser en komt niet in logbestanden. * Alleen de mailservice van MasterKey ontsleutelt het geheim, en alleen op het moment van versturen. ==== Veelvoorkomende meldingen ==== ^ Melding bevat ^ Oorzaak ^ | AADSTS7000222 | Het clientgeheim is verlopen. Maak een nieuw geheim aan (stap 7). | | AADSTS7000215 | Het clientgeheim is onjuist; vaak is de //Geheim-ID// ingevuld in plaats van de **Waarde**. | | AADSTS700016 | De Application (client) ID bestaat niet in deze Microsoft 365-omgeving. | | AADSTS90002 | De Directory (tenant) ID bestaat niet. | | ErrorAccessDenied / AccessDenied | De app heeft geen toestemming voor deze mailbox (stap 5). Net gewijzigd? Wacht tot 2 uur. Gaat het alleen mis bij grote bijlagen, dan ontbreekt Mail.ReadWrite. | | ErrorInvalidUser / MailboxNotEnabledForRESTAPI / ResourceNotFound | De mailbox bestaat niet of is geen Exchange Online-mailbox. | | ErrorMessageSizeExceeded | De e-mail is groter dan de mailbox mag versturen. Verhoog de maximale verzendgrootte van de mailbox. | Komt u er niet uit? Neem contact op met MasterKey support en stuur de volledige melding mee. Stuur **nooit** het clientgeheim mee. ---- [[nl:desktop:instellingen:applicatie|Terug naar Instellingen: Applicatie]] \\ [[nl:desktop:instellingen|Terug naar Instellingen]]