Skip to main content

Configuring Email for PingCastle Enterprise

Email

PingCastle Enterprise sends email for password reset requests and notifications, including weekly reports. Configure email on Configuration > Settings > Email in the PingCastle Enterprise web interface.

note

Most changes on this screen take effect within about 30 seconds, without a restart. A few settings across the Settings UI require a restart, and PingCastle Enterprise schedules that restart automatically when needed.

Choosing an email provider

Select one of two providers under Email Provider:

  • SMTP — Sends email through a traditional SMTP server.
  • Microsoft Graph — Sends email through the Microsoft Graph API using OAuth 2.0 authentication. Choose this option for Office 365 environments that require modern authentication instead of a shared mailbox password.

Both providers share two common fields:

  • From Address — The email address that appears as the sender on messages PingCastle sends.
  • From Display Name — The display name that appears alongside the From address.

Configuring the SMTP provider

When you select SMTP as the email provider, configure these fields:

  • SMTP Host — The fully qualified domain name (FQDN) or IP address of the SMTP server.
  • SMTP Port — The port the SMTP server listens on. Common values are 25 (unencrypted), 465, and 587 (TLS/SSL).
  • SMTP Login — The username PingCastle uses to authenticate to the SMTP server. Leave this field blank if the server doesn't require authentication.
  • SMTP Password — The password for the SMTP login. Leave this field blank if the server doesn't require authentication.
  • Enable SSL — Encrypts the connection to the SMTP server. Enable this option when your SMTP server requires TLS/SSL, such as on port 465 or 587.

Configuring the Microsoft Graph provider

When you select Microsoft Graph as the email provider, configure these fields:

  • Tenant ID — The Entra ID tenant ID for your organization.
  • Client ID — The application (client) ID from the Entra ID app registration that PingCastle uses to send email.
  • Authentication Method — The credential type the app registration uses: a client secret or a certificate.
  • Client Secret — The application's client secret. This field applies only when you set Authentication Method to client secret.
  • Certificate fields (location, file, thumbprint, store location, and store name) — These fields apply only when you set Authentication Method to certificate. They identify which certificate PingCastle uses to authenticate.
note

See Modern authentication with Office 365 using Graph API for the full walkthrough on setting this up securely.

Notifications

Configuring the web host

Configure these fields on Configuration > Settings > Notifications:

  • Webhost — The base URL PingCastle Enterprise uses when it builds links in outgoing emails, such as links back to a report or the login page. Set this to the URL your users use to reach PingCastle Enterprise.

For example, if your PingCastle Enterprise instance is reachable at https://pingcastle.contoso.com, set Webhost to that address so email links resolve correctly for recipients.

Configuring reminders and the weekly report

PingCastle Enterprise can remind administrators before scheduled items expire and can send a weekly summary report. Configure these fields on Configuration > Settings > Notifications.

  • Default Domain Reminder Days — The number of days before an Active Directory domain's scheduled review that PingCastle sends a reminder email.
  • Default Entra Reminder Days — The number of days before an Entra ID tenant's scheduled review that PingCastle sends a reminder email.
  • Monday Hour — The hour of the day, on Mondays, when PingCastle sends the weekly report.

For example, setting Default Domain Reminder Days to 7 sends a reminder email one week before a domain's next scheduled review.

Modern authentication with Office 365 using Graph API

PingCastle Enterprise supports sending emails using Microsoft Graph API with modern authentication. Netwrix recommends this method for Office 365 environments, as it provides enhanced security through OAuth 2.0 authentication.

This configuration uses RBAC for Applications (Role-Based Access Control for Applications) in Exchange Online, which allows the application to send emails from a specific shared mailbox without requiring a user account with mailbox access permissions.

Prerequisites:

Before starting this configuration, ensure you have:

  • Global Administrator or Exchange Administrator permissions
  • Application Developer permissions in Entra ID
  • Exchange Online PowerShell module installed or use the Cloud Management Shell
  • Microsoft Graph PowerShell module installed (optional, for PowerShell automation)
note

This configuration uses "PingCastle-Email" throughout as an example name. You can substitute any name that fits your organization's naming conventions.

Create and Export Certificate (For Entra ID Certificate Authentication)

If you prefer certificate-based authentication instead of client secrets, use this PowerShell script to create and export a self-signed certificate:

# Create Self-Signed Certificate for use with Entra App Registration for dev environments.
$Name = "PingCastle-Email"
$password = "ENTER PASSWORD"

# Create a self-signed certificate
$cert = New-SelfSignedCertificate -Subject "CN=PingCastle-Email" -CertStoreLocation "Cert:\LocalMachine\My" -KeyExportPolicy Exportable

# Create a password for the PFX
$pwd = ConvertTo-SecureString -String $password -Force -AsPlainText

# Export the certificate as PFX
Export-PfxCertificate -Cert $cert -FilePath "$env:USERPROFILE\$Name.pfx" -Password $pwd

# Export the certificate as CER for Entra
Export-Certificate -Cert $cert -FilePath "$env:USERPROFILE\PingCastle-Email.cer" -Type CERT

Write-Output "Certificate exported to: $env:USERPROFILE\$Name.pfx"
warning

For production environments, use certificates issued by your organization's Certificate Authority (CA) instead of self-signed certificates.

Part 1: Create Entra ID app registration

Step 1: Access the Microsoft Entra admin center
  1. Open a web browser and navigate to https://entra.microsoft.com
  2. Sign in with your administrator account
  3. If you have access to multiple tenants, use the Settings gear icon in the top menu to switch to the correct tenant

