Install and Configure the Okta Active Directory Agent Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005ujhsaa&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2finstall-and-configure-the-okta-active-directory-agent-1597766701
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Install and Configure the Okta Active Directory Agent
Published: Jan 31, 2018   -   Updated: May 15, 2018

okta-doc-source

Install and Configure the Okta Active Directory Agent

Okta Active Directory (AD) integration allows you to integrate Okta with your on-premise AD. AD integration provides delegated authentication support (allowing users to sign in to Okta with their AD credentials), user provisioning and de-provisioning, and the ability to import users and AD groups.

To enable AD integration, you must install the Okta AD agent. Before installing the agent, you must create a special administrative user whose password is Okta-specific and not tied to AD. Once you integrate AD, you are able to specify how to handle an Okta account when the source account is deactivated or reactivated. For details see Profile & Lifecycle Mastering.

AD integrations in a newly-created organization automatically have the following default settings enabled:

  • Delegated authentication
  • Just-in-Time (JIT) provisioning
  • The import schedule set to never
  • Profile mastering
Requirements
  • To ensure that you have up-to-date functionality and get optimum performance from your Okta AD agent(s), we strongly recommend that you download and install the latest version of the agent on your designated host server(s). If you are running multiple Okta AD agents, make sure that all of them are the same version. Running different versions within a domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.
  • Install on Windows Server 2008 or Later — You need access to a Windows server to install the Okta AD Agent. You do not need to install the agent on the domain controller itself. Your system must have 20Mb memory for the AD Service Account that is created upon agent installation.

    Note: You must be running IE 10 or later on your Windows Server.

  • .NET 4.0 (minimum) up to  .NET 4.6.x  (downloaded and installed automatically with the agent if no suitable version is found on the target machine at runtime).
  • Installing the agent on a DMZ server — You must open several ports.
  • AD password history enforcement — To enforce the AD Password History policy, you must use Okta AD Agent version 3.4.1 or later and your Domain Controllers must be running Windows Server 2008 R2 or later.
  • 256 Mb of free memory for the service to run.
  • Service Dedicated AD Service Account with Domain user permissions 
  • For each domain:
    • The AD agent should be installed on a VM with at least 2 vCPUs and 8 GBs of RAM.

    • In order to ensure high availability and redundancy, we strongly recommend installing the agent on two or more systems.

    • If there are 30K or more users, we recommend deploying at least 3 AD agents.

  • Separate server for domain controller (can be shared).
  • Must be a member server within your active directory forest — We recommend the host server be a member in the same Active Directory domain of which your Active Directory users are members but is not required. The member server can be in a different domain, but must be in the same forest. Placing the agent on a different domain may cause performance issues.
  • Consider the agent a part of your IT infrastructure – The host server where the agent resides must be on at all times. Do not install it on your laptop. The host server must have a continuous connection to the Internet so that it can communicate with Okta.
  • Run this setup wizard from the host server – We recommend running this setup wizard in a web browser on the host server where you want to install the agent. Otherwise, you must transfer the agent installer to the host server, and then run the installer
  • Creating admin users – If you are using the Okta AD integration functionality, you should always have an Okta administrator whose password is Okta-specific and not tied to AD.

Okta recommends that no administrators be AD mastered.

Note: This does not affect existing administrators you have created who are AD mastered. We encourage you to disconnect your admins from AD (select Directory > People > More Actions > Disconnect from AD, select the admin users who you want to disconnect, and then click the appropriate Disconnect button).

  • If you are using a third-party delegated authentication service, such as that of Salesforce.com which delegates authentication into one service and to another service (like AD via Okta), then you should always have a Salesforce.com admin account that is not assigned to a delegation authentication-enabled profile. For example, you should configure a Salesforce.com admin user whose password is specific to Salesforce.com, not Active Directory.
Mandatory account permissions

You must have permissions for the following accounts:

  • Okta administrative user.
  • An Active Directory (AD) user account to run the AD Agent Installer.
  • Okta service account (created by the installer) – A service account under which the AD agent process runs after installation. This account can be created automatically by the installer, or you can select an existing account.

Creating an Okta Administrative User Account

