Exchange (on-prem) - Serval Documentation

This integration is available by request during preview. Contact your Serval team to enable it for testing.

About Exchange (on-prem)

The Exchange (on-prem) integration connects Serval to an on-premises Microsoft Exchange server - Exchange 2016, Exchange 2019, or Exchange Subscription Edition - using remote PowerShell (PSRP over WinRM) against the server’s /PowerShell virtual directory (for example, https://mail.corp.example.com/PowerShell). It is a separate integration from Exchange Online, which targets Microsoft 365 tenants: connecting one does not grant the other. Authentication: an approved Active Directory account (username and password) with Exchange management roles. The connection supports Kerberos, Negotiate, NTLM, and Basic authentication. Choose Kerberos for a /PowerShell virtual directory in Microsoft’s default configuration, which accepts Kerberos only; choose Negotiate or NTLM where your Exchange administrators have enabled NTLM on that directory, and Basic only over HTTPS. The Serval worker does not need to be domain-joined for Kerberos: it obtains tickets from your domain controllers with the account’s password. Worker requirements: an on-prem Exchange server lives on your private network, so this integration requires a hybrid (self-hosted) Serval worker with network reach to the server. Serval’s cloud workers cannot reach a private-network target. Data sync: On-demand only. There is no background sync, entity ingestion, or scheduled polling - each action opens a fresh remote PowerShell session against your server, runs, and disconnects.

Operations run as structured cmdlet pipelines, not free-form scripts. The Exchange remote PowerShell endpoint is a NoLanguage constrained runspace - it only accepts Exchange cmdlet invocations, so arbitrary PowerShell script text (variables, loops, expressions) is rejected by the server itself.

Set up the account

Choose an approved account

Choose an Active Directory identity your organization approves for automation. A dedicated service account is optional; a named account can also authenticate. Grant only the management roles your workflows need.

Assign Exchange management roles

Add the account to the Exchange role group(s) that cover the operations your workflows need - Recipient Management covers common mailbox and distribution-group administration. Use the Exchange admin center (Permissions → Admin roles) or the Exchange Management Shell:

Add-RoleGroupMember -Identity "Recipient Management" -Member "svc-serval"

The account must also have remote PowerShell access enabled. Verify RemotePowerShellEnabled with Get-User -Identity "svc-serval" | Format-List RemotePowerShellEnabled.

Verify remote PowerShell access

From a domain-joined machine, confirm the account can open a session against the endpoint before involving Serval, using the same server name and authentication method the Serval connection will use:

$cred = Get-Credential   # enter the approved account credentials
New-PSSession -ConfigurationName Microsoft.Exchange `
  -ConnectionUri https://mail.corp.example.com/PowerShell `
  -Authentication Kerberos -Credential $cred

If this fails, fix the account, roles, or endpoint configuration first. Use -Authentication Negotiate only when the connection will use Negotiate or NTLM: a Windows client’s Negotiate can pick Kerberos, so it does not prove that NTLM is enabled on the endpoint. Run the Serval connection healthchecks from the intended worker as well.

Prepare for Kerberos authentication

Review these items with your directory and network teams before connecting with Kerberos. They apply in addition to the account setup above.

Network: TCP port 88 (or the port you give in the KDC list) from the Serval worker’s egress addresses to the domain controllers you list as KDCs, or to any the DNS SRV records return, and TCP 80 or 443 to the Exchange server named in the Server URI.
Time: the worker nodes’ clocks within five minutes of the domain controllers, the Kerberos default tolerance.
Account keys: AES encryption types enabled on the account (msDS-SupportedEncryptionTypes), with a password set after AES was enabled. Windows updates from 2026 turn off RC4 for Kerberos ticket issuance by default.
Service principal: a Kerberos ticket names the host in the Server URI. An Exchange server’s own fully qualified name works by default, because its HTTP/ name maps to the computer account. A load-balanced name such as mail.corp.example.com needs an alternate service account credential carrying http/mail.corp.example.com (Microsoft: “Configure Kerberos authentication for load-balanced Client Access services”); otherwise point the Server URI at one server’s fully qualified name.
Certificate for a per-server target over HTTPS: the server’s certificate must include the server’s own name. If it covers only the load-balanced name, use http:// with Kerberos message encryption (Microsoft’s documented form, TCP 80) instead of skipping certificate verification.
Extended Protection: Microsoft sets Extended Protection to Off on the front-end /PowerShell virtual directory. Serval sends channel bindings with its Kerberos tokens over HTTPS; if your administrators enabled Extended Protection there, a load balancer that terminates TLS with a different certificate than the server will make Kerberos fail.

The Serval worker keeps the Kerberos ticket in memory for the life of a single command run and writes no ticket or keytab to disk. The Kerberos configuration for the run is a small file (the realm and the KDC list) in a private temporary directory that the worker removes when the run ends; a removal that fails is logged rather than failing the run. Each run obtains one ticket-granting ticket with the account’s password, so a wrong password costs one logon per run, not one per request.

Connect in Serval

Open the Exchange (on-prem) connect form

In Serval, open the Exchange (on-prem) integration and start a new connection.

Enter the server and credentials

Server URI (required) - the URL of your Exchange server’s PowerShell virtual directory, e.g. https://mail.corp.example.com/PowerShell. Must be an http:// or https:// URL. With Kerberos, http:// is acceptable because the session is encrypted with the Kerberos session key, the form Microsoft documents for remote Exchange PowerShell; Basic requires https://. Enter the final PowerShell URL: a Kerberos connection does not follow redirects.
Username (required) - the approved account, as CORP\svc-serval or svc-serval@corp.example.com. For Kerberos, the UPN form carries its own realm; the CORP\svc-serval form needs the Kerberos Realm field.
Password (required) - the account’s password.

Choose an Authentication Method

Negotiate (NTLM) - the default; authenticates with NTLM, so NTLM must be enabled on the /PowerShell virtual directory.
NTLM - force NTLM explicitly.
Basic (requires HTTPS) - sends credentials directly; Serval refuses Basic over plain http:// because the credentials would travel unencrypted.
Kerberos - authenticates with a Kerberos ticket obtained from your domain controllers with the account’s password. Choose it for a /PowerShell virtual directory in Microsoft’s default configuration. Selecting it shows two more fields, described in the next step.

Fill in the Kerberos fields (Kerberos only)

Kerberos Realm - your Active Directory Kerberos realm in upper case, for example CORP.EXAMPLE.COM. Required when the username is CORP\svc-serval or svc-serval; optional for svc-serval@corp.example.com, where it defaults to the upper-cased suffix.
Kerberos KDCs (Optional) - comma-separated domain controllers, each a host name or IPv4 address with an optional :port (default 88), up to 16. Leave blank to discover them through DNS SRV records (_kerberos._tcp.corp.example.com), which requires the worker’s DNS resolver to serve your domain.

The service principal Serval asks for is always HTTP/ followed by the Server URI host, so the Server URI must name a host that holds that principal; an Exchange server’s own fully qualified name does by default. The endpoint must answer an unauthenticated request with a 401 Kerberos challenge; Serval refuses an endpoint that answers without challenging, because no Kerberos exchange would have taken place.

Name the connection (optional)

Instance Name (Optional) - a friendly name for this connection. If left blank, the connection is named after the server’s host name.

Skip TLS certificate verification is available for servers with self-signed certificates. It weakens transport security - prefer mounting a PEM CA bundle and setting REQUESTS_CA_BUNDLE in the worker environment while leaving verification on.

The connection healthchecks query Get-Recipient, Get-Mailbox, and Get-DistributionGroup with a one-item limit. The account needs these read cmdlets in its role assignments; the connection check does not require organization configuration permissions.

SecureString parameters

Commands such as New-RemoteMailbox require a PowerShell SecureString for their password parameter. Use microsoft.powershell.exchangeOnPrem.secureString(value) as the parameter value in a structured pipeline. The runner negotiates a PSRP session key and encrypts this value in the protocol’s SecureString format. The wrapper selects a wire type; it does not make workflow inputs secret or prevent them from being persisted. Do not put passwords directly in workflow source or assume this wrapper redacts them from workflow history. Use your approved workflow secret-handling mechanism. The password for a new AD user is separate from the credentials used to connect to Exchange.

Operation results

Typed actions fail when Exchange reports an error, including non-terminating PowerShell errors. The raw pipeline action returns errors and hadErrors; check both before using its output. Runner output is limited to 32 MiB; narrow large queries or select fewer properties. A timeout or an error does not roll back changes already applied on the Exchange server. Check the current state before retrying a write. getDistributionGroup reads group metadata without enumerating members. Use getDistributionGroupMembers when you need the membership list. Group writes normally require the account to be listed in the group’s ManagedBy owners. For an approved non-owner administrator, set bypassSecurityGroupManagerCheck: true on the update, delete, add-member, or remove-member action. Exchange still requires the Security Group Creation and Membership role and the applicable recipient scope; this option does not bypass RBAC. Group notes (including the description alias) are updated through Set-Group. When you also update mail settings, the helper issues separate commands; they are not atomic.

Gotchas and troubleshooting

401 Unauthorized when connecting

The server rejected the credentials or the account lacks remote PowerShell access. Verify the username and password, confirm the account has the required Exchange roles and RemotePowerShellEnabled is enabled, and check that the chosen authentication method is enabled on the PowerShell virtual directory in IIS. If the directory offers only Kerberos (Microsoft’s default for the front-end /PowerShell directory), switch the Authentication Method to Kerberos. With Kerberos, a 401 after a ticket was issued usually means the server could not accept the ticket: check that the service principal for the Server URI host belongs to the account the server uses, or point the Server URI at one server’s fully qualified name.

403 Forbidden

Some endpoints, often a load-balanced name, answer 403 to an unauthenticated request and never send a WWW-Authenticate challenge, so the connection fails before any credential is sent. With Kerberos, the error says which side of the Kerberos token the 403 fell on. “Before any Kerberos token was sent” means the endpoint never challenged: point the Server URI at an individual Exchange server that challenges, typically the server’s own fully qualified name, and ask your Exchange administrator which server names accept Kerberos for remote PowerShell. “After the Kerberos token was sent” means the endpoint refused the authenticated account: check remote PowerShell access and role membership.

Kerberos errors and what to check

The connection healthcheck reports “Kerberos authentication failed” with a short hint when it recognizes the message, followed by the Kerberos library’s own text. The library text often includes the account or service principal it was working on and ends with a numeric code:

Message	What to check
Cannot contact any KDC	Network path from the worker to the KDCs on TCP port 88 or the port you listed; the KDC list in the connection settings
Cannot find KDC for realm	No KDC list and DNS discovery found none: fill in the KDC list or check the worker’s DNS
Clock skew too great	Time synchronization on the worker nodes
Server HTTP/host@REALM not found in Kerberos database	The host in the Server URI has no service principal: point the Server URI at one server’s fully qualified name; a load-balanced name needs a service principal your Exchange administrators register for it
Server krbtgt/DOMAIN@REALM not found in Kerberos database	The Server URI host is outside your realm’s DNS domain; use a server name under it
Preauthentication failed, or Decrypt integrity check failed	The password in the connection settings
Client ‘user@REALM’ not found in Kerberos database	The username and the Kerberos realm
Password has expired	Set a new password and update the connection
KDC policy rejects request	The account’s authentication policy or silo, with your identity team
KDC has no support for encryption type	AES keys on the account
Failed to authenticate the user user@REALM with kerberos	The server did not accept the ticket: the service principal for the Server URI host, or point the Server URI at one server’s fully qualified name (see the 401 entry above)
The endpoint answered (status) without a Kerberos challenge	The endpoint accepted the request before any Kerberos exchange, so Serval refused the session; confirm the Server URI is the Exchange PowerShell directory and that the directory requires Kerberos
The server accepted the Kerberos token without completing mutual authentication	The server answered without the token that proves its identity, so Serval refused the session; review the endpoint’s Kerberos configuration with your Exchange administrator
Code: 403 … the endpoint answered 403 before any Kerberos token was sent	The endpoint never challenged (see the 403 entry above)
Code: 403 … the endpoint answered 403 after the Kerberos token was sent	The endpoint refused the authenticated account: remote PowerShell access and role membership (see the 403 entry above)
The endpoint redirected (status) to (URL); a Kerberos token is bound to the URL it was issued for	Enter the final PowerShell URL as the Server URI; a Kerberos connection does not follow redirects
Kerberos realm is required unless the username is a UPN	Fill in Kerberos Realm, or use the account’s UPN as the username
Kerberos username must be `user@corp.example.com`, `DOMAIN\user` or a bare account name without spaces	Enter the username in one of those three forms
Kerberos libraries are not available in this worker image	Upgrade the self-hosted worker to a release that includes Kerberos support
Exchange on-prem integration has an invalid connection configuration (with Kerberos selected)	The self-hosted worker predates Kerberos support; upgrade it before using this method

Connection refused or timeout

The worker can’t reach the server. The hybrid worker needs network egress to the Exchange server’s host and port - check firewalls and routing, and make sure the worker’s Kubernetes NetworkPolicy allows egress to your private CIDR ranges (cluster policies often allow only public internet egress by default). With Kerberos, the worker also needs TCP port 88 to the domain controllers; a blocked port, or a controller that accepts the connection but never answers, shows as “Cannot contact any KDC” within about 20 seconds of the unanswered request. A run the worker had to stop at its deadline names the last step it reached (reading the payload, the Kerberos logon, the WSMan connection, the runspace, the pipeline) in the error details.

TLS certificate errors

The Exchange server presents a certificate the worker doesn’t trust - typically a self-signed or internal-CA certificate. Mount a PEM CA bundle in the worker and set REQUESTS_CA_BUNDLE to its path, or enable Skip TLS certificate verification on the connection if you accept the weaker transport security. For a Kerberos connection to an individual server whose certificate names only the load-balanced address, prefer http:// with Kerberos message encryption over skipping verification.

Arbitrary PowerShell script is rejected

The Exchange remote endpoint is a NoLanguage constrained runspace: it accepts Exchange cmdlet invocations with parameters, but no script syntax (variables, loops, expressions). Serval sends operations as structured cmdlet pipelines for this reason - compose multiple cmdlets rather than writing a script.

Exchange (on-prem) and Exchange Online are separate integrations

This integration targets your on-premises servers over PSRP/WinRM; Exchange Online targets Microsoft 365 with an Entra app registration. In hybrid organizations, on-prem-synced recipients must be changed on-prem - cloud writes to synced objects fail.

Need help? Contact support@serval.com for assistance with your Exchange (on-prem) integration.

​About Exchange (on-prem)

​Set up the account

​Prepare for Kerberos authentication

​Connect in Serval

​SecureString parameters

​Operation results

​Gotchas and troubleshooting

About Exchange (on-prem)

Set up the account

Prepare for Kerberos authentication

Connect in Serval

SecureString parameters

Operation results

Gotchas and troubleshooting