Stacked Identities

A Practical Guide to Integrating On-Prem Exchange Server (Outlook Web App) with Okta (WS-Fed)

—

by

Rohith Udupa
in ,

Integrating on-premises Exchange Server with Okta using WS-Federation (WS-Fed) is a great way to centralize authentication and provide SSO for your users. However, Exchange’s architecture means you can’t just “turn it on everywhere” without first understanding how your environment is built.

Step 1: Understand the Exchange Infrastructure

Before any configuration, you need a clear map of your Exchange environment:

  1. Number of Exchange Servers (nodes)
    • Setting up the WS-Fed URL, audience, and certificate is global — it applies to the entire organization.
    • Enabling WS-Fed authentication is per server — you choose on which servers WS-Fed actually handles logins.
  2. Role of Each Server
    • Identify which servers handle end-user traffic (/owa) and which handle administrator traffic (/ecp).
    • /ecp = Admin Control Panel endpoint
    • /owa = Outlook Web Access endpoint for end users
  3. Load Balancer Design
    • Understand how traffic is routed between servers.
    • If admin and user traffic share the same server without planning, WS-Fed can cause admin login issues.

Key Principle: WS-Fed configuration is applied centrally for all servers, but actual WS-Fed authentication is enabled individually per server.

Step 2: Plan Your WS-Fed Deployment Strategy

Option A: Split End-User and Admin Servers

  • Server 1 & Server 2: Handle /owa and /ecp for end users → Enable WS-Fed
  • Server 3: Admin-only (/ecp) with basic authentication → Do NOT enable WS-Fed
  • Load balancer ensures admin /owa traffic never hits WS-Fed-enabled servers.

Option B: WS-Fed Everywhere

  • If administrators are fine with WS-Fed, enable it on all servers.

Step 3: Create WS‑Fed applications in Okta

Purpose: Create two WS-Fed apps (one for /owa, one for /ecp) and ensure they share the same signing certificate.

GET {{OKTA_BASE_URL}}/api/v1/apps/{{OWA_APPID}}
# Retrieves the OWA app configuration including signing cert kid

POST {{OKTA_BASE_URL}}/api/v1/apps/{{OWA_APPID}}/credentials/keys/{{OWA_KID}}/clone?targetAid={{ECP_APPID}}
# Clones OWA cert to the ECP app

PUT {{OKTA_BASE_URL}}/api/v1/apps/{{ECP_APPID}}
# Updates ECP app to use the cloned cert
Import Okta WS‑Fed signing cert on Exchange & get thumbprint

Purpose: Install the Okta signing cert into the Exchange server’s local machine store.

Import-Certificate -FilePath C:\temp\okta-wsfed-signing.cer -CertStoreLocation Cert:\LocalMachine\My
Import-Certificate -FilePath C:\temp\okta-wsfed-signing.cer -CertStoreLocation Cert:\LocalMachine\Root

Set-Location Cert:\LocalMachine\Root; Get-ChildItem | Sort-Object Subject
# Lists all trusted root certs so you can copy the Okta cert thumbprint

Step 4: Configure claims (GLOBAL)

Purpose: Sets the global WS-Fed issuer, audience URIs, and signing cert for the entire Exchange organization.

Set-OrganizationConfig `
  -AdfsIssuer "https://<okta-tenant>/app/template_wsfed/<appId>/sso/wsfed/passive" `
  -AdfsAudienceUris "https://mail.contoso.com/owa/","https://mail.contoso.com/ecp/" `
  -AdfsSignCertificateThumbprint "<THUMBPRINT>"

Output: No output if successful.

Step 5: Discover current virtual directories & auth

Purpose: Lists current authentication settings for all OWA and ECP directories.

Get-OwaVirtualDirectory | fl Identity,AdfsAuthentication,BasicAuthentication,FormsAuthentication,WindowsAuthentication,OAuthAuthentication
Get-EcpVirtualDirectory | fl Identity,AdfsAuthentication,BasicAuthentication,FormsAuthentication,WindowsAuthentication,OAuthAuthentication

Output Example:

Identity            : SERVER1\owa (Default Web Site)
AdfsAuthentication  : False
BasicAuthentication : True
FormsAuthentication : True
WindowsAuthentication: False
OAuthAuthentication : False

Step 6: Enable WS‑Fed (AD FS) auth for a specific directory

Purpose: Enables WS-Fed and disables other auth methods for a specific /owa or /ecp directory.

Set-EcpVirtualDirectory -Identity "SERVER1\ecp (Default Web Site)" -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false
Set-OwaVirtualDirectory -Identity "SERVER1\owa (Default Web Site)" -AdfsAuthentication $true -BasicAuthentication $false -DigestAuthentication $false -FormsAuthentication $false -WindowsAuthentication $false -OAuthAuthentication $false

Output: No output if successful.

Verify changes

Get-OwaVirtualDirectory -Identity "SERVER1\owa (Default Web Site)" | fl Identity,AdfsAuthentication,BasicAuthentication,FormsAuthentication,WindowsAuthentication,OAuthAuthentication
Get-EcpVirtualDirectory -Identity "SERVER1\ecp (Default Web Site)" | fl Identity,AdfsAuthentication,BasicAuthentication,FormsAuthentication,WindowsAuthentication,OAuthAuthentication

Step 7: Restart IIS on Exchange

Purpose: Applies changes by restarting IIS services.

net stop w3svc /y
net start w3svc

Output:

The World Wide Web Publishing Service service was stopped successfully.
The World Wide Web Publishing Service service was started successfully.

Step 8: Test Authentication

Purpose: Confirm that /owa and /ecp now redirect through Okta WS-Fed.

# Test authentication for OWA (end-user portal)
Start-Process "https://mail.contoso.com/owa/"

# Test authentication for ECP (admin portal)
Start-Process "https://mail.contoso.com/ecp/"

Expected Result:

  • Accessing /owa or /ecp should redirect you to the Okta login page.
  • After successful Okta authentication, you should be returned to the respective Exchange page with valid session access.
,

Comments

Leave a comment