Install the Okta Active Directory agent

Download and install the latest version of the Okta AD agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations. on your host server(s) to make sure that you have the most current features and functionality and get optimum performance. If you are running multiple Okta AD agents, make sure they are all the same version. Running different versions within a domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.

To download the agent from another computer, copy the Okta AD agent installer to the host server.

If you're installing the Okta AD agent on a DMZ server, you must open specific ports. See Configure DMZ server ports for Active Directory integrations

  1. On the host server, sign in to the Okta AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Console with Super Admin permissions.
  2. Click Directory > Directory Integrations.
    1. Click Add Directory and then select Add Active Directory.
    2. Review the installation requirements and click Set Up Active Directory
    3. Click Download Agent.
  3. On the host server, locate the downloaded file and double-click the file to launch the installer.
    1. Click Yes when the message Do you want to allow the following program to make changes to this computer? appears.
    2. Choose an installation destination. Click Next.
    3. Select the AD domain you want to manage with this agent. Click Next.
    4. Select a domain user for the Okta AD agent to run as and click Next:
      • Select Create or use the Okta Service account (recommended) and complete the prompt to set a password. Okta recommends using a complex password for security.
      • Select Use an alternate account that I specify if you want to assign the Okta AD agent to run as an existing domain user.
    5. Optional — If appropriate for your environment, specify a proxy server through which your AD agent will connect. Click Next.
      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.
    6. To register the Okta AD agent with the Okta service, enter your Okta subdomain name. This is the <mycompany> part of the example: <mycompany> Click Next.
    7. On the Okta Sign In page, enter your admin username and password, and then click Sign in.
    8. The Okta AD agent requires several permissions. Click Allow Access. The agent installation completes.

      If the error message The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel, appears you are likely installing a version of the Okta AD agent with SSL pinning enabled by default and this prevents communication with Okta. This is most likely to occur in environments that rely on SSL proxies. To complete the installation, Okta recommends adding the domain to a whitelist to bypass SSL proxy processing. You can also disable SSL certificate pinning.

    9. Click Finish.
  4. When the Okta AD agent starts, return to the browser and click Next. On the following screens you will select some basic configuration options. You can change these and other settings at a later time.
    1. (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 groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups..
    2. Select the Okta Username format that you want AD-imported end usersEnd users are people in your org without administrative control. They can authenticate into apps from the icons on their My Applications home page, but they are provisioned, deprovisioned, assigned, and managed by admins. to use when logging in to Okta and then click Next. Choose from:
      • Email address
      • SAM Account Name
      • User Principal Name (UPN)

      It is critical that the username format selected here be the correct format when you first import users. Changing the value can cause errors for existing users.

    3. In the Import AD Users and Group dialog, click Next.

    Note: To reconfigure OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority. and import settings, as well as other settings, return to the Settings tab (Directory > Directory Integrations > Active Directory > Settings). For details, see Configure import and account settings.

  5. On the Build User Profile tab, accept the default attributes or select the specific attributes for your Okta user profiles. Attributes can be modified as the needs of your business change. Click Next.

    To learn more about Okta user profiles and attributes, see Work with user profiles and attributes.

  6. Click Done.
  7. Define the import, account, and provisioning settings.

Next steps