Custom roles in Office 365
Custom roles defined in Microsoft Entra ID can be used to implement role-based access control (RBAC) for Office 365. Depending on your use case, you can choose to only import the custom roles names defined in Microsoft Entra ID, or can also import the role assignments. You can configure Okta to be the single source of truth for custom role assignments for Office 365.
By default, the Office 365 app integration only recognizes Microsoft Entra built-in roles such as Global Administrator and Helpdesk Administrator, which provide fixed, predefined permissions. If your org uses custom roles defined in Microsoft Entra ID for Office 365, you can configure your Office 365 integration to import and manage custom roles by enabling the relevant settings in its provisioning settings.
There are three provisioning settings that determine how an Office 365 integration imports and uses custom roles:
Import custom roles
To use custom roles from Microsoft Entra ID in Okta, you must enable the Import custom role names provisioning option. Okta uses role names to differentiate between each role. Duplicate role names can exist in Microsoft Entra ID as it differentiates roles by GUID. Before importing custom role names to Okta, you must rename or delete any roles that have duplicate names. By ensuring that each role has a unique name, you ensure that each role defined in Microsoft Entra ID is imported into Okta.
After you enable Import custom role names and perform a full import, you can assign those custom roles to users or groups. Role assignments in Okta are completely separate from any assignments in Microsoft Entra. After you complete assigning roles, you can push the assignments to Microsoft Entra by completing the Provision Office 365 custom role assignments task.
To enable this option, complete the Import Office 365 custom roles task.
Import custom role assignments
If you created and assigned custom roles to users in Microsoft Entra ID and want to bring those assignments to Okta, you can enable the Import custom role assignments. Note that only user assignments are imported; group assignments are not imported.
When you enable this option and perform a full import, Okta imports the assignments directly from Microsoft Entra. The import operation ignores any rules defined in Okta, such as entitlement policies, which means that assignments in Okta are replaced by those defined in Microsoft Entra.
This means that importing assignments from Microsoft Entra has the potential to break the access defined by your Identity Governance setup for Office 365 in Okta. To ensure that your role assignments in Okta continue to comply with your governance settings, before you perform an import, you must compare the assigned roles in Microsoft Entra against your governance rules and configurations in Okta.
To enable this option, complete the Import Office 365 assignments from Microsoft Entra ID to Okta task.
Provision custom role assignments
In some org configurations, you may want to use Okta as the source of truth for Microsoft Entra ID custom role assignments for Office 365. Choosing this approach means that all role assignments are performed in Okta, and whenever a role assignment is updated in Okta, that change is synced to Microsoft Entra. This option requires you to enable provisioning custom roles from Okta to Office 365.
When you enable this option, syncing to Office 365 results in the role assignments defined in Okta replacing those in Microsoft Entra. There is no way to recover the overwritten records in Microsoft Entra.
Since this provisioning option is a one-way operation with no rollback, it's critical that you ensure that the role settings in Okta are exactly how you want them to be defined in Microsoft Entra.
To enable this option, complete the Provision Office 365 custom role assignments task.