Entra admin center homepage with Settings menu

Step 2: Navigate to app registrations
  1. In the left navigation pane, expand Identity
  2. Click Applications
  3. Select App registrations
  4. Click + New registration at the top of the page

App registrations page with New registration button

Step 3: Configure application registration
  1. In the Name field, enter: PingCastle-Email
  2. Under Supported account types, select Accounts in this organizational directory only
  3. Leave Redirect URI (optional) blank for now
  4. Click Register

Register an application form

Step 4: Create client secret
  1. In the left menu under Manage, click Certificates & secrets
  2. Click + New client secret
  3. Add a description: PingCastle-Email Secret
  4. Set expiration to 12 months (or as per your policy)
  5. Click Add
  6. Important: Copy the secret Value immediately - you won't see it again
  7. Paste it in Notepad or a password manager for later use
note

If you misplace your secret, you can return to this screen and generate a new one.

Client secrets page

Part 2: Create shared mailbox

Step 5: Access the Exchange admin center
  1. Navigate to https://admin.exchange.microsoft.com
  2. Sign in with your Exchange administrator account
  3. In the left navigation, expand Recipients
  4. Click Mailboxes

Exchange Admin Center navigation

Step 6: Create shared mailbox
  1. Click + Add a shared mailbox
  2. Fill in the following details:
    • Display Name: PingCastle
    • Email Address: pingcastle (the domain should auto-populate with your domain)
    • Alias: pingcastle (optional)
  3. Click Create

Add a shared mailbox form

Step 7: Verify shared mailbox creation
  1. Wait for the mailbox creation process to complete
  2. Verify the mailbox appears in the mailboxes list
  3. Note the full email address (e.g., pingcastle@yourdomain.com)

Mailboxes list showing the new shared mailbox

Step 8: Block shared mailbox sign-in

This should be automatically configured, but verify it:

  1. Navigate to https://entra.microsoft.com/
  2. Go to Users > All Users
  3. Search for and select the user account corresponding to the shared mailbox
  4. Click Edit Properties
  5. Click the Settings tab
  6. Ensure the Account Enabled checkbox is unchecked
  7. Click Save

User properties page with Account Enabled disabled

Part 3: Configure RBAC for applications

Step 9: Connect to Exchange Online PowerShell

Open Windows PowerShell as Administrator and run the following commands:

# Install Exchange Online Management module if not already installed
Install-Module -Name ExchangeOnlineManagement -Force -AllowClobber

# Import the module
Import-Module ExchangeOnlineManagement

# Connect to Exchange Online
Connect-ExchangeOnline
Step 10: Create service principal

Using the values from your app registration, create the service principal:

# Define variables (replace with your actual values)
$AppId = "YOUR_APPLICATION_CLIENT_ID"
$ObjectId = "YOUR_APPS_SERVICE_PRINCIPAL_OBJECT_ID" # Get this from the Enterprise Applications screen in Entra ID

# Create Service Principal
New-ServicePrincipal -AppId $AppId -ObjectId $ObjectId -DisplayName "PingCastle-Email"
note

The $ObjectId is the Service Principal Object ID from Enterprise Applications, not the Object ID from App Registrations.

Step 11: Create management scope

Create a management scope that restricts access to only the PingCastle shared mailbox:

# Create Management Scope
$EmailAddress = "pingcastle@yourdomain.com" # The email address of the shared mailbox
New-ManagementScope -Name "PingCastle-Email-Scope" -RecipientRestrictionFilter "EmailAddresses -eq '$EmailAddress'"
Step 12: Assign application role

Assign the Application Mail.Send role to the service principal with the custom scope:

# Create Role Assignment
$ExchangeSPObjectId = "" # The Exchange Service Principal Object Id (This is output in Step 10)
New-ManagementRoleAssignment -Role "Application Mail.Send" -App $ExchangeSPObjectId -CustomResourceScope "PingCastle-Email-Scope"

Part 4: Test configuration

Step 13: Test service principal authorization

Verify the configuration works correctly:

# Test Service Principal Authorization
$EmailAddress = "pingcastle@yourdomain.com" # The email address of the shared mailbox
$ExchangeSPObjectId = "" # The Exchange Service Principal Object Id (This is output in Step 10)

Test-ServicePrincipalAuthorization -Identity $ExchangeSPObjectId -Resource $EmailAddress

Expected Output:

  • RoleName: Application Mail.Send
  • InScope: True
Step 14: Verify scope restriction

Test that the service principal can't access other mailboxes:

# Test with a different email address
$EmailAddress = "otheruser@yourdomain.com" # A random email that the application should not be able to send as
$ExchangeSPObjectId = "" # The Exchange Service Principal Object Id (This is output in Step 10)

Test-ServicePrincipalAuthorization -Identity $ExchangeSPObjectId -Resource $EmailAddress

Expected Output:

  • InScope: False

This confirms the application can only send from the designated shared mailbox.

Entering the values in the Settings UI

After completing either the manual or PowerShell configuration, go to Configuration > Settings > Email and enter the values from your app registration:

  • Set Email Provider to Microsoft Graph.
  • Set From Address to the shared mailbox address (e.g., pingcastle@yourdomain.com).
  • Set Tenant ID and Client ID to the values from your Entra ID app registration.
  • Set Authentication Method to Client Secret or Certificate, matching how you created the app registration's credential.
    • For Client Secret, set Client Secret to the secret value you copied during app registration.
    • For Certificate, set the certificate location to File or Store, then fill in the matching fields: the certificate file path and password for File mode, or the thumbprint, store location, and store name for Store mode.