Exchange Online PowerShell -Credential retirement: migrate ROPC scripts

The -Credential parameter is being removed from Connect-ExchangeOnline and Connect-IPPSSession: ExchangeOnlineManagement module versions released in December 2026 or later won't include it, according to Message center post MC1248389 (updated 15 July 2026). Scripts that pass a PSCredential object fail at the connection step as soon as they load a new module, and Microsoft plans a later server-side retirement that will break the flow on older versions too. Move interactive admins to modern sign-in with MFA, automation outside Azure to certificate-based app-only authentication, and automation inside Azure to a managed identity.

Who this is for and what you will have

This guide is for Exchange Online and Microsoft Purview administrators who own PowerShell scripts, scheduled tasks or runbooks that connect with a username and password. At the end you will have:

• An inventory of scripts and accounts that use -Credential.
• The right replacement chosen for each one.
• Working, tested connection commands for Exchange Online and Security & Compliance PowerShell.
• A short-term version pin for anything that can't move before December, with an end date.

What changes and when

For now the change is client-side and isn't applied automatically. A script keeps working as long as it loads a module version released before December 2026. The latest release documented on Microsoft Learn at the time of writing is 3.10.1, from July 2026.

Why it's happening

-Credential uses the resource owner password credentials (ROPC) flow: the script sends a username and password straight to Microsoft Entra ID. ROPC doesn't support multifactor authentication, so it can't meet MFA or Conditional Access requirements. Microsoft is making MFA mandatory, and the Microsoft Authentication Library (MSAL) deprecated ROPC starting with version 4.74.0.

Who is affected

Anyone who runs Connect-ExchangeOnline -Credential or Connect-IPPSSession -Credential. Typical cases are scheduled reports on a jump server, runbooks that read a stored credential asset, and older scripts copied from the remote PowerShell era. Organizations that don't use the parameter don't need to do anything.

A specific risk is automatic module updates. If a server installs the newest ExchangeOnlineManagement on a schedule, a December release will break every script on it at once.

How to check whether you're affected

Search your scripts

On every machine and repository that holds automation, search for the pattern:

Get-ChildItem -Path 'D:\Scripts' -Recurse -Include *.ps1,*.psm1 |
    Select-String -Pattern 'Connect-(ExchangeOnline|IPPSSession).*-Credential'

Also search for Get-Credential, Import-Clixml and PSCredential near connection code, because some scripts build the credential in one line and connect in another. In Azure Automation, look for runbooks that call Get-AutomationPSCredential before connecting. Don't forget scripts inside scheduled tasks, CI pipelines and third-party tools that wrap the module.

Check the module version in use

Get-InstalledModule ExchangeOnlineManagement

Note every machine that auto-updates modules.

Check sign-in logs

The service accounts these scripts use leave a trail in Microsoft Entra sign-in logs. Microsoft Graph documents an authenticationProtocol property on sign-in events whose values include ropc, and the sign-in logs in the Microsoft Entra admin center have an Authentication Protocol filter. Filter the logs for each suspected service account and look at the protocol of its sign-ins. Microsoft's Exchange documentation doesn't describe a dedicated report for -Credential use, so treat the logs as a cross-check, not a complete list.

Choose the replacement

Two documentation details shape the choice. First, the Connect-IPPSSession syntax on Microsoft Learn has no ManagedIdentity or Device parameter, so unattended Security & Compliance scripts need certificate-based app-only authentication even when they run in Azure. Second, Microsoft removed secret-based app-only authentication from its recommendations in March 2026, so don't swap a password for a client secret.

Option 1: Interactive sign-in with MFA

Replace the credential with the account name. The module opens a modern sign-in, where MFA and Conditional Access apply:

# Before
$UserCredential = Get-Credential
Connect-ExchangeOnline -Credential $UserCredential
 
# After
Connect-ExchangeOnline -UserPrincipalName [email protected]
Connect-IPPSSession -UserPrincipalName [email protected]

From version 3.7.0, the module uses Web Account Manager (WAM) on Windows by default. If sign-in fails with WAM-related errors, Microsoft documents -DisableWAM (3.7.2-Preview1 or later) as the workaround.

On a server core installation or over SSH, use device code sign-in in PowerShell 7:

Connect-ExchangeOnline -Device

The command prints https://microsoft.com/devicelogin and a code. Open the URL on any device with a browser, enter the code and sign in. Some organizations block device code flow with a Conditional Access authentication flows policy; if yours does, use a machine with a browser or app-only authentication instead.

