Federate multiple Office 365 domains in a single app instance

If you have existing Office 365 app instances, go to the Sign On tab, and then click EditSave. This allows Okta to capture the required domain mappings from Microsoft Entra ID. For the new app instances, this is captured automatically.

You can automatically federate multiple Microsoft Office 365 domains within a single Office 365 app instance in Okta. This eliminates the need to configure a separate Office 365 app instance for each Office 365 domain.

This is useful if you have the following configurations:

  • Multiple Office 365 domains in a single Office 365 tenant and you don't want to create a separate app instance for each domain.
  • Multiple Office 365 domains in a single Office 365 tenant and want to apply the same set of policies to all of them.

Before you begin

  • This feature isn't available for the manual WS-Federation method.

  • The following information is required to complete this procedure:

    • A valid Microsoft Office 365 tenant
    • Verified Microsoft Office 365 domains
    • Office 365 application added to Okta org using automatic WS-Federation

Start this procedure

This procedure includes the following tasks:

  1. Configure domains
  2. Validate federated domains

Configure domains

First-time setup

If you're configuring WS-Federation for the first time, follow these steps to authenticate and select domains.

  1. If you're setting up Microsoft Office 365 for the first time, in the General Settings tab, click Next to go to Sign-On Options tab.

  2. In the Sign on methods section, select WS-FederationAutomatic.
  3. Optional. Click View Setup Instructions. The procedure to configure Office 365 WS-Federation opens in a new window.
  4. Optional. Refer to the Prepare your domain for federated authentication section of the procedure to ensure that you have correctly prepared your domains for federation.
  5. Back on the Sign-On Options tab, click Start federation setup. You're redirected to the Microsoft account sign-in page.
    1. Sign in to Microsoft as a global administrator for your Microsoft tenant.
    2. Read and accept the requested permissions.
  6. Click Federate domains.
  7. On the dialog that appears, select the domains that you want to federate from the dropdown list.
  8. Click NextSave.
  9. Click Done.
Edit an existing configuration

If you've previously configured WS-Federation, follow these steps to make changes.

  1. Go to Office 365Sign onEdit. Ensure that WS-FederationAutomatic is selected in the Sign on Methods.

  2. To view federated parent and child domains in read-only mode, click View selected domains.
  3. To add or remove domains, click Manage verified domains.
  4. To re-authenticate with a different Microsoft Office 365 account, click Re-authenticate with Microsoft Account.
  5. Click Save.

You can add and manage multiple domains only through the WS-FederationAutomatic method. The Manual method does not support multiple domains.

Validate federated domains

  1. Sign in to Okta as an end user that belongs to an Office 365 domain you federated.
  2. Access Office 365 through the End-User Dashboard.
  3. Ensure that you can sign in successfully.
  4. Repeat these steps for test users from all federated Office 365 domains.

Alternatively, you can use the following PowerShell cmdlet for each federated domain to verify that the domain has been successfully federated:

Get-MSOlDomainFederatioNSettings -domainname <domain name>

If you enabled the MS Graph federation feature, use the following PowerShell cmdlet:

Get-MgDomainFederationConfiguration -DomainId <yourDomainName> | Select -Property FederatedIdpMfaBehavior

Cautions

  • Office 365 apps that have a federated domain with multiple subdomains in a single app can cause sign-in errors.

    Existing Office 365 apps with a federated domain with multiple subdomains in a single app cause the subdomain members to receive an error when they sign in. To avoid this, go to the Sign On tab, and then click EditSave. This allows Okta to capture the required domain mappings from Microsoft Entra ID.

  • Switching to manual WS-federation or SWA will unfederate domains

    If you switch from automatic WS-Federation to manual WS-Federation or from WS-Federation to SWA, all the domains involved will be unfederated.

  • Don't delete Office 365 app instances

    If you have multiple instances of Office 365 domains that are automatically federated and you're migrating to a single instance of automatically federated Office 365, disable such instances. Don't delete them.

  • When unfederating, wait until all domains are unfederated

    If you change the federation method from automatic to manual for already-federated domains, Okta recommends that you wait until all automatically federated domains are unfederated. If you try to manually federate a domain before Okta completes its unfederation process, Okta may try to remove the manually federated domain since it was previously an automatically federated domain.

    Use the following cmdlet to ensure that the automatically federated domain is unfederated:

    Get-MSOlDomainFederatioNSettings -domainname <domain name>

    If you enabled the MS Graph federation feature, use the following PowerShell cmdlet:

    Get-MgDomainFederationConfiguration -DomainId <yourDomainName> | Select -Property FederatedIdpMfaBehavior

    You should expect some downtime while the domain is being unfederated.

  • Configure domains during off-hours to avoid assigning duplicate apps

    When you configure an Office 365 domain that's already configured in a separate Office 365 app instance, end users may be assigned a duplicate set of Office 365 apps. Perform this action during off-hours so that you have enough time to unconfigure the original app instance.

Related topics