You must create an administrator account before you begin installing the AD Agent. This user should have an Okta-specific password and not an AD password. The AD Agent connects to Okta using this account.

  1. From the Administrative Dashboard, select Directory > People, and then click Add Person to create a user (for example, ADAgent@mycompany.com).
  2. Select Security > Administrators, and then click Add Administrator.
  3. Select the type of administrator. We recommend you configure an application administrator. For details about administrator roles, see Administrators.

User Permissions Required to Install the AD Agent (Version 3.4.x)

During installation, you are asked if you want to let the installer create the Okta service account. To do so, you must have the following permissions:

  • Be a member of the domain admins group. This is required because you must be able to create a new AD user in AD that will act as the AD agent service account.
  • Have local administrator privileges. If you are installing the AD agent but using an existing user account to run as the service account, you only need local administrator privileges.

With either option, the installer grants logon as a service to the domain user you select.

Okta Service Account Options

The AD agent runs under the account you specified (either the Okta service account the installer created or the domain user you selected). Depending on the configuration of your integration, the agent performs the following actions:

  • Read users, OUs, and groups — Requires read access on the accessed objects. By default, a domain user has sufficient permission to do this. We recommend read access on the entire domain, but it is not required.
  • Authenticate users — No special permissions are required.
  • Change user passwords (by supplying the current password) — No special permissions are required.
  • Set user passwords (administratively, without the current password) — Requires permissions to set passwords for users.
  • Create and update users, attributes, and memberships in AD with values pushed from Okta — Requires permissions to read and write to the attribute(s) you are updating.

On your Windows server, use the Delegation of Control Wizard to grant the Okta service account the following permissions:

  • Create, delete, and manage user accounts — For create and update user flows.
  • Reset user passwords and force password change at next logon — For syncing passwords.
  • Read all user information — For import and create user flows.
  • Modify the membership of a group — For Group Push.

Minimum Agent Service Account permissions)

Before adjusting the permissions on your directory make sure you understand how Active Directory permissions are set and plan how to manage this within your environment.

By default the AD Agent installer will allow you to create a new service account if you do not choose an existing account. The newly created OktaService user has the permissions of the Domain Users group. OktaService is also considered to be a member of Authenticated Users and Everyone special identity groups when the agent is running.

The Okta AD Agent Management Utility also includes the option of adding the OktaService account to the Domain Admins group. If you require functionality listed below but don't want to make your service account a full admin, make sure the following permissions are set.

Provision User

  • Requires create child permission for user objects on the target OU.
  • Requires Reset Password Control Access Right permission for user objects within your target OU.
  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permission on user objects within your target OU for all other attributes mapped on the AD user profile within Okta https://<org>/admin/universaldirectory

Update User Attributes

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permission on user objects within your target OU for all other attributes mapped on the AD user profile within Okta https://<org>/admin/universaldirectory

Group Push

  • Requires create child permissions for group objects on the target OU.
  • Requires delete child permissions for group objects on the target OU.
  • Requires write property permissions on group objects within your target OU for the following attributes:
    • sAMAccountName
    • description
    • groupType
    • member
    • cn
    • name

Reset Password, Forgot Password , and Sync Password

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • lockoutTime
    • pwdLastSet
  • Requires Reset Password Control Access Right permission for user objects within your target OU.

Activate and Deactivate User

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • userAccountControl

Reference commands:

You can add the permissions listed here using the commands below. Save them to a batch file and change the target OU and service account info to be correct for your environment. Remember to remove permissions you do not need and add any attributes you have mapped for provisioning within Okta. You can get the complete list of user attributes from your Directory user profile on https://<org>/admin/universaldirectory.

# Create User

dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CC;user

# Create or Update user

# include additional attributes that are mapped in your org within Okta

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;mail;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userPrincipalName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;givenName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sn;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;user

# Create user/Password Reset

dsacls "OU=targetOU,DC=domain" /I:S /G "domain\agentserviceaccount:CA;Reset Password;user"

#Group Push

dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CCDC;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;description;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;groupType;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;member;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;group

Additional Reference information

You may find these additional references helpful in setting permissions:

Installing the Active Directory Agent

