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 custom admin account: Used when you install the AD agent to allow the AD agent to connect to Okta. This account should be Okta-sourced, not AD-sourced.
  • AD user account with Domain Admin permissions: Required to run the Okta AD agent installer. It's a good practice to use the same AD service account to install all Okta AD agents. You can choose to have the installer create the Okta service account during installation.
  • Okta service account to run Okta AD Agent service: This is an AD domain service or user account. The installer can 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.

Create a custom admin account

Custom admins can view, register, and manage agents. For installation, you need an Okta custom admin account, not an Active Directory (AD) account, to connect the AD agent to Okta. See Custom admin roles.

A best practice is to use a dedicated custom admin account for the AD agent. Suppose you use an individual's super admin account to install and run the AD agent. If that individual later has their admin privileges lowered, revoked, or deactivated, the Okta AD integration stops working. Restoring the AD integration requires that you uninstall the existing AD agent and then reinstall the AD agent with a new super admin account to reconnect Okta to AD.

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

AD service account to run the Okta AD agent installer

Okta recommends that you use the same AD service account to install all of your agents. During agent installation, 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.

Okta service 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). 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 attribute(s) 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.