In today’s world, more and more organizations are looking at simplifying their Identity and access management solution in order to better secure their identity but also to reduce cost while improving the user experience. One of the use case we see more and more is organizations using Okta to centralise their users coming from mutliple user’s stores.
This article will cover how we can seemlessly migrate users and their passwords from Microsoft Office 365 / Azure AD to Okta.
- 1 x Okta Workforce Identity tenant (Trial available here).
- 1 x Okta Workflows tenant (Provisioned with above tenant – 5 Free Flows included).
- 1 x Office 365 / AzureAD tenant with users and basics licencing E3 or developer account.
- Basic Knowledges of Okta Admin Console, Workflows and Office365&Azure AD.
Please note that this article do not represent an official solution for production purpose and has been designed to offer an example to address such use case.
- Okta Integration with Office 365.
There is many way of integrating Office 365 and we recommend you to follow the below articles in order to sucessfully integrate Office 365 with Okta. For this article we require you to also turn on Provisioning in order to be able to import your users to Okta.
Now your Office 365 is fully integrated including provisionning we will now import a test user for the purprose of this article.
In your Okta tenant, go to Application section and find your Office 365 Application.
Select the Tab “Import” and click “Import Now” button to start to sync down the users from Office 365. As per the screenshot above, all your users will appear however they are not yet imported at this stage. Select then the users you would like to import and then Confirm Assignement.
As per below do not tick auto-activate users as we want them to be in stage mode in order to configure the Import hook in step 2 of this article.
Click confirm and verify that your user is in Okta directory and in Staged mode.
As this stage we are done with our step 1.
2. Set your Office 365 users for “Import” Password Hook.
What is Okta Password Import Inline Hook Reference?
The Password Import Inline Hook enables migration of users from another data store in a case where you wish the users to retain their current passwords. It is meant to be used in conjunction with the Create User with Password Import Inline Hook flow that is provided by the Users API.
The Password Import Inline Hook is triggered when the end user tries to sign in to Okta for the first time. Okta sends your external service the password that the user supplied. Your external service then needs to send a response to Okta indicating whether the password supplied by the end user is valid or not.
If your service returns a response that indicates that the password is valid, Okta sets the password for the user and won’t normally need to call your service again. However, if the Okta service is in read-only mode, it might not be possible to set the password. Okta then needs to call your service again the next time the end user attempts to signs in. See Password Inline Hook and Okta Service Mode and Removing Password from Existing User Store for details.
Configuration of the Password Import Inline Hook:
In order to automatically set the user’s credential to seed their password from an “Import” source we will configure a Flow in Workflows to do that.
This flow that you can download here and import into your Workflows tenant will check when a user is assigned to Office 365 app and in staged mode to then update the user to set their credential to “import” to then activate this user ready for sign in.
Once you have downloaded the flow into your computer. Go to your Okta tenant admin console then go to the Workflow menu and select the Workflows Console.
In the Workflow Tenant, go to Flow then create a new folder and then click on the little config button and import the flow.
Once imported you will have all the flow availbale for this article. We will however focus on the 01.Office365 – Enable Password Hook for this section.
Click on this Flow to open it and configure it. I will assume for this article that you have already the Okta connection setup (Workflows connection to your okta tenant). If you didn’t please follow this step here before going any further.
Now your configured you will need to configure the first card “User Assigned to Application” card by selecting the Application ID. FYI to find the application ID in Okta going to the Okta Admin console and go on the Application configuration page of Office 365 in this case. The Application ID will appear in the URL. Copy it and paste it in this first card.
Next card will be to replace yourtenant by your tenant name as per this exemple.
In the API Connector card you will need to get your Secret key that you you need to generate in order to tap in the okta API. As per below screenshot go to your Okta Admin Console and Click Security, API, Tokens and Click Create Token. Give it a name and click Create Token.
It will provide a secret key that you need to copy to then past it to the API card Flow mentioned earlier.
Replace the existing key and please note that there is a space after SSWS “SSWS KEY”.
You can now save your Flow and turn it on. At this stage everytime a user is imported from Office 365 it will get prepare for the Import password Hook.
3. Password Inline Hook Configuration
In this section we will now focus on the API call Hook to Office 365 / Azure AD.
As part of your previously downloaded Flow package we will now focus on the flow 02.AAD – Password Import Hook. So go back to your Workflows tenant. We need now to get the API endpoint of our flow to configure the Inline Hook in Okta.
For this click on the configuration button then API Access and copy the Invoke URL that we will use in the next step.
Now go back to your Okta admin console and go to the Workflow tab then Inline hooks. Add Inline Hook and Click Password Import.
Select a name for the Hook and past your API End point URL from Workflows and click save.
At this stage the Hook is ready to go to our Flow in Workflows to pass the password for verification to Azure AD. Before we configure the Flow to connect to our Azure AD tenant we need to do some preparation into Azure AD.
Go to your Azure AD tenant and select Azure Active Directory. On the left tab go to App registrations and click new Registration.
Provide a name and leave the other settings default and click register.
Select your app and once in the middle section click on secret below Client credentials this will bring you to the next page to create a client secret.
Create a new secret and select the period you wish. Once created please keep the secret ID for later steps.
Now go to Authentication Make sure to select settings as per below. If you don’t see Access Token make sure to add Application as a Web app to it will appear then.
Go bak now to the main Azure Active Directory Menu and select Enterprise Application then select your Application and click Permissions on the left menu.
To finish our apps setting in Azure go now to Users and groups and add the groups and users that you would like to test.
Before we go back to configuring our Flow in Worflows and since you have the Client Secret ID, we also need the Azure AD tenant ID. For this go to the main menu Azure Active Directory and copy the teant ID.
Back to our Workflows console. Click on the 02.AAD – Validate Creds.
Replace both ID with the previously copied IDs
Nos save this Flow and turn in on with the little toggle. Go back to your folder flow and turn on the other flow 02.Password import hook.
At this stage you are ready to test the whole flow. Preapre a user in Azure AD that you have setup a password you know (I use Office 365 admin console to geenrate a password).
Go to the login page of your Okta tenant and test this user. Once the user signed in it will be ask to setup MFA. After that the user is now stored with its password in Okta congratulations!
25/06/2022 – Please note that the Inline Hooks capability with Workflows is not officially supported even though it is high likely going to work at small scale. It is however being addresed to offer official latency SLA for such use case in the future.
10/08/2022 – Adding the Workflows capability to import the Office User’s Attributes along the user to okta:
Simply download the flow here pick and choose which attributes you would like to read/import on the read user Office 365 card as per below screenshot.
the flow below will do the import when the user is activated.
If you have any error Workflows has a Flow history section that shows exactly what is not working.
you can also see that the Flow has been fired by looking at the time stamp at the main Flow menu.
Special credit to James Reeder to build the Flow to API call into Azure.
Special credit to Mark Smith for helping me making it all working.
Special credit to Sathish Balasubramaniyan for the initial guidance.