Important: To ensure that you have up-to-date functionality and get optimum performance from your Okta AD agent(s), we strongly recommend that you download and install the latest version of the agent on your designated host server(s). If you are running multiple Okta AD agents, make sure that all of them are the same version. Running different versions within a domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.

  1. Select Directory > Directory Integrations.
  2. Click Add Directory and then select Add Active Directory.
  3. Click Set Up Active Directory
  4. Click Download Agent.
  5. Double click the file to launch the installer.
  6. Click Yes at the message Do you want to allow the following program to make changes to this computer?.
  7. Choose an installation destination.
  8. Select the AD domain you want to manage with this agent.
  9. Select Create or use the Okta Service account (recommended) and complete the prompt to set a password.

    Note: Select Use an alternate account that I specify if you want to assign the Okta AD Agent to run as an existing domain user.

  1. (Optional) If appropriate for your environment, specify a proxy server through which your AD agent will connect.
    Note: If you are installing an AD agent version 3.4.11 or later, in environments where internet traffic is required to go through a proxy, the sign-in flow for the AD agent installer uses the proxy settings specified within the installer. If no proxy settings are specified, the machine defaults are used.
  2. To register the AD Agent with the Okta service, enter your Okta subdomain name, and then click Next.
  3. Enter the username and a password, and then click Sign in.
  4. Click Allow Access.

    Note: If the error message displays The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel, see Troubleshooting.

  1. Click Finish.
  2. When the Active Directory agent has started, click Next.
  3. (First time installations for this domain only) At the Connect an Organization Unit to Okta screen, select the OUs from which you want to import users and groups. You can change these and other settings at any time.
  4. Select the Okta Username format that you want AD-imported end users to use when logging in to Okta.
  5. Click Next.
  6. In the Build User Profile tab, select the attributes that you want to use to build your Okta user profiles.
  7. Click Next.
  8. When the initial Active Directory agent configuration is complete, click Next.
  9. Click Done.
  10. To reconfigure OU and import settings, as well as other settings, return to the Settings tab (Directory > Directory Integrations > Active Directory > Settings). For details, see Configuring Import and Provisioning Settings.
  11. Click Save Settings.
  12. If you installed the AD agent on a DMZ server, you must open several ports.
Open the following ports if installing the AD agent on a DMZ server.
  • 135/TCP RPC
  • 137/UDP NetBIOS
  • 138/UDP NetBIOS
  • 139/TCP NetBIOS
  • 389/TCP/UDP LDAP
  • 636/TCP LDAP SSL
  • 3268/TCP LDAP GC
  • 3269/TCP LDAP GC SSL
  • 53/TCP/UDP DNS
  • 88/TCP/UDP Kerberos
  • 445/TCP SMB
  • 123/UDP NTP

In addition, you must open your DCOM RPC ports. In addition to TCP 135, Microsoft RPC (MS-RPC) uses randomly generated ports from TCP 49152-65535 for Vista/2008 and above. These ports are also known as "random RPC ports." RPC clients use the RPC Endpoint Mapper (EPM) which runs on TCP135 to tell them which dynamic ports were assigned to the server.

For detailed information on configuring your ports on a DMZ server, see the Microsoft Support page. For more information on the required network ports, refer to Service overview and network port requirements for Windows. For more information on random RPC ports, refer to How to configure RPC dynamic port allocation to work with firewalls

Uninstalling and Reinstalling the AD Agent

Important: To ensure that you have up-to-date functionality and get optimum performance from your Okta AD agent(s), we strongly recommend that you download and install the latest version of the agent on your designated domain server(s). If you are running multiple Okta AD agents, make sure that all of them are the same version. Running different versions within a domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.

When you uninstall and reinstall your AD agent, you must decide whether you also want to remove the old Okta API token from your system. If you are performing an upgrade, you are not required to remove the old token. To remove the API token, you must delete the Okta AD Agent folder and deactivate and remove your old AD agent.

Note: To avoid down time if you intend to continue using an AD agent, you must have at least two agents running before you uninstall one of them. For more information, see Configuring High Availability by Installing Multiple Active Directory Agents.

Uninstalling the AD Agent

  1. In Windows, select Start > Control Panel > Programs > Programs and Features.
  2. Select the Okta AD Agent, and then select Uninstall.
  3. Uninstalling your AD agent leaves the agent configuration data on your hard drive.
    • To remove the configuration data, on the agent server, go to C:\Program Files (x86)\Okta and delete the Okta AD Agent folder. Deleting this folder removes the agent configuration data and the API Token from your hard drive. The API token for the server is still valid in Okta so it is important to remove the configuration data.
    • Revoke the API token by going to the agent monitor in Okta. Deactivate and remove the uninstalled agent, which will remove the API token.

