Active Directory integration prerequisites

This topic provides the prerequisites for Active Directory (AD) integrations.

Hardware

A minimum of one Windows server is required to install the Okta AD agent. These servers are called host servers. These host servers must always be on and have a continuous connection to the internet so that they can communicate with Okta.

  • The host server can be a physical or virtual server.
  • The server should have at least two CPUs and a minimum of 8 GB RAM.

Operating system and software

Download and install the latest version of the Okta AD agent on 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.

  • Host server running Windows Server 2016, Windows Server 2019, or Windows Server 2022: You need access to a Windows server to install the Okta AD agent. You don't need to install the agent on the domain controller. Your system must have 20 MB memory for the AD service account that's created during the agent installation.

  • .NET 4.6.2 or later. If you have an earlier version of .NET, upgrade to 4.6.2 or later.

  • To improve the security of AD integrations, the default security protocol is TLS 1.2 for orgs running .NET Framework 4.5 or later.
  • AD domain/forest functional level: Okta supports an AD domain/forest functional level of 2003 and later. See Forest and Domain Functional Levels.
    • If you're using an AD domain functional level of 2003, AD usernames must be in the domain name format. That is, users must have a UPN that contains the @domain.name format.
  • Member server: The host server can be a member server in your AD domain or a domain controller. Okta recommends that you use a member server.

  • Run the setup wizard from the host server: Run the agent setup wizard in a web browser on the host server where you want to install the agent. If you don't follow this recommendation, you must transfer the agent installer to the host server and then run it.

  • Must be a member server within your active directory forest: The host server can be in a different domain than the domain that your users reside, but it must be in the same AD forest. Placing the agent on a different domain may cause performance issues.
  • AD password history policy: To enforce this policy, you must use Okta AD agent version 3.4.1 or later, with an AD Domain functional level of Windows Server 2016 or later.
  • High availability: To ensure high availability and redundancy, install the agent on two or more computers.
  • Number of agents: If there are more than 30,000 users, deploy a minimum of three AD agents.

You also need to determine:

  • The username format to use when importing AD users into Okta (email, samAccountName, UPN, or custom)
  • Which OUs to import users and groups from
  • Which AD attributes to import to the Okta user profile

Required accounts

  • Okta account with required permissions: Sign in to Okta with an account that has the permissions required to install the AD agent and allow the AD agent to connect to Okta. This account should be Okta-sourced, not AD-sourced.
  • AD admin account to run the Okta AD agent installer: Required to run the Okta AD agent installer. This account must have permissions in every domain in the forest to read and access user data in the domains that the agent connects to.
  • AD domain user account to run Okta AD agent service: This is an AD domain service or user account. During installation, you can choose to have the installer create this account—called OktaService by default—or you can select an existing account. The Okta service account must have permissions in every domain in the forest to read and access user data in the domains that the agent connects to. It's a good practice to use the same AD service account to install all Okta AD agents.

Okta account with required permissions

To install the agent, you need to use an account that has the manage directories, manage agents, and register agents permissions. A best practice is to create a custom admin role that has these permissions. Assign that role to an Okta account to connect the agent to Okta. See Create a role and Agent permissions.

Directory permissions are required when creating an app instance with the AD agent. See Role permissions.

For greater security, consider requiring your admins to use MFA to access the Admin Console. See Enforce MFA to access the Admin Console.

Starting with version 3.18.0, the AD agent operates independently of any Okta account. This ensures that the Okta AD integration will continue to work as expected, regardless of the status of the account used to register the agent. For example, in version 3.17.0 and earlier, a dedicated account was often used to register the agent. If the privileges for that account were changed (for example, lowered or revoked), or the account was deactivated, the AD agent would stop working.

AD admin account to run the Okta AD agent installer

When you install the agent, you're asked if you want the installer to create the Okta service account. You need one of the following based on your choice:

  • An AD domain admin account if you want to let the installer create the Okta service account.
  • An AD user account that has local administrator privileges on the host server if you want to use an existing domain user account as the Okta service account.
  • If you chose the Use an alternate account that I specify option during installation, the AD user account must have read access rights to the OU. This requirement also applies to the OktaService account.

AD domain user account to run Okta AD agent service

During installation, you can choose to have the installer create the Okta service account. By default it's called OktaService. If you choose to use an existing domain user account, be sure to set the account password to never expire. Okta AD agent supports managed service accounts in version 3.6.0 and later.

To have the installer create the Okta service account during installation, you must meet the following requirements:

  • Be a member of the domain admins group. This is required because you must be able to create an AD user to act as the AD agent service account.
  • Have local administrator privileges. If you're 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 that you selected.

Okta service account permissions

The AD agent runs under the Okta account that you specified (either the OktaService account that the installer creates or the domain user that you selected during the agent install).

If you choose to use a domain user as the service account, you must ensure that the user has the permissions listed in Okta service account permissions.

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 permissions to do this. Read access on the entire domain is recommended, but it isn't 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 attributes that you're updating.

Configure delegation for the Okta Service account

On your Windows server you need to configure delegation to the Okta service account in your AD domain based on your needs.

  1. On your AD Domain controller, open the Active Directory Users and Computers snap-in.
  2. Right-click the OU or domain name, and then select Delegate Control.
  3. In the Delegation of Control Wizard. add the Okta service account and select the tasks to delegate:

    • 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.

Related topics

Install the Okta Active Directory agent

Okta service account permissions