Using the Okta API to Configure Okta Group to AD OU Mappings

Introduction

Integrating Okta with Active Directory (AD) is a common requirement for organizations that want to centralize identity management while maintaining on-premises resources. One key aspect of this integration is mapping Okta groups to AD Organizational Units (OUs). This ensures that users provisioned through Okta are placed in the correct OU in AD, aligning with organizational policies and workflows.

Okta allows you to map Okta groups to AD OUs in the Group Directories tab. This is fine if you are only mapping a handful of groups and OUs. But if your organization utilizes many different OUs, then a programmatic approach will be a better option.

In this post, we’ll walk through how to use the Okta API to configure these mappings programmatically.

Why Map Okta Groups to AD OUs?

• Granular Control: Different OUs often have unique policies, GPOs, or delegated administration.

• Automation: Avoid manual placement of users in AD.

• Consistency: Ensure that identity lifecycle events in Okta reflect accurately in AD.

 Prerequisites

1. Okta Admin Access with API token.

2. Active Directory Integration already configured in Okta.

3. Some prior experience making Okta API calls using Postman

4. Okta API Documentation handy: Okta Developer Docs.

Okta API End Point

The Okta Applications API end point can be leveraged for this update. Here is the documentation:

https://developer.okta.com/docs/api/openapi/okta-management/management/tag/ApplicationGroups/#tag/ApplicationGroups/operation/assignGroupToApplication

You may notice it is not clear from the documentation that we are able to update the Okta group to AD OU mappings with this end point.

But this is how you can do it.

Use the following API call:

PUT

https://{{okta_url}}/api/v1/apps/{{appId}}/groups/{{groupId}}

With the following payload:

{

"profile": {

"organizationalUnit": "{{ou}}"

}

}

The organizational unit value should be all in lower case.

Postman Runner

If you need to configure a lot of Okta group to AD OU mappings, using a Postman runner is a quick and easy option. The runner lets you specify a CSV or JSON file as input to your request.

The steps below assume you already have some familiarity with Postman and the Okta API.

Here are the steps:

• Add the above PUT request into a postman collections folder

• The baseUrl and appId values can be specified in your environment variables.

• Create a CSV with the following columns: groupId and ou.

• On the folder, click on the '3 dots' and click Run

  

• Click Select File and choose your CSV file.

• Click Run

 Other options for configuring a lot of Okta groups to AD OU mappings include:

• Okta Workflows

• Okta API SDK

 Conclusion

If you require assistance with any of the Okta API steps detailed above or any other Okta-related inquiries, contact the TechJutsu team today.