Reinstalling the AD Agent

Installing the AD agent does not overwrite the configuration data in the Okta AD Agent folder. If you want to reinstall and create a new API token, make sure you delete the Okta AD Agent folder (as described above) before you reinstall the AD agent. Then perform the following steps to reinstall your AD agent and deactivate and remove the old AD agent in Okta:

  1. Perform the AD agent installation procedure described in Installing the Active Directory Agent.
  2. Select Directory > Directory Integrations.
  3. Click Active Directory.
  4. In the Settings tab, your agents are listed in the Agent Monitors section. Confirm that your reinstalled AD agent is connected to Okta and appears in the list. You should always make sure to have at least one AD agent online.

If you are performing an upgrade or reinstall and you do not want to revoke the Okta API token of the old AD agent, you are finished. Otherwise, proceed to the next step.

  1. Under Agent Monitors, select the Deactivate link for the old AD agent and then click Ok to confirm. Deactivating the agent revokes its API token.
  2. Click the Remove link for the old AD agent and then click Ok to confirm.

Upgrading in place

It is possible to upgrade the agent without having to uninstall it. The agent installer will automatically upgrade an existing agent.

Delegated Authentication

Delegated authentication (Del Auth) makes your users' Okta credentials the same as their AD credentials. Enable it if you want Active Directory (AD) to authenticate your users when they sign into Okta.

Instance-Level Del Auth moves Del Auth enablement from the org-level (Security > Delegated Authentication) to the instance-level (Directory > Directory Integrations). While preserving current Del Auth functionality, instance-level Del Auth is optimized for use in environments with multiple AD instances. It allows admins to delegate authentication on a per AD-instance level to support more granular authentication scenarios such as the following:

  • Configure Okta to be the authentication master for users in some AD instances.
  • Configure AD to be the authentication master for users in the remaining AD instances (meaning users sign-in using their Windows credentials).
  • Continue to rely on Okta to provision to all AD instances.

When Instance-Level Del Auth is enabled, you can configure it in Directory > Directory Integrations > Active Directory > Settings. Your former org-level delegated authentication settings are preserved but no longer managed from Security > Delegated Authentication > Active Directory.

Configuring Import and Provisioning Settings

Options in this section allow you to configure import and provisioning settings, as well as make changes to your initial configuration.

IMPORT AND ACCOUNT SETTINGS

Select Directory > Directory Integrations > Active Directory and then select the Settings tab.

Separate OU selectors

Separate OU selectors for Users and Groups allows you to separately specify the OUs from which to import users, and from which to import groups. This also allows you to ignore the OUs that contain users or groups that you don't want in Okta.

  • User OUs connected to Okta – Select the organizational units from which to import users.
  • Group OUs connected to Okta – Select the organizational units from which to import groups.

To select all OUs, select the top folder. Or you can select individual OUs.

Note: If you are running a pre-3.3.5 version of the agent, changes to Group OU settings will not take effect for JIT Provisioning until you restart your agents. To avoid the need to restart agents each time you change this setting, upgrade all of your AD agents to version 3.3.5 or later.

This is an Early Access feature. To enable it, please contact Okta Support.

User and Group filters (EA)

Using filters allows you to perform granular imports from Active Directory. Create syntax queries to selectively import users matching the criteria that you specify.

Caution: Changing the default filter queries can result in deprovisioning users. To avoid unintended results, Okta strongly recommends that you test these filters in your directory environment to make sure that the results match your expectations.

Default queries:

  • User filtersAMAccountType=805306368
  • Group filterobjectCategory=group

For more about importing groups, see these related topics:

Just in-Time Provisioning (JIT)

Select Create and update users on login to create and update users at sign on. This option can be used with or without scheduled imports.

Okta JIT allows for the automatic creation of new user accounts at sign on, as well as updates to existing user profiles. The security groups to which the user belongs are also imported if the group belongs to a selected OU. If a user signing in does not belong to a selected OU, the sign in fails.

There are membership inconsistencies that can occur between “regular” imports and JIT provisioning. These membership anomalies may occur when using nested groups. During regular imports, a child group that is outside the scope of an AD OU or LDAP object filter cannot be detected. If a parent group is within an OU/object filter scope but its child groups are not, the parent group membership is incorrectly resolved during import. JIT provisioning would correctly resolve these memberships to the parent group because its function only detects "flat" memberships. 

JIT and AD Domains

For details about JIT and AD domain scenarios, see FAQ: Okta and AD Groups.

Delegated Auth and Desktop SSO

There are other forms of JIT that integrate with AD. Namely, delegated authentication for Windows environments, and Desktop SSO for imports that can be verified on the Imports page. For details, see Delegated Authentication.

Schedule import 

Determine how often you want Okta to import users from AD. Select Do not import new users to leverage scheduled imports to keep user profiles and groups in sync without importing new users from your directory. Use it when you only want to create new users in Okta via JIT, not via imports, yet continue to use imports to sync groups and group memberships.

Note: Following a successful import, under specific conditions Okta automatically sends an email to designated administrators. The email details the number of users and groups scanned, added, updated, or removed during the import. Okta only sends the email if the scan detects any new users or groups, or changes to any existing user profile or group membership.

Okta username format

Note: Orgs created after October 4th (Preview) or October 9th, 2017 (Production) may see slightly different import and provisioning options in the user interface elements described below. These changes will be rolled out to orgs created before these dates at a later date, which will be announced in the Release Notes. For details about the import and provisioning changes, see AD Updated Profile Mapping options.

Specify a username format. When you import users from AD, Okta uses this attribute to generate the Okta username. If you select SAM Account Name, Okta combines the SAM Account Name with the AD domain to generate the Okta username. For example, if the SAM Account Name is jdoe and the AD domain is mycompany.okta.com, then the Okta username is jdoe@mycompany.okta.com. When using the "SAM Account Name + Configurable Suffix" option, do not include the @ character before the Configurable Domain.

Note: All Okta users can sign in by entering the alias part of their user names as long as it maps to a single user in your organization. For example, jdoe@mycompany.okta.com could sign in using jdoe.

Activation emails

You can optionally select Don't send new user activation emails for this domain to prevent Okta from sending an activation email to new users.

USG support 

Select the Universal Security Group (USG) option if you want to ignore domain boundaries when importing group memberships for your users. This assumes that the relevant domains are connected in Okta.

You must also deploy an AD agent for every domain in your forest that contains the USG object that you want to sync with Okta. Each connected domain then imports its groups. When a user’s group memberships match any groups that were imported (from any connected domain in the forest), Okta syncs the memberships for the user to each group.  Only groups from connected domains are imported.

IMPORT MATCHING RULES

If there is an existing Okta account, AD allows you to import and confirm users automatically. Select the automatic confirmation option that matches the policies of your organization:

Note: This feature does not apply to CSV-imported user lists.

UIMatching_Old

Matching rules are used in the import of users from all apps and directories that allow importing. Establishing matching criteria allows you to specify how an imported user should be defined as a new user or mapped to an existing Okta user.

Imported user is an exact match to Okta user if: the match criteria that establishes whether an imported user exactly matches an existing Okta user. Choose any combination from the list of options to establish your criteria. For the new imported user to be considered an exact match, each option that you select must be true. Note that if you choose the third option, the first and second choices are disabled.

Allow partial matches: Partial matching occurs when the first and last name of an imported user matches that of an existing Okta user, but the user’s username or/and email address do not.

Confirm matched users: Select to automate the confirmation or activation of existing users. Unchecked, matches are confirmed manually.

Confirm new users: Select to automate the confirmation or activation of a newly imported user. If this option is selected, you can uncheck it during import confirmation. Note that this feature does not apply for users who already exist in Okta.

PROVISIONING FEATURES

Create Users 

Note: Orgs created after October 19th (Preview) or October 25th, 2017 (Production) may see slightly different import and provisioning options in the user interface elements described below. These changes will be rolled out to orgs created before these dates at a later date, which will be announced in the Release Notes. For details about the import and provisioning changes, see AD Updated Profile Mapping options.

Checking the Enable box creates or links a user in Active Directory.

  • Activation email recipient – Specify where to send the new AD account credentials. The recipient is responsible for distributing the credential information to the appropriate user.
  • AD username format – Specify a default AD username format.
  • AD common name format – Specify a default AD common name format.
  • Exclude AD username update – If you select this option, Okta does not update the user names of existing AD accounts that are Okta mastered when you change the default username format. You can still provision new AD accounts from Okta.

