Overview

Okta strives to deliver the most secure integrations for our customers. To this effect, Okta is introducing a stronger and more resilient way to federate Office 365 with Okta using the recommended Microsoft Graph framework. This change aligns with Microsoft’s plans to deprecate Azure AD Graph and MSOnline PowerShell cmdlets. 
 

To take advantage of this newer integration, Customers must follow the required actions detailed below to migrate their Office 365 Single Sign-on applications federated using the Manual with PowerShell option. 

NOTE:

• It is highly recommended that this update be made as soon as possible, well before the beginning of March, as a proactive measure to prevent any complications.
  • This will ensure that customers are prepared ahead of the change and that they comply with the upcoming Microsoft updates to avoid any service disruption.
  • Taking action beforehand is necessary because the configuration could be tricky and time-consuming. This would ensure that customers have ample time for planning and testing to ensure a smooth transition from MSOnline to MS Graph.
• By March 30, 2025: Microsoft will end support for deprecated MS OnlinePowerShell cmdlets, which might impact the Single Sign-on integrations. 
• For customers who federate Office 365 with Okta using Automatic, please click here to follow the migration guide. 

Prerequisites

• An Office 365 application that uses Manual with PowerShell configuration for Single Sign-On. 
• Run the PowerShell command get-module to check which PowerShell module (MSGraph or MSOL) is already installed. If neither is present, follow the Microsoft Guide to install MSGraph, as Microsoft is actively phasing out the MSOL module
• An App Administrator role in Okta to migrate the Issuer URI format of Office 365 Single Sign-on applications. 
• A Global Administrator role in Microsoft to run the PowerShell scripts and update the domain federation settings. 
• An Org Administrator role in Okta to mark it complete from the UI.

Update O365 Apps to New IssuerUri format

Follow the steps or the video below:

1. Download the attached zip file 
2. Unzip it to view verification and migration scripts.  
3. Run the verification script* in PowerShell to check domains for which the Issuer URI format is in the older format. This will generate three CSV files:
   • O365DomainsToBeMigrated.csv: contains a list of domain names with Issuer Uri that need to be migrated.
   •  O365DomainsToBeMigrated_failed.csv: contains a list of domain names that could not be migrated and must be manually verified.
   • O365DomainsToBeMigrated_Exceptions.csv: contains the details on why the domains could not be verified. 

NOTE: For GCC High customers, run the PowerShell script with -GCCHigh as a suffix to the script name. For example: O365_IssuerUri_Verify_Msol.ps1 -GCCHigh
 

4. Ensure all the domains listed in the “O365DomainsToBeMigrated” file are federated using Manual with PowerShell. If any domains use Automatic configuration, remove them from the file before running the migration script.  
5. Run the migration script** in PowerShell to automatically update the domains' Issuer URI format to the supported version. This will generate three CSV files:
   • O365DomainMigration_Success.csv: contains the list of domains that were successfully updated. 
   • O365DomainMigration_Failed.csv: contains the list of domains that could not be updated.
   • O365DomainMigration_Exceptions.csv: provides the details of the error. 

NOTE: For GCC High customers, run the PowerShell script with -GCCHigh as a suffix to the script name. For example, O365_IssuerUri_Migrate_Msol.ps1 -GCCHigh
 

6. Before proceeding further, ensure that all the domains are successfully migrated and validate whether the Issuer URI is updated by running the following command:
   • Get-MsolDomainFederationSettings -DomainName {domain name}

If using MSGraph, use the following command:

6. • Get-MgDomainFederationConfiguration -DomainId {domain name}
7. Log in to Okta Admin Console.
8. On the Applications page, click the Migrate Format button.

NOTE: Please ensure to complete the above steps for all of the Office 365 WS-Fed manual instances before proceeding with the Migrate Format action. Failing to do so could negatively impact other Office 365 WS-Fed manual instances.

9. Check the box and click the Migrate Format button. 

Contact Okta Support

For any issues related to IssuerUri migration, contact Okta Support.

NOTE: It is recommended to do the update from MSol to Microsoft Graph outside of business hours due to potential downtime depending on the number of users on the federated domain.

*   Use the Verify script from the attached file
** Use the Migrate script from the attached file

Related References

• Frequently Asked Questions on PowerShell Deprecation for Azure AD, Azure AD-Preview, and MS Online
• Update Office 365 Applications with Provisioning to Support Microsoft Graph
• Update Office 365 Single Sign-on Applications with Automatic Configuration to Support Microsoft Graph
• Frequently Asked Questions about Mandatory MFA Requirements for Microsoft Applications