Install the Okta Active Directory agent

Download and install the latest version of the Okta Active Directory (AD) agent on each of your host servers. This ensures that you have the most current features and functionality and get optimum performance.

If you're running multiple Okta AD agents, make sure they're 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. Other domains aren't affected.

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 Okta Admin Console using an account with suitable permissions. See Okta account with required 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 Yes when the message Do you want to allow this app to make changes to your device? appears.
    2. Click Next.
    3. Accept the default installation folder, or click Browse and select an alternate location. Click Install.
    4. Click Next.
    5. Accept the default AD domain that you want to manage with this agent, or enter a domain name. Click Next.
    6. 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. Use a complex password for better 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. If you choose this option, you must ensure that the account has the permissions listed in Okta service account permissions.

      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. Include a dollar sign ($) at the end of the account name. For example, gMSA01$@example.com.

    7. Click Next.
    8. Optional. Specify a proxy server through which your AD agent connects. If you don't specify a proxy server, the installer detects and uses the default proxy settings.
    9. Click Next.
    10. Enter your Okta org URL. For example, https://mycompany.okta.com. Click Next.
    11. Click the activation link (for example, https://mycompany.okta.com) and enter the code displayed by the installer.
    12. On the Okta Sign In page, sign in using an account that has permission to manage directories, and to manage and register agents.
    13. Permission is required to register the agent with Okta. Click Allow Access. The agent installation completes.

      The error message "The underlying connection was closed. Could not establish trust relationship for the SSL/TLS service channel" may appear. It indicates that you're likely installing a version of the Okta AD agent with SSL pinning enabled by default, which prevents communication with Okta. This is most likely to occur in environments that rely on SSL proxies. To complete the installation, add the domain okta.com to an allowlist to bypass SSL proxy processing. You can also disable SSL certificate pinning.

    14. 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 page, 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

      The username format that you select must be correct 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.

    To reconfigure your OU, import, and 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 page, 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.

Next steps

Configure Active Directory import and account settings

Configure Active Directory provisioning settings