This is a step by step guide on how to set up SSO for Microsoft Office 365 on Okta.
Before you can start setting up Single Sign On (SSO) for Microsoft Office 365 and Okta, we need to check the following:
Log in to your Okta account as an administrator (with administrator access).
Under Applications> Applications, search for the Microsoft Office 365 app in the Okta Integration Network (App Integration Catalog).
"Add" Microsoft Office 365 app.
Add your Microsoft Office 365 tenant domain and leave the rest to the default settings in the first page. Then click Next.
Select "Secure Web Authentication".
Select the appropriate option for username and password setup that you want to test with.
This is important to select "Secure Web Authentication" now. As we can change this later in the future. It is important is as we need to make sure users can log in while we migrate the users over.
For now, leave the rest of the default settings and click Done.
We can now test this in our Okta end user dashboard. To do this, in Okta, let's assign a user to the application.
Go to our "Microsoft Office 365" application via Applications> Applications.
Go to "Assignments".
Select "Assign" and "Assign to People".
Select our test user, click "Assign".
Assign appropriate Office 365 licenses to your test users.
Click "Done".
Now let's log into our Okta instance as a test user. You may need to refresh your browser if you had the browser window already open.
Then click on one of your "Microsoft Office 365" application icons (chiclet) to log into the application.
If you have not already, we want to add our own domain (custom domain) to Microsoft Office 365. We want to change this to our own custom domain as we will not be able to federate on a Microsoft domain (e.g. developerdomain.onmicrosoft.com). That is, *.onmicrosoft.com domains cannot be federated.
So we need a custom domain that we can use for WS-Federation (WS-Fed).
To do this, we need to add our own custom domain following steps in Microsoft.
Go to the admin center at https://admin.microsoft.com.
Go to the Settings > Domains page.
Select Add domain.
Enter the name of the domain you want to add, then select Next.
Then choose how you want to verify that you own the domain.
e.g. You can use a TXT record to verify your domain.
Make the DNS changes required for Microsoft to use your domain.
Select Finish - you're done!
https://docs.microsoft.com/en-us/microsoft-365/admin/setup/add-domain?view=o365-worldwide
You can import users with a CSV file or using the provisioning function to enable importing (steps on how to set up provisioning below that below).
If your users have the same email address as your custom domain, then you can use the default "email" or similar setting in Okta.
For example, myemail@vulongtran.com = myemail@vulongtran.com
If your users have email addresses which different from the custom domain then we may need to do some username mapping.
For example, myemail@differentdomainname.com is not myemail@vulongtran.com.
We can use the transform functions within Okta to help us with this username transformation and mapping.
In Okta, open Applications> Applications.
Open Microsoft Office 365 > "Sign on" tab > Edit
Under Credentials Details > Application username format, select "Custom" from the drop down menu.
You can use a string as follows, depending on your preferences.
String.substringBefore(user.email, "@") + "@vulongtran.com"
String.substringBefore(user.email, "@") + "@yourdomainname.com"
You may need to use the source.Mail variable and not user.email. So you can use this string instead.
String.substringBefore(source.Mail, "@") + "@vulongtran.com"
It will let you test what the output looks like, by entering an Okta user to preview this mapping with. Please feel free to use that to check so you are comfortable with the expected outputs.
More guidance here from Okta if your users’ email addresses do not reside in the domain you are federating. As you can use the "Profile Editor" to facilitate the mapping.
Prepare for WS-Federation for Microsoft Office 365.
In Okta Admin Console, go to Applications> Applications.
Open your "Microsoft Office 365" app.
Click on the "Sign On" tab.
Click on "WS-Federation"
Click on "View Setup Instructions" and read through the tips and guidance there. I have a brief summary of my tips and guidance below as well.
you will need to go to the "Sign" tab of the "Microsoft Office 365" app and look for "Office 365 Domains" and click on "Fetch and Select". Then select your custom domain.
Similar to Step 2 earlier, we can test that SSO is working on Office 365 with the WS-Federation method.
You will notice that the log in process looks very similar.
However, this time, behind the scenes, there is no username and password needs to be set up as what is required for the Secure Web Authentication (SWA) method. So WS-Federation is always the goal to work towards as you phase your migrate your users into Office 365 and make it as seamless as possible for the users experience.
Provisioning allows Okta to help you manage the users with access to Microsoft Office 365.
Specifically, provisioning will allow you to Create, Update and Deprovision users in Office 365 using Okta as your control centre. Essentially CRUD, Create, Read, Update, and Deprovision users in/from Office 365.
Go to "Microsoft Office 365".
Click on "Provisioning" tab.
Click on "Configure API integration".
Fill in your login details for Microsoft Office 365 using your Microsoft Administrator account. As you need to provide consent to Microsoft to allow Okta to access directory data in your Microsoft tenant.
Ensure you are using administrator credentials for an account that is on your default Office 365 domain. This domain is by using your default Microsoft yourtenant.onmicrosoft.com.
For example:
Notice that we are using my yourdomain@yourdomain.onmicrosoft.com username here. We are using this, as this is our administrator credentials for an account that is on our default Office 365 domain of yourdomain.onmicrosoft.com. We want to keep this one separate and not the domain that you are planning to federate (WS-Federate).
As turning on WS-Fed will require you to authenticate yourself in Microsoft 365 Admin Center through Okta, where you will be treated as a user, not as an admin. So to ensure you always have access to Office 365 domain using your default Microsoft yourtenant.onmicrosoft.com, we will use a custom domain for the WS-Fed set up.
When ready, click "Test API Credentials".
Once successful, you'll see "Microsoft Office 365 was verified successfully!"
Click "Save" when you're ready. Then it will automatically refreshed.
Once enabled successfully, you will be able to see the following. You can select your desired option below.
Minimum is "Profile Sync" and you can choose one of the others depending on your preferences. If you are unsure, I would recommend selecting "Profile Sync" as once you select the other three options, you will not be able to select "Profile Sync".
Here are further details on each of the options:
Other notes:
You will be able to use these options from "Okta to [Office 365] App".
You will be able to use these options from "[Office 365] App to Okta".
Here are some useful links in case you need more details around this.
We can test if this is working correctly by deactivating a person in Okta.
To do this, we:
1. In Microsoft 365 admin center (Microsoft Office Admin Console), we go to our Users> Active users.
Notice that the "Sign-in status" = "Allowed" for our users.
2. In Okta Admin Console, go to Directory > People.
Find a test user to deactivate, I am using tuesday@ as my example.
We would click on "More Actions> Deactivate Person" in the option there.
3. Go back to Microsoft 365 admin center (Microsoft Office Admin Console), and go to our Users> Active users.
Refresh the page.
You will notice that my test user (Tuesday) is now status as blocked, which is what we want to see.
Notice that the "Sign-in status" = "Blocked" for our users.
You can't remove the ".onmicrosoft.com" domain from your account. You also cannot federate on a *.onmicrosoft.com domain. When you remove a domain, user accounts will revert back to the ".onmicrosoft.com" address as the Primary SMTP/UserprincipalName.
If you have received this, reset your admin password by following these instructions. You will need to know the name of your previous Microsoft account that has been using that domain. https://passwordreset.microsoftonline.com.
We have confirmed that you own dejavuguides.com, but we can't add it to your account because the domain is already added to a different Microsoft 365 organization: dejavuguides.onmicrosoft.com.
Sign in to the admin center as an admin for that organization, and remove the domain dejavuguides.com. Try resetting the admin password if you can't sign in. You should be able to add the domain dejavuguides.com here after taking that step.
If you can't access dejavuguides.onmicrosoft.com, please contact our support team for help.
You will receive an error if you try federate using the *.onmicrosoft.com address.
Please review the form to correct the following error(s):
Please provide credentials for an Office 365 administrator who belongs to a separate domain than you are about to federate. If you do not have such user, please create an Office 365 user 'admin@yourcompany.onmicrosoft.com' that has the role 'Company Administrator'To fix this, you will need to go to the "Sign On" tab of the "Microsoft Office 365" app and look for "Office 365 Domains" and click on "Fetch and Select". Then select your custom domain.
You will receive an error if you try federate using the default domain in Office 365.
Please review the form to correct the following error(s):
Federating to the 'Default' domain is not allowed. Please change your Office 365 domain for this app. domain=vulongtran.com
To fix this, you will need to go to Microsoft Admin console> Settings> Domains and update your default to be your *.onmicrosoft.com address or another domain other than the one you are planning to use in Okta.
This usually comes up when immutable ID does not show up in the user assignment.
"Office 365 Login Failure. Your account has not been configured for this application"
If you are not using Active Directory (as we won't be using the immutable ID from AD), you can fix this by doing the following:
In Okta> Applications> Applications
Provisioning> To App> scroll down to "Microsoft Office 365 Attribute Mappings"
Set the "Microsoft Office 365 Attribute Mappings" to have the following:
As when you click on Assignments and then the pencil icon next to the user.
You may or may not see the "immutable ID". Microsoft Office 365 needs that immutable ID, else it will give the error message "Office 365 Login Failure. Your account has not been configured for this application".
You can also try this "Expression" setting if the test if you need to have the "Apply on: Create and Update" option as well.
You can also check the federation status of your domain on Microsoft. Here's an example:
https://admin.microsoft.com/Adminportal/Home#/Domains/Details/vulongtran.com
You create a new user in the Microsoft 365 Admin Center in Office 365. However, when you try to assign a federated domain to the new user, the federated domain isn't listed in the user's list of domains.
This behavior is by design in Office 365. You can't create federated users through the portal. All federated users must be created on-premises and must be synced by using the Microsoft Azure Active Directory Sync Tool.
Useful Troubleshooting links: