Active Directory integration prerequisites
This topic provides the prerequisites for Active Directory integrations.
To install the Okta AD agent, one or more Windows servers are required. These servers are called host servers. These host servers must be on at all times 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 2 CPUs and a minimum of 8GB RAM
Download and install the latest version of the Okta AD agent 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 domain can cause all agents in that domain to function at the level of the oldest agent. This does not affect other domains.
- The host server should run Windows server 2008 R2 or later, including Server 2016 and Windows Server 2019 — You need access to a Windows server to install the Okta AD agent. You do not need to install the agent on the domain controller. Your system must have 20MB memory for the AD Service Account that is created during the agent installation.
Note: You must be running IE 10 or later on your Windows server.
.NET 4.5.2 (minimum) up to .NET 4.6.x If you have a lower version of .NET, upgrade to 4.5.2 or higher.
- To improve the security of AD integrations, the default security protocol is TLS1.2 for orgs running .NET Framework 4.5 or later. For Windows 2008 R2 TLS 1.2 is disabled by default and needs to be enabled through the registry. See AD agent does not connect at startup.
- AD domain/forest functional level — Okta supports an AD domain/forest functional level of 2003 and higher. For additional information on AD domain functional levels, see: https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/plan/security-best-practices/understanding-active-directory-domain-services--ad-ds--functional-levels
- If you are using the 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. It is recommended 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 do not 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 the AD Password History policy, you must use Okta AD agent version 3.4.1 or later and your AD Domain functional level should be Windows server 2008 R2 or higher.
- High availability — To ensure high availability and redundancy, install the agent on two or more computers.
- Number of agents — If there are 30K or more users, deploy a minimum of 3 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.
- Okta admin account — Used when you install the AD agent to allow the AD agent to connect to Okta. This account should be Okta-mastered, not AD-mastered. The minimum admin role required for this account is Super admin.
- AD service account — Required to install the Okta AD agent. It is important that the service account has permissions in all domains in that forest to read and access user data in all domains to which the agent connects.
- Okta service account to run Okta AD Agent service — This is an AD domain service or user account. It can be created by the installer (called OktaService by default) or you can select an existing account.
For installation, you need an Okta account, not an AD account, to connect the AD agent to Okta. To create this account, you must be a Super admin.
Okta recommends that you use a dedicated Okta admin account for the AD agent. If you use an individual's Super admin account to install and run the AD agent, and that individual later has their admin privileges lowered, revoked, or deactivated, the Okta AD integration stops working. If this occurs, you need to uninstall the existing AD agent and reinstall the AD agent with a new Super admin account to reconnect Okta to AD.
- Sign in to your Okta Super admin account.
- Click Admin to open the Okta Admin Console.
- Click Directory > People > Add Person.
- Complete the fields and click Save.
- Click Security > Administrators > Add Administrator.
- In the Grant Administrator role to field, start entering the name of the user you added in step 3 and select the user from the list.
- Select the administrator role for the user. The Super Administrator role is the minimum permission needed for agent installations. For admin permissions information, see Administrators.
Okta recommends that the Okta AD agent admin accounts are Okta-mastered and not AD-mastered. This does not affect existing AD mastered administrators. It is recommended that you to disconnect your admins from AD (select Directory > People > More Actions > Disconnect from AD, select the admin users who you want to disconnect, and then click Disconnect Selected).
Okta recommends you use the same AD service account to install all of your agents. During agent installation, you are asked if you want the installer 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.
The Okta service account can be created by the installer. By default it is called OktaService. If you choose to use an existing domain user account, be sure to set the account password to never expire. Managed Service accounts are not supported.
During installation, you are asked if you want to let the installer create the Okta service account. To do so, you must have the following permissions:
- Be a member of the domain admins group. This is required because you must be able to create a new AD user in AD that will act as the AD agent service account.
- Have local administrator privileges. If you are 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 you select.
Okta service account permissions
The AD agent runs under the Okta account you specified (either the Oktaservice account the installer creates or the domain user you select 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 permission to do this. We recommend read access on the entire domain, but it is not 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 are updating.
Configure delegation for the Okta Service account
- On your AD Domain controller, open the Active Directory Users and Computers snap-in.
- Right click the OU or domain name, and select Delegate Control which will open the Delegation of Control Wizard.
- Add the Okta service account and select the appropriate 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.