Troubleshooting O365 Provisioning Errors in a Cloud-Based Infrastructure

As simple as it sounds, there are many pitfalls when it comes to integrating your directory with Office 365. The bulk of these issues stems from the provisioning side of the integration by not matching up the correct unique identifiers in both of the user accounts. In some cases, O365 is not listing an Immutable ID for an end user or Office 365 is not recognizing a certain account from your cloud-based directory.

While this solution will only work for certain use cases, like the ones I mentioned above, this error is a common problem that you’ll run into if you’re finding provisioning issues with Office 365. I’ll walk you through the process of manually setting an Immutable ID in Powershell and your source directory so that the two accounts can correctly match up.

By manually setting an Immutable ID for certain end users, your source directory and Office 365 will be able to successfully recognize the user and provision him or her directly to Office 365.

Step 1: PowerShell

Open Powershell and run it as an administrator

Step 2: Install O365

If you haven’t already, you’ll need to install the Office 365 PowerShell cmdlet. You can do that by running the following command: “Install-Module MSOnline”. If prompted, type “Y” to finish the installation.

Step 3: Connect PowerShell to Office365

Run “Connect-MsolService” to connect Powershell to your Office 365 tenant. You’ll then see a screen asking you to sign into your Office 365 Tenant. If your domain is already in a federated state, I highly recommend logging in with a .onmicrosoft.com domain global administrator account.

Step 4:  Syncing

After that, have a list ready of your problematic users that aren’t syncing correctly with Office 365. For these users, you’ll first need to change the User Principal name before you change the Immutable ID. The reasoning for this step is because you cannot alter an immutable ID for a user that’s a part of a federated domain. Run the following command to change the UPN from @domain.com to @tenantname.onmicrosoft.com:

“Set-MsolUserPrincipalName -UserPrincipalName user@domain.com -NewUserPrincipalName user@tenantname.onmicrosoft.com”

Step 5: Immutable ID

Once the user’s UPN is changed to a .onmicrosoft domain, you’ll now be able to alter or create an immutable ID manually. To accomplish this, I recommend visiting  https://www.guidgenerator.com/ to generate your unique Immutable ID value. This is similar to what a Source directory would do to map the Immutable ID attribute.

Note: Make sure Base 64 encoding is checked before you generate your GUID

Step 6: GUID

Now that you have your randomly generated GUID value, you can change the Immutable ID. Go ahead and run this script:

“Set-Msoluser -UserPrincipalName user@tenantname.onmicrosoft.com -ImmutableID <GUID Value Here>”

Step 7: Original

Since you’ve successfully changed the user’s Immutable ID, you’ll now need to change the user’s UPN back to its original state. Modify the command from step four to make it so you’re changing the UPN from the .onmicrosoft domain to the federated domain.

“Set-MsolUserPrincipalName -UserPrincipalName user@tenantname.onmicrosoft.com -NewUserPrincipalName user@domain.com”

Step 8: Verify

At this point, you can now verify that the new Immutable ID is showing up in the user’s office profile via Powershell. Run “Get-MsolUser -UserPrincipalName user@domain.com | select *” to make sure the Immutable ID is correctly showing up in the user’s profie.

While we completed the Office 365 portion of this configuration, we’ll still need to make the necessary changes in the cloud directory (I’ll be using Okta as my cloud directory example).

Step 9: OKTA

In Okta, you’ll need to make sure that the provisioning Options (Create, Update, Deactivate, Sync Password) are all disabled. If the user is assigned to Office 365 currently, go ahead and unassign the user from Office 365.

Step 10: Reassign

Next, Reassign the user to Office 365. After you click assign, you’ll be prompted for a space to manually input the newly created Immutable ID. Feel free to copy/paste the value into the Immutable ID textbox.

All that’s left to do now is to assign the correct licenses and roles to the end user inside Okta and you should be all set. You’re now able to turn back on the provisioning features inside Okta to master all of your O365 users in one central location. Test authentication with the problematic user and verify that the authentication flow is successful.

Although manually setting/resetting a problematic user’s Immutable ID is not always the fix to a provisioning solution, it’s a good place to start when it comes to diagnosing certain provisioning problems. These steps offer a great way to rule out any chance that your error is stemming from a unique ID issue.  If the Immutable ID fix did not correct the user synchronization, there is likely something else deeper at play. Look for other attributes that could be causing the Sync to fail, and then resync the values between Office 365 and Okta.