Import Office 365 custom roles

Configure your Office 365 app integration to import custom roles from Microsoft Entra ID. After they're imported to Okta, you can assign these custom roles to users and groups. Optionally, you can choose to import role assignments from Microsoft Entra ID to use it as the source of truth for Office 365 role assignments in Okta.

About this task

Custom roles defined in Microsoft Entra ID can be imported into your Office 365 app integration to manage role-based access control (RBAC).

Note: Okta uses custom role names to distinguish between custom roles, while Microsoft Entra ID uses GUIDs to distinguish custom roles, which allows for duplicate role names. If any custom roles have duplicate names in Microsoft Entra ID, rename or delete them before you enable importing custom names to Okta.

Before you begin

You have an Okta admin role with permission to manage apps.
Rename or delete any custom roles that have duplicate names in Microsoft Entra ID. The import operation only imports custom roles with unique names, and ignores duplicates. The import also ignores any custom roles whose names include non-BMP characters, which are characters that are larger than two bytes.

Procedure

Import Office 365 custom roles to Okta

In the Admin Console, go to Applications and Resources > Applications.
Select the Office 365 app instance.
Go to the Provisioning tab.
Select To Okta under Settings.
Click Edit in the Settings section.
Select Import custom role names in the Custom role settings section.
Click Save.
Go to the Import tab.
Click Import Now.
When the import is complete, the custom roles are listed in a Custom Roles section of the pages where you can assign roles. You can now optionally complete the following steps to use Microsoft Entra ID as the source of truth for Office 365 roles in Okta.

Import Office 365 assignments from Microsoft Entra ID to Okta

Verify that assignments from Microsoft Entra ID won't overwrite desired settings in Okta. Do this by reviewing the assigned roles in Microsoft Entra ID and comparing them against your governance rules and configuration in Microsoft Entra ID.
Go to the Provisioning tab.
Select To Okta under Settings.
Click Edit in the Settings section.
Select Import custom role assignments in the Custom role settings section.
CAUTION: When you import custom role assignments from Microsoft Entra ID, these values overwrite role assignments in Okta. This import ignores any entitlement policies that are configured in your org, which could cause users to have incorrect permissions.
Click Save.
Go to the Import tab.
Click Import Now.

Any imported users who don't have an app user profile for the Office 365 app instance appear on the Import page. Select the users to assign them to the app. After you confirm the app assignments, the Office 365 roles in the affected app user records match the roles assigned to the users in Microsoft Entra ID. If a user's role was assigned by a policy that was overwritten by the import, you can revert this change by using the Revert to Policy option. See Manage user entitlements.