Active Directory integration prerequisites

This topic provides the prerequisites for Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management. integrations.

Topics

Hardware

To install the Okta AD agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations., 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

Operating system and software

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 domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). 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:

Required accounts

Create an Okta admin 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.

  1. Sign in to your Okta Super admin account.
  2. Click Admin to open the Okta Admin Console.
  3. Click Directory > People > Add Person.
  4. Complete the fields and click Save.
  5. Click Security > Administrators > Add Administrator.
    1. 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.
    2. 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).

AD user account to run the AD agent installer

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.

Okta service account to run Okta AD agent service

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 Windows server you need to configure delegation to 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 OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority. or domain name, and select Delegate Control which will open the Delegation of Control Wizard.
  3. 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.

Okta service account permissions

Before adjusting the permissions on your directory, make sure you understand how Active Directory permissions are set and plan how to manage permissions within your environment.

By default, the Okta AD agent installer creates a new Okta service account if you do not choose an existing account. The newly created OktaService account inherits the permissions of the Domain Users group. OktaService is also considered to be a member of the Authenticated Users and Everyone special identity groups when the agent is running.

The Okta AD agent Management Utility also includes the option of adding the OktaService account to the Domain Admins group. If you require functionality listed below but don't want to make your service account a full admin, make sure the following permissions are set.

Provision user

  • Requires create child permission for user objects on the target OU.
  • Requires Reset Password Control Access Right permission for user objects within your target OU.
  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permission on user objects within your target OU for all other attributes mapped on the AD user profile within Okta https://<orgThe Okta container that represents a real-world organization.>/admin/universaldirectory

Update user attributes

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • mail
    • userPrincipalName
    • SAMaccountName
    • givenName
    • sn
    • userAccountControl
    • pwdLastSet
    • lockoutTime
    • cn
    • name
  • Requires write property permission on user objects within your target OU for all other attributes mapped on the AD user profile within Okta https://<org>/admin/universaldirectory

Group push

  • Requires create child permissions for group objects on the target OU.
  • Requires delete child permissions for group objects on the target OU.
  • Requires write property permissions on group objects within your target OU for the following attributes:
    • sAMAccountName
    • description
    • groupType
    • member
    • cn
    • name

Reset password, forgot password , and sync password

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • lockoutTime
    • pwdLastSet
  • Requires Reset Password Control Access Right permission for user objects within your target OU.

Activate and deactivate user

  • Requires write property permissions on user objects within your target OU for the following attributes:
    • userAccountControl

Reference commands:

You can add the permissions listed here using the commands below. Save them to a batch file and change the target OU and service account info to be correct for your environment. Remember to remove permissions you do not need and add any attributes you have mapped for provisioning within Okta. You can get the complete list of user attributes from your Directory user profile on https://<org>/admin/universaldirectory.

# Create User

dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CC;user

# Create or Update user

# include additional attributes that are mapped in your org within Okta

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;mail;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userPrincipalName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;givenName;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sn;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;userAccountControl;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;pwdLastSet;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;lockoutTime;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;user

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;user

# Create user/Password Reset

dsacls "OU=targetOU,DC=domain" /I:S /G "domain\agentserviceaccount:CA;Reset Password;user"

#Group Push

dsacls "OU=targetOU,DC=domain" /G domain\agentserviceaccount:CCDC;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;sAMAccountName;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;description;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;groupType;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;member;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;cn;group

dsacls "OU=targetOU,DC=domain" /I:S /G domain\agentserviceaccount:WP;name;group

Top