Okta AD Agent Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Okta AD Agent
Published: Sep 8, 2015   -   Updated: Jun 22, 2018
Deploy the Okta AD Agent for OCC

Training video for OCC AD Agent

Step1: Create a dedicate "Okta Agent" Admin account

As a best practice, there should be a dedicated "Okta Agent" admin account which will be used by the agent to authenticate back to your Okta instance.  To add this user, go to:  People >> Home.  Click "Add Person."

In the resulting screen, provide values for first name, last name, user name and primary email.  Note: the user name and primary email values must be in the format of an email address; however, the value provided does not necessarily need to be a valid mailbox.  The most important thing is that the value is unique, and does not coincide with any actual AD user, as you want this "Okta Agent" account to always remain purely Okta-mastered.  You should, however, provide an actual mailbox to which you have access for the secondary email.  This will allow you to receive the activation email for the account, as well as any future password reset emails for this account.

Once the account is added, be sure to make the account an administrator.  Go to:  Security >> Administrators.  Click "Add administrator" and type the name of the user in the text field.  When the desired user appears below the text field, select it and assign the account to the Super Administrator or Application Administrator roles.  Click "save."

Finally, check the inbox of the secondary email address provided for the "Okta Agent" user, find the activation email from Okta and click on the activation link.  Provide a password, security question/answer, and security image and click "create my account."  Your Okta Agent account is now ready for use.

Step 2: Windows Service Account

The Okta Active Directory agent requires a Windows service account under which to execute.  You have the option of letting the Okta AD agent installer automatically create a new service account (called "OktaService") for you as part of the installation.  Alternately, you can specify an existing service account under which the agent will run.

If you choose to allow the Okta agent installer to create the service account, you must run the installer as a Domain Administrator in order for the installer to have sufficient privileges to create the new account.

Step 3: Identify Server(s) and agent(s)

The Okta AD agent must be installed on a domain-connected server.  It does not need to be installed directly on a Domain Controller, and in fact it is recommended to avoid installation on a DC if possible, if only to avoid a possible reboot as a result of the installation.

Note that for the initial setup/configuration, only a single Okta AD agent is required; however, we recommend installing at least one additional agent within your domain for a basic level of agent redundancy prior to deploying.  You may add as many additional agents as you like, simply by running the installer on additional machines.

Once you have identified the server(s) on which you intend to install the Okta agent(s), you are ready to download and execute the installer.  To do so, go to:  People >> Direcotry Integrations >> click "Add Directory."  Review the requirements and click "Setup Active Directory" at the bottom of the screen.  Click "Download Agent" and save the agent installer executable.

Note:  On many Windows server machines the Internet Explorer security settings may block the download of the agent installer from the browser.  It typically is easiest to download the installer from a normal workstation, then copy the installer executable to the desired server.

Step 4: Active Directory Configuration

There are a number of configuration options available for the Okta/AD integration.  The following is a discussion of each setting and its ramifications.  To access these settings after installation of the AD agent, go to:  People >> Directories >> Active Directory >> Settings tab.

Agent Status Indicators
At the top of the screen under the AD Settings tab, you will notice one or more boxes representing each of your currently installed AD agents.  The health of each agent is reflected by the color of the box -- green signifying the agent is healthy and connected; red signifying the agent is not connected.  As you add additional agents to your AD domain, each agent will appear as its own box here to indicate the current status of each individual agent.

Organizational Unit Selection
You have the ability to narrow the scope of the AD integration with Okta to select OUs, rather than your entire AD structure.  You will need to select any OUs containing users who need access to Okta.  Also, if you plan to manage application assignment using AD security groups (recommended), you will also need to select OUs containing any groups which will be used to determine application assignment via Okta.

Okta Username Preference
This setting determines the attribute which users will provide on the Okta login form to authenticate against Active Directory.  For example, if UPN is chosen, users would need to provide the domain logon name (UPN) values, similar to:  user.name@domain.local.  This setting only applies to the Okta login form, and has no bearing on how Okta identifies users to third party applications (those settings are configured per-application), so feel free to choose whatever attribute is easiest for your users.

Schedule Import
Automated imports may be set to occur on a desired scheduled increment, ranging from every hour to ever two days.  The impetus for this setting is how frequently you expect changes in your AD -- new users added, users deactivated, group memberships changed, etc.  In general, the more frequently you expect these changes to occur, the more frequently you will want the Okta AD import to run, so that Okta remains up-to-date with the most recent data from AD.

Please note, however, that regardless of the chosen increment, you always have the option of logging into the Okta admin console and manually initiating an import at any time.  So, if you have set scheduled imports to run once daily, and you have a number of new users added to AD, you can immediately initiate a manual AD import so that you do not have to wait for the next daily import to get these users recognized by Okta.

Automatic Confirmation
For now, leave these options set to manual for now.

Activation Emails
Most Okta Cloud Connect customers want their users to know as little about Okta as possible.  If this is the case, you will want to select the option which says "Don't send new user activation emails from this domain."  With this option selected, users managed by this AD domain will not receive activation emails from Okta.

Step 5: User Provisioning/activation strategy

The final step in your AD deployment is determining a strategy for provisioning/activating AD users in Okta. There are three ways to accomplish this, and depending on your particular use case, you may utilize one or more of these options:

Manual Confirmation/Activation
This option is best for initial pilot testing with a select set of users.  Under People >> Directories >> Active Directory >> Import tab, you will see a list of results from the most recent AD import scan.  In the left column are users found in your AD.  In the right column are either existing Okta user(s) who have been identified as matches for the corresponding AD user(s), or the option to provision new Okta user(s) based on the corresponding AD user(s).  To manually provision an Okta account for any user(s), simply select the check box to the right of the desired user(s) and click "Confirm Assignments."

This will provision Okta accounts for all selected users, set initially to a "pending" status.  To fully activate these newly provisioned accounts, go to People >> Home.  Click "Activate People," select the user(s) to activate and click "Activate Selected."

Please note, that as long as these users are AD-managed users, and as long as the AD domain configurations are set to "Don't send new user activation email from this domain," then no user activation email will be sent as a result of this activation.

Automatic Confirmation
This option is best when all users in the selected OUs need access to Okta.  To enable this feature, go to People >> Directories >> Active Directory >> Settings tab. 

To automatically provision only new users (i.e AD users for whom there is no existing Okta user match), select "New users."  To automatically provision both new and existing users select "New and Existing users" and choose the matching logic for existing Okta users.

With this setting enabled, AD users will automatically be provisioned with Okta accounts when the Okta AD import scan runs.  If you also wish to have these accounts automatically activated upon provisioning, select the "When confirmed, automatically activate" option.

Note:  This will provision Okta accounts for all AD users found in the selected OUs under your AD settings in Okta.  If you do not wish to have Okta accounts for all users in your selected OUs, you should avoid this option.

Just In Time (JIT) Provisioning
Okta offers another way of automating the user provisioning/activation process without having to bulk provision accounts for all selected OUs.  Just In Time provisioning is enabled by default for all Okta instances and allows any user in a selected OU to "self provision" simply by successfully authenticating to Okta with his/her AD credentials.

When a user is prompted for authentication by Okta -- regardless of whether the user navigated directly to {yourcompany}.okta.com, or whether the user was redirected to {yourcompany}.okta.com from a third party application -- if the user authenticates successfully against your Active Directory (either via the web login form or automatically via Desktop SSO), the user's Okta account will automatically be provisioned and activated on demand.