How to setup Okta and Active Directory Integration & Provisioning

More often then not, companies begin a modern identity journey by expanding the capability of an existing identity store. This could be federation using ADFS, identity governance using SailPoint, or integration to a third party directory.

Active Directory (AD) is a highly extensible and capable solution for the majority of legacy business cases and is easily the most common identity store in the industry. With the advent of cloud, however, the on-premise directory is starting to show its age – and that’s why my favourite initial capability addition is to integrate Okta.

In this technical blog, I’ll take you through the basics, and demonstrate some Universal Directory capability.

Integrating Okta with AD: An Introduction

Before we get started, it’s valuable to address the three most common questions most people will ask when I begin the conversation about using Okta with Active Directory:

1. Why choose a cloud directory?

The cloud directory conversation boils down to one point: Less infrastructure. I’ll probably need a bit of infrastructure to run the initial phase of any identity uplift, but lets be honest; Infrastructure is hard work, We don’t want it and we certainly don’t want to plan our transformation with the idea of working harder in mind.

2. Why a third party directory?

The second question isn’t a dig at any one provider, but providers generally operate with their own services in mind. Sure, you can plug external solutions into a proprietary solution, but the integration to the vendor ecosystem products is always a little bit better. A third party directory really removes this problem, as they are focused on offering businesses well-managed, easy identity and access management (IAM).

3. Why Okta?

Okta is the world’s leading Identity as a Service (IDaaS) solution for both enterprise and small and midsize businesses, with some incredible versatility owing to its cloud-based delivery model. For a deeper comparison on some of the Gartner market leaders in the modern identity space, head on over to our comparison of Ping & Okta.

How to connect AD to Okta

So you’ve decided to connect AD to Okta. Great! Now is the time to understand the requirements for your Okta connectors and your AD integration scenario before deployment – generally two member servers will work for a HA deployment. Greater than 30,000 users? You probably should have a few more!

As an optional first step, we can create a service account and assign the relevant permissions for provisioning.