Option 2: Certificate-based app-only authentication

This is the main replacement for scheduled scripts outside Azure. The full setup, including certificate requirements and least-privilege roles, is in Run unattended Exchange Online PowerShell with app-only certificate auth. In summary:

1. Register a single-tenant app in Microsoft Entra ID and copy the Application (client) ID.
2. Under API permissions, add Office 365 Exchange Online > Application permissions > Exchange.ManageAsApp and grant admin consent.
3. Create a certificate (a self-signed one is supported), upload the public .cer under Certificates & secrets, and install the private key on the machine that runs the script.
4. Assign the app a supported Microsoft Entra role, such as Exchange Recipient Administrator or Global Reader, or add its service principal to an Exchange role group. For Security & Compliance PowerShell, assign a role such as Compliance Administrator.

Then change the connection line. These are Microsoft's documented examples:

# Exchange Online, certificate in the Windows certificate store
Connect-ExchangeOnline -AppId <%App_id%> -CertificateThumbprint <%Thumbprint string of certificate%> -Organization "contoso.onmicrosoft.com"
 
# Security & Compliance, same app and certificate
Connect-IPPSSession -AppId <%App_id%> -CertificateThumbprint <%Thumbprint string of certificate%> -Organization "contoso.onmicrosoft.com"
 
# Either cmdlet, certificate loaded at run time (for example from Azure Key Vault)
Connect-ExchangeOnline -AppId <%App_id%> -Certificate <%X509Certificate2 object%> -Organization "contoso.onmicrosoft.com"

-CertificateThumbprint works only on Windows. -Organization must be the tenant's primary .onmicrosoft.com domain. Microsoft also documents -CertificateFilePath with -CertificatePassword, but notes there's no automated and secure way to supply the password for a local certificate file, so prefer the certificate store or a vault.

Not every cmdlet supports app-only authentication. Microsoft documents that Purview eDiscovery cmdlets such as New-ComplianceSearch don't, and the Exchange Team said in comments on its announcement that Security & Compliance cmdlets that don't work in app-only mode won't be supported for automation. Test each cmdlet your script uses before switching.

Option 3: Managed identity in Azure

If an Exchange Online script already runs in Azure Automation or on an Azure VM, a managed identity removes the certificate as well. Microsoft's documented steps for a system-assigned identity are:

1. Enable the system-assigned managed identity on the Automation account or VM.
2. Store its object ID: $MI_ID = (Get-AzADServicePrincipal -DisplayName "ContosoAzAuto1").Id.
3. Import the ExchangeOnlineManagement module into the Automation account (or install it on the VM).
4. Grant Exchange.ManageAsApp to the identity with Microsoft Graph PowerShell:

Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All,Application.Read.All
 
$AppRoleID = "dc50a0fb-09a3-484d-be87-e023b12c6440"
$ResourceID = (Get-MgServicePrincipal -Filter "AppId eq '00000002-0000-0ff1-ce00-000000000000'").Id
 
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $MI_ID -PrincipalId $MI_ID -AppRoleId $AppRoleID -ResourceId $ResourceID

5. Assign a supported Microsoft Entra role to the identity:

Connect-MgGraph -Scopes RoleManagement.ReadWrite.Directory
 
$RoleID = (Get-MgRoleManagementDirectoryRoleDefinition -Filter "DisplayName eq 'Exchange Recipient Administrator'").Id
New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $MI_ID -RoleDefinitionId $RoleID -DirectoryScopeId "/"

6. Make the connection the first command in the runbook:

Connect-ExchangeOnline -ManagedIdentity -Organization contoso.onmicrosoft.com
Get-AcceptedDomain | Format-Table Name

For a user-assigned identity, store its client ID with (Get-AzUserAssignedIdentity -Name "ContosoMI1" -ResourceGroupName "ContosoRG2").ClientId and add -ManagedIdentityAccountId with that value. Managed identity can't be used locally on your own computer; it only works inside the Azure resource. Microsoft also notes that New-UnifiedGroup, Remove-UnifiedGroup, Add-UnifiedGroupLinks and Remove-UnifiedGroupLinks don't work with managed identity connections, and points to Microsoft Graph for those tasks.

Test before you cut over

1. Run the new connection in a test session and confirm Get-ConnectionInformation returns your tenant.
2. Run every cmdlet the script uses, including write cmdlets against a test object, under the new identity. Missing role permissions show up here, not at connection time.
3. For app-only and managed identity connections, check the Service principal sign-ins or Managed identity sign-ins in the Entra sign-in logs.
4. Run the scheduled task or runbook end to end once, and compare its output with the last run under -Credential.
5. Once it's stable, remove the old credential from the credential store or Automation asset, then disable or remove the service account's mailbox and role assignments if nothing else uses them.