Update User Attributes

Okta updates a user's attributes in Active Directory when the app is assigned. Future attribute changes made to the Okta user profile automatically overwrite the corresponding attribute value in Active Directory. For details, see Enable Okta-mastered user OU changes.

This is an Early Access feature. To enable it, please contact Okta Support.

Update OU: Select this option to update an Okta-mastered user's OU when the group that provisions a user to AD changes.

Note: If an Okta-mastered user's OU changes in AD, that change will not be reflected in Okta since Okta is the master for that user. The next time the user is update in Okta, they will be provisioned back to the OU as set in Okta.

Deactivate Users

Deactivates users' Active Directory account when they are unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.

Profile Master

Enabled by default, profile mastering makes Active Directory the identity authority for connected users. When enabled, user profiles are not editable in Okta and all changes are synced to Okta during provisioning events. AD defaults as a profile master, but you can disable this option to have AD treated as a normal application.

If you disable AD as the profile master, user updates performed in AD are not pushed back to the user in Okta. For example, if you change a user's name in AD, the name change is not pushed to the Okta user account. In addition, you cannot reset a user's AD password in Okta because their credentials are still being managed by AD. You can, however, enable the Sync Password option to push passwords to Active Directory and disable Delegated Authentication. Your users will have their delegated Okta password, but any subsequent password updates are pushed to AD.

This is an Early Access feature. To enable it, please contact Okta Support.

LIFECYCLE SETTINGS

This section allows you to determine what happens when a user is deactivated in an app: should they be deactivated, suspended or remain an active user is Okta?

When a user is deactivated in the app

LC_Settings

  • Do Nothing: Prevents activity in the app from controlling the user life cycle. This still allows profile master control of attributes and mappings.
  • Deactivate Okta user: This default setting allows the user to be automatically deactivated when deactivated in the target app.
  • Suspend Okta user: This setting allows the user to be automatically suspended when deactivated in the target app.
When a user is reactivated in the app
  • Reactivate suspended users: Allows an admin to choose if a suspended Okta user should be reactivated when they have been reactivated in the app.
  • Reactivate deactivated users: Allows an admin to choose if a deactivated Okta user should be reactivated when they have been reactivated in the app.

Only the highest priority profile master for an Okta user can deactivate or suspend an Okta user. To verify the highest priority profile master, review the Profile Masters page.

Sync Password 

Enable this option if you want each user's AD password to be synced to their Okta password. Any subsequent password changes users make are pushed to their user profile in AD. To enable the Sync Password option, Delegated Authentication must be disabled. For more information, see Using Sync Password.

Profile Attributes & Mappings

For information about profile attributes and mappings, see Using Custom Attributes with Active Directory.

Registering Multiple Domains From One AD Agent

Okta AD integration support also allows you to set up multiple domains from one AD agent, reducing the number of servers or virtual machines you need to connect to multiple domains. After you install the AD agent, you can use the Okta AD Agent Management Utility to add more domains.

  1. On your Windows desktop, select Start > All Programs > Okta > Okta AD Agent > Okta AD Agent Manager.
  2. Select Domains.
  3. In the drop-down menu containing the grayed-out text choose another domain, select the domain that you want to add, and then click Register. Alternatively, you can type the desired domain name in the drop-down field, and then click Register.

If you have not entered your Okta administrator credentials, you are prompted to do so.

  1. A message appears stating that your new domain has been registered and prompting you to restart the agent. Optionally register additional domains. Restart your AD agent after you are finished.
Configuring High Availability by Installing Multiple Active Directory Agents

To configure high availability, you can install additional AD agents on separate servers or virtual machines. We recommend setting up two or more AD agents per domain.

Note: Installing multiple agents in close geographical proximity to your users does not enhance performance. When you have multiple agents installed, the process randomly selects which agent it uses so user location is not a factor. In addition, setting up large numbers of agents in this manner can cause problems when the system attempts to perform status checks on their performance.

Setting up a second AD agent follows the same steps as setting up your first agent. If you created the Okta service account with the first AD agent, then you are prompted to enter your password during the second agent installation.