By default, the AD Agent installer will create “OktaService”, but you need to make updates for provisioning and group push. I’ve got quick little script to create the required account with the minimum requirements for both.

	#Quick and easy File to write output to – A Lazy mans logging
	Start-Transcript ./Okta–ServiceAccountConfig.log

	#I would like an AD module please
	Import-Module ActiveDirectory

	#Basic Details for the Service Account & Domain.
	$serviceAccountName = "svcOktaAgent"
	$serviceAccountUsername = "svcOktaAgent"
	$serviceAccountDescription = "svcOktaAgent – Okta AD Agent Service"
	$serviceAccountPassword = "1SuperSecretPasswordThatWasRandomlyGenerated!!!"
	$serviceAccountOU = "OU=ExampleOU,DC=corp,DC=contoso,DC=com"
	$targetUserOUs = @("OU=ExampleOU,DC=corp,DC=contoso,DC=com", "OU=ExampleOU,DC=corp,DC=contoso,DC=com")
	$targetGroupOUs = @("OU=ExampleOU,DC=corp,DC=contoso,DC=com")
	$domain = Get-ADDomain
	$serviceAccountUPN = "svcOktaAgent@$($domain.Forest)"

	#Create an AD User
	New-ADUser –SamAccountName $serviceAccountUsername –Name $serviceAccountName –DisplayName $serviceAccountName –Path $serviceAccountOU –UserPrincipalName $serviceAccountUPN –CannotChangePassword $true –Description $serviceAccountDescription
	Set-ADAccountPassword $serviceAccountUsername –NewPassword $(ConvertTo-SecureString –String $serviceAccountPassword –AsPlainText –Force) –Reset
	Enable-ADAccount $serviceAccountUsername

	#Assign Permissions for User creation & basic attribute write.
	foreach($TargetOU in $targetUserOUs){
	$UserCommands = @(
	"dsacls `"$TargetOU`" /G $($domain.Name)\$($serviceAccountUsername)`:CC;user"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;mail;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;userPrincipalName;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;sAMAccountName;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;givenName;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;sn;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;pwdLastSet;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;lockoutTime;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;cn;user",
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;name;user",
	"dsacls `"$TargetOU`" /I:S /G `"$($domain.Name)\$($serviceAccountUsername)`:CA;Reset Password;user`""
	"dsacls `"$TargetOU`" /I:S /G `"$($domain.Name)\$($serviceAccountUsername)`:WP;userAccountControl;user`""
	)
	foreach($command in $userCommands){
	CMD /C $command
	}
	}

	#Permissions required for group push.
	foreach($targetOU in $targetGroupOUs){
	$groupCommands = @(
	"dsacls `"$TargetOU`" /G $($domain.Name)\$($serviceAccountUsername)`:CCDC;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;sAMAccountName;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;description;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;groupType;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`;member;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;cn;group"
	"dsacls `"$TargetOU`" /I:S /G $($domain.Name)\$($serviceAccountUsername)`:WP;name;group"
	)
	foreach($command in $groupCommands){
	CMD /C $command
	}
	}

	Stop-Transcript

view raw OktaServicePowershell.ps1 hosted with ❤ by GitHub

You will notice the account gets write on a specific set of attributes within the OU – this is by design as you should only ever assign access to the minimum required attributes. If you intend on adding extra attributes to Universal Directory, you will need to configure the service account access to each attribute in a similar fashion.

For my lab, I’ve taken a short-cut and provided the account to full attribute write.

Next, we can log into our Okta portal and download the AD agent. Run the installer on a separate server to your domain controller, as you should always strive to separate out services between servers.

The agent installer is fairly straight forward, and the process can be initiated from the web portal. (Directory Integrations > Add Directory > Active Directory.) The key steps are as follows:

Specify the service account: In our case, this will be custom account.

Provide your subdomain and log in to Okta: This step will allow the agent to register.

Select the essentials: The OU’s you would like to run sync from + attributes to be included in your profiles.

You should finish step 3 with the following prompt. If you get stuck, there is detailed instructions in the Okta documentation.

Disable Active Directory Profile Mastering: For the purpose of this blog, I’m going to disable AD Profile Mastering. This ensures that Okta remains as the authoritative source for my user profiles. You can find this option under the import and provisioning settings of the directory.

Enabling Okta to provision AD Accounts

Now we have completed a base setup, most administrators will configure up user matching and synchronisation (Step 2 in the official Okta provided documentation).

I’m lucky enough to have a brand new AD domain, that I would like to push Okta users to, allowing me to skip straight to Okta Mastered AD Accounts – winning!

Okta mastered accounts rely on the concept of Universal Directory. The UD is an excellent Okta feature that enables administrators to pivot data from Okta into and out of third party services. Universal Directory enables HR as a master scenarios, and data flow between the vast majority of Okta applications. For a detailed overview on UD, have a look at this excellent page from Okta’s official documentation.

Enabling Okta provisioning in AD: First I need to navigate to my directory settings and enable “Create Users”. To ensure my user data always stays accurate, I’ll also be enabling “Update User attributes”.

Create an Okta Group: Self-explanatory! Click Add Group and fill out the details as desired.

Assign a directory to the Okta Group: This ensures users who are added to the Okta Group are automatically written down into the AD OU. To do this, navigate to the group, and select Manage Directories.

Add your AD domain to the “Member Domain” section: You are able to select multiple AD domains here, which is extremely useful for Multi Domain scenarios. You can also use UD to daisy chain together AD domains, enabling a migration scenario. Select Next and configure your target OU. This should match the OU you specified in the earlier service account setup, as the service does need permission to create your AD account.

Assign users to AD: Everything is now set up! The assignment process is pretty simple – navigate to the group, manage users and move across your targeted user. Select save to initiate the Okta provisioning action.

A quick look in AD, and my account has already been provisioned! This process is extremely quick, with the account remaining disabled initially. This is a by-default security feature.