Rollback and buying time

If a migration fails and the script must run tonight, keep the old version of the script and pin the module to a version released before December 2026, for example:

Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.10.1
Import-Module -Name ExchangeOnlineManagement -RequiredVersion 3.10.1

Turn off automatic module updates on that machine while the pin is in place. This is a temporary measure only: Microsoft says a server-side retirement will follow, and when it does, -Credential stops working with any module version. Record every pinned script with an owner and a migration date.

Troubleshooting

A parameter cannot be found that matches parameter name 'Credential'. This is PowerShell's standard message for a removed parameter, and it means a December 2026 or later module is loaded. Migrate the script, or pin an older version temporarily.

App-only connection prompts for sign-in in Connect-IPPSSession. Microsoft's documented workaround is to run $Global:IsWindows = $true before Connect-IPPSSession.

Connected, but a cmdlet isn't recognized. The role you assigned doesn't include it. Exchange Administrator covers all Exchange Online PowerShell tasks; Security Administrator doesn't include recipient management or anti-spam settings.

Managed identity connection fails with no service principal found. If Get-MgServicePrincipal -Filter "AppId eq '00000002-0000-0ff1-ce00-000000000000'" returns nothing, follow Microsoft's fix in the managed identity article: register an app and add the Exchange.ManageAsApp permission through the manifest so the Office 365 Exchange Online resource appears.

For other connection errors, see Fix Connect-ExchangeOnline errors.

Checklist

• Searched all script locations and runbooks for -Credential with either connect cmdlet.
• Listed machines that auto-update ExchangeOnlineManagement.
• Chose interactive, app-only certificate or managed identity for each script.
• Confirmed every Security & Compliance cmdlet you use supports app-only authentication.
• Tested each new connection and the full job.
• Removed stored passwords and unused service accounts.
• Pinned only what can't move yet, with an owner and an end date.

What we checked

• Opened MC1248389 on mc.merill.net on 2026-11-12: published 10 March 2026, last updated 15 July 2026, removal in module versions from December 2026, both cmdlets in scope, server-side retirement with no date.
• Read the Exchange Team blog post "Deprecation of the -Credential Parameter in Exchange Online PowerShell" (published 12 February 2026, updated 16 July 2026) for the ROPC, MFA and MSAL 4.74.0 reasoning and the three recommended replacements.
• Compared the syntax blocks of Connect-ExchangeOnline and Connect-IPPSSession on Microsoft Learn: ManagedIdentity, ManagedIdentityAccountId, Device and InlineCredential appear only on Connect-ExchangeOnline.
• Copied the certificate and managed identity commands exactly from the cmdlet examples and the managed identity article, including the Exchange.ManageAsApp role ID dc50a0fb-09a3-484d-be87-e023b12c6440.
• Confirmed on "What's new in the Exchange Online PowerShell module" that 3.10.1 (July 2026) is the latest documented release; no December 2026 release was listed on 2026-11-12.
• Confirmed the ropc value of authenticationProtocol on the Microsoft Graph signIn resource page.
• Not checked: the exact error text a December module returns for -Credential, because that version wasn't released yet; the message quoted in Troubleshooting is PowerShell's generic one. Not tested on a live tenant; steps follow Microsoft's documentation as of 2026-11-12.

Last tested: 2026-11-12

References

• MC1248389, Retirement of -Credential parameter when connecting to Exchange Online PowerShell: https://mc.merill.net/message/MC1248389
• Deprecation of the -Credential parameter in Exchange Online PowerShell (Exchange Team blog): https://techcommunity.microsoft.com/blog/exchange/deprecation-of-the--credential-parameter-in-exchange-online-powershell/4494584
• Connect-ExchangeOnline: https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/connect-exchangeonline
• Connect-IPPSSession: https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/connect-ippssession
• Use Azure managed identities to connect to Exchange Online PowerShell: https://learn.microsoft.com/en-us/powershell/exchange/connect-exo-powershell-managed-identity
• App-only authentication for unattended scripts: https://learn.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2
• What's new in the Exchange Online PowerShell module: https://learn.microsoft.com/en-us/powershell/exchange/whats-new-in-the-exo-module
• signIn resource type (Microsoft Graph beta): https://learn.microsoft.com/en-us/graph/api/resources/signin?view=graph-rest-beta