Install the Okta Active Directory agent

Download and install the latest version of the Okta Active Directory (AD) agent on your host servers 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 domain can cause all agents in that domain to function at the level of the oldest agent. This doesn't 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, open a web browser and sign in to the OktaAdmin Console with Super Admin permissions.
  2. In the Admin Console, go to DirectoryDirectory 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 and double-click the installer .exe file and complete the installation:
    1. Click Run when the message Do you want to run this file? appears.
    2. Click Next.
    3. Accept the default installation folder, or click Browse and select an alternate location. Click Install.
    4. Accept the default AD domain you want to manage with this agent, or enter a domain name in the Domain field. Click Next.
    5. Select a domain user for the Okta AD agent to run as:
      • Select Create or use the OktaService 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.

      6. If you're using a group Managed Service Account (gMSA) for the Okta AD agent service account, enter the account name and leave the Password field empty. You must include a dollar sign ($) at the end of the account name. For example, gMSA01$@example.com.

    6. Click Next.
    7. Optional. Specify a proxy server through which your AD agent will connect.
      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 default settings are used.
    8. Click Next.
    9. Select a domain to register the Okta AD agent with Okta. To register the Okta AD agent with the Okta service, enter your Okta subdomain name. This is the <mycompany> part of the example: <mycompany>.okta.com.
    10. Click Next.
    11. On the Okta Sign In page, enter your admin username and password, and then click Sign in.
    12. 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 okta.com to an allowlist to bypass SSL proxy processing. You can also disable SSL certificate pinning.

    13. Click Finish.
  4. When the Okta AD agent starts, return to the browser and click Next.
  5. Select the configuration options:
    1. (First time installations for this domain only) On the Connect an Organizational Unit to Okta screen, select the OUs from which you want to import users and groups.
    2. In the Okta Username format list, select one of these formats that you want AD-imported end users to use when logging in to Okta:
      • Email address
      • SAM Account Name
      • User Principal Name (UPN)
      • Custom

      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. Click Next.
    4. In the Import AD Users and Group dialog, click Next.

    Note: To reconfigure OU and import settings, as well as other settings, return to the Settings tab (DirectoryDirectory Integrations Active DirectorySettings). See Configure Active Directory import and account settings.

  6. On the Select the attributes to build your Okta User profile screen, 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.

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

  7. Click Next.
  8. Click Done.
  9. Define the import, account, and provisioning settings.

Next steps

Configure Active Directory import and account settings

Configure Active Directory provisioning settings