Provide Microsoft admin consent for Okta

Okta requires specific permissions to integrate with your Microsoft Office 365 tenant. These permissions allow Okta to access the Microsoft Graph API on your behalf to perform SSO and user provisioning.

Before you begin

Ensure that you have the global admin permissions in your Microsoft tenant.

Understanding Okta's permission needs

The required permissions are granted to one of two distinct Okta apps that are registered in your Microsoft tenant. The specific app used depends on the functionality that you enable:

Functionality enabled	Okta app required
Domain federation	Okta Graph API Client - Federation
Provisioning and advanced API access	Okta Microsoft Graph Client

You're prompted to grant admin consent during the initial configuration of either SSO or provisioning within your Okta Office 365 app integration.

Permissions for domain federation

If you're only federating your domain, the following set of permissions is granted to the Okta Graph API Client - Federation app:

Permission	Allows Okta to	Notes
`User.Read`	Read users	Basic user identity required for authentication.
`Domain.ReadWrite.All`	Read and write domain data	Required for domain configuration and verification.
`RoleManagement.ReadWrite.Directory`	Assign directory roles to users, groups, and service principals.	Required during initial setup. Note: You can safely revoke this permission after you've successfully integrated.

Note:

The Directory.Read.All permission isn't required. If you previously granted this permission, you can revoke it.

Permissions for provisioning and advanced API access

If you're configuring provisioning or advanced API access for OAuth-based apps (such as Microsoft Teams, Viva, and Power BI), the comprehensive set of permissions is required and granted to the Okta Microsoft Graph Client app.

Both provisioning and advanced API access share the permission set, which requires read/write access to the Microsoft Graph API to manage user tokens, licenses, and directory objects.

Note:

For SSO to work with apps such as Microsoft Teams, Viva, and Power BI, you must grant permissions to both the Okta Graph API Client - Federation app and Okta Microsoft Graph Client app.

Permission	Allows Okta to	Notes
`User.ReadWrite.All`	Create, read, update, and delete users	Required for user lifecycle management.
`Group.ReadWrite.All`	Create, read, update, and delete groups	Required for group push and group management.
`GroupMember.ReadWrite.All`	Add or remove members in a group	Required for managing group membership.
`Organization.Read.All`	List acquired licenses and remaining seats in a tenant	Required to view license availability.
`Application.Read.All`	List the app registrations and service principals in a tenant	Required for integration configuration.
`RoleManagement.ReadWrite.Directory`	Assign directory roles to users, groups, and service principals	Required for managing administrative roles (for example, global admin). If provisioning isn't used, you can safely revoke this permission after successful SSO integration.
`Directory.ReadWrite.All`	Read directory data	Used for directory management. If `LicenseAssignment.ReadWrite.All` is granted, you can safely revoke this permission.

Note:

The User.Read permission isn't required. If you previously granted this permission, you can revoke it.

Provide Microsoft admin consent for Okta

You can provide admin consent in two ways:

Provide Microsoft admin consent for provisioning
Provide Microsoft admin consent for single sign-on

Provide Microsoft admin consent for provisioning

Note:

To facilitate provisioning from Okta to Office 365, you must authenticate and grant admin consent to allow Okta to access Microsoft Graph APIs.

If you're enabling provisioning for the Office 365 app for the first time, follow these steps:

In the Okta Admin Console, complete the following:
1. Go to Applications > Office 365 > Provisioning > Integration.
2. Select the Enable API integration checkbox.
3. Click Authenticate with Microsoft Account.
  
  You're redirected to the Microsoft account sign-in page.
In Microsoft, complete the following:
1. Sign in to Microsoft as a global admin for your Microsoft tenant.
2. Read and accept the instructions that are listed on the Okta Microsoft Graph Client page.
Save the settings in the Okta Admin Console.

Re-authenticate Microsoft admin consent for provisioning

Note:

If your org enabled provisioning before December 2021, you must reauthenticate to grant admin consent before you modify the provisioning settings. This is required because the permissions that Okta requests have changed.

If you've already enabled provisioning for the Office 365 app and need to re-authenticate, follow these steps:

In the Okta Admin Console, complete the following:
1. Go to Applications > Office 365 > Provisioning > Integration > Edit.
2. Click Re-authenticate with Microsoft Account.
  
  You're redirected to the Microsoft account sign-in page.
In Microsoft, complete the following:
1. Sign in to Microsoft as a global admin for your Microsoft tenant.
2. Read and accept the instructions that are listed on the Okta Microsoft Graph Client page.
Save the settings in the Okta Admin Console.

Provide Microsoft admin consent for SSO

In the Okta Admin Console, complete the following:
1. Go to Applications > Office 365 > Sign On > Edit.
2. In the Sign on methods section, ensure that WS-Federation > Automatic is selected.
3. In the Office 365 Domains section, click Start federation setup. You're redirected to the Microsoft account sign-in page.
In Microsoft, complete the following:
1. Sign in to Microsoft as a global admin for your Microsoft tenant.
2. Read and accept the instructions that are listed on the Okta Graph API Client - Federation page.
Back on the Sign On tab, click Federate domains, and select the domains to federate with Okta. Federate at least one domain to complete authentication.
Optional. For SSO to work with apps such as Microsoft Teams, Viva, and Power BI, complete the following in the Okta Admin Console:
1. In the API Credentials section, select Allow administrator to consent for Advanced API access.
2. Click Authenticate with Microsoft Account. You're redirected to the Microsoft account sign-in page.
3. Sign in to Microsoft as a global admin for your Microsoft tenant.
4. Read and accept the instructions that are listed on the Okta Microsoft Graph Client page.
Save the settings in the Okta Admin Console.

Reauthenticate Microsoft admin consent for SSO

You must reauthenticate the existing Microsoft admin consent for Okta in the following cases:

If you add a new Office 365 app to the Okta End-User Dashboard and that app requires OAuth.
If the URL for an Office 365 app changes.

In the Okta Admin Console, complete the following:
1. Go to Applications > Office 365 > Sign On > Edit.
2. In the Sign on methods section, ensure that WS-Federation > Automatic is selected.
3. In the Office 365 Domains section, click Re-authenticate with Microsoft Account. You're redirected to the Microsoft account sign-in page.
In Microsoft, complete the following:
1. Sign in to Microsoft as a global administrator for your Microsoft tenant.
2. Read and accept the instructions listed on the Okta Graph API Client - Federation page.
Optional. For SSO to work with apps such as Microsoft Teams, Viva, and Power BI, complete the following in the Okta Admin Console:
1. In the API Credentials section, ensure that Allow administrator to consent for Advanced API access is selected.
2. Click Re-authenticate with Microsoft Account. You're directed to the Microsoft sign-in page.
3. Sign in to Microsoft as a global admin for your Microsoft tenant.
4. Read and accept the instructions that are listed on the Okta Microsoft Graph Client page.
Save the settings in the Okta Admin Console.