To install additional AD agents on a domain:

  1. Select Directory > Directory Integrations.
  2. Click Active Directory.
  3. Select the Settings tab. Your agents are listed in the Agent Monitors section.
  4. Click Add Agent.
  5. Run the installer as described in Installing the Active Directory Agent.

You can check the status console in the Admin app to make sure that the second agent was installed. A green circle next to the agent name indicates the agent is connected and healthy.

AD Agent Request Handling

Each agent connects to the Okta service independently. When the service needs to communicate to AD (for example, to authenticate a user), it picks one of the available agents and sends it a task to complete. If one of the agents becomes unavailable, it is automatically removed from the queue and not given additional tasks.

Agent Availability

Agents send periodic messages to the service. If the service does not receive a message for 120 seconds, it is marked as unavailable.

Domain Controller Selection

The AD agent relies on the underlying operating system to select which domain controller to communicate with.

Changing the AD Agent User

  1. Sign in to the server running the AD Agent.
  2. From the Start menu, type run, then type services.msc.
  3. Locate the Okta AD Agent Service.
  4. Right click the Okta AD Agent Service and select Properties.
  5. Select the Log On tab and change the account credentials.
  6. Restart the service and verify that the agent displays as green in your Okta org.
Configuring the Number of Threads the AD Agent Uses

You can configure the number of threads the AD agent uses to poll the server for tasks. If you are running the AD agent on a large-scale server, you can increase the thread count as an alternative to using multiple AD agents.

For example, to create three instances, do the following:

  1. Before opening or modifying the AD agent configuration files, stop the AD agent service under Windows Services.
  2. From the terminal, locate the OktaAgentService.exe.instances.config file for each AD agent server: 

    C:\Program Files (x86)\Okta\Okta AD Agent\OktaAgentService.exe.config

  3. Open the 'OktaAgentService.exe.config' file in a suitable text editor program and then locate the following line:

    <add key="PollingThreads" value="2" />

    The default value is 2 and the valid range is 1 - 10. As an example to increase the number of polling threads to four, edit the line to look like this:

    <add key="PollingThreads" value="4" />

  4. Save the file.
  5. Start the agent.
  6. Once the change has been made, save the file and then start the Okta AD agent service again. You can verify that the setting has changed by opening the agent.log file at startup and observing the startup information towards the bottom of the file:

    2017/07/21 06:06:22.167 Debug – TEST-SERVER-1(4) – PollingThreads: 4

Now the agent has four concurrent polling threads searching for actions to perform.

Note: There is a 10 thread limitation for this feature.

Troubleshooting

Error when resetting a Windows password

If the following error displays when your end users try to reset their Windows password in Okta,

New Windows password: Unexpected error when changing password, please try again

. . . and the following description was written to Reports > System Log at the same time,

UnavailableCriticalExtension

. . . then you are probably not enforcing Active Directory's Password History policy. To enforce the policy, make sure that your Okta AD Agent is version 3.4.1 or later and your Domain Controllers are running Windows Server 2008 R2 or later.

Error when installing the agent

During agent installation, if the error message displays,

The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel

. . . then you are probably attempting to install a version of the AD agent in which SSL pinning is enabled by default and your environment is one in which the agent's support for SSL certificate pinning prevents communication with the Okta server. This is most likely to occur in environments that rely on SSL proxies. To allow installation to complete in this case, Okta recommends that you bypass SSL proxy processing by adding the domain okta.com to a whitelist.

Alternatively, if SSL certificate pinning is enabled you can choose to disable it as described below.

To disable SSL certificate pinning if it is enabled

  1. Perform steps 1 through 4 of the procedure Installing the Active Directory Agent.
  2. Instead of double-clicking the file as directed in step 5, open a command line terminal and enter the following:

OktaADAgentSetup.exe OktaDisableSslPinning=1

  1. Press Enter.
  2. Complete the installation as described in Installing and Configuring the Agent.

To re-enable support for SSL certificate pinning if it is disabled

  1. Locate and open the AD agent configuration file:

    C:\Program Files (x86)\Okta\Okta AD Agent\OktaADAgentSetup.exe.config

  2. Change the SSL pinning enabled setting to True:

    "SslPinningEnabled" value="True"

  3. Save the configuration file and restart the agent.

For more information about SSL certificate pinning, see the article by the Open Web Application Security Project.

Post a Comment