The Okta Active Directory (AD) agent Deployment Guide
This guide provides the information you need to plan, install and configure your 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. integration.
Depending on the size and complexity of your Okta AD integration, you will work your way through select topics based on whether or not they apply to your environment and how familiar you already are with Okta. Some topics may apply to all integrations, such as installing the agent. Others are more applicable for larger enterprise customers, for example disaster recovery.
Table of contents
- Before you install: considerations and best practice
- Install the Okta AD agent
The Okta Active Directory (AD) agent enables you to integrate Okta with your on-premise Active Directory (AD). AD integration provides delegated authentication supportenabling users to sign in to Okta with their AD credentials, user provisioningassigning users to apps and de-provisioningremoving users from apps. To enable AD integration, you must install the Okta AD agent, and import AD usersIn Okta literature, we generally refer to "users" as the people who serve as Okta administrators. When we refer to "end users" we are generally referring to the people who the administrators serve. That is, those who use Okta chiclets to access their apps, but have no administrative control. and groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups. into Okta.
AD integrations in a newly-created organization automatically have the following default settings enabled:
- Delegated authentication — Allows your end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using chiclets to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. to sign in to Okta with their AD credentials.
- The import schedule set to never — You can choose your import options in the configuration steps below.
- Profile mastering — This refers to which application is the source of truth for user data. By default, AD is the profile masterA profile master is an application (usually a directory service such as Active Directory, or human capital management system such as Workday) that acts as a source of truth for user profile attributes. A user can only be mastered by a single application or directory at any one time. For more details, see Using the Okta People Page. when the agent is installed.
There are two common AD scenarios, as illustrated by the diagrams below.
How you approach your Okta AD integration will depend on your organization's size, needs and scopeA scope is an indication by the client that it wants to access some resource. of deployment. In general, there are two main approaches:
- Proof of Concept (POC) or simple deployment — If you're doing a POC or have a relatively simple AD integration, you may prefer to jump right in to installing the Okta AD agent and get started importing some users and setting up the basics. You may not want or need to do a lot of planning around high availability (HA) or disaster recovery (DR), or which attributes you will import from your AD user profiles into the corresponding Okta user profile.
- Large scale enterprise deployment — Larger enterprise deployments may do more upfront planning of their Okta AD agent integration before beginning the agent installs and importing user data.
Which ever approach you take, you are always able to come back to the configuration options and make changes as your implementation evolves.
This guide includes sections to help you plan your implementation, including:
- Agent performance information
- High Availability (HA) and Disaster Recovery (DR)
- AD Domains and Cross-forest scenarios
This section covers our recommendations and best practices for HA and DR scenarios. We recommend you review these guidelines and decide what and how to implement given your organization's fault tolerance and DR processes. The specific implementation details will depend on the unique requirements of your organization.
The Okta AD agent does not perform load balancing. Traffic is directed to the first available agent.
Some questions you'll need to answer:
- Who owns your organization's DR or HA processes and who needs to be consulted?
- How many data centers do you have?
- How are they used? That is, which ones are live (hot) all the time and which ones are backups (cold).
- What kind of fail over do you want to plan for? You can have agent redundancy, in the event an individual agent fails. Or you can plan for the failure of an entire data center (that is, all agents in that data center).
- Are the AD 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). controllers live all the time?
- Are they actively replicated to?
- Is there a significant latency in replication between the data centers? This can cause replication problems.
The easiest way to illustrate your options is with an example scenario.
Example Corp has three data centers:
- A physical data center in Atlanta that is always live.
- An AWS data center that is always live.
- A cold backup data center that is only used for complete DR scenarios if the two live data centers go offline.
The first point to note is that it does not matter to the Okta AD agent whether it is a physical or virtual data center. So the Atlanta and AWS data centers are the same from the point of view of the Okta AD agent.
If Atlanta and AWS are both live all the time, and each have one or more agents installed, then traffic will be routed to the active agents, regardless of the agent location. The cold backup data center cannot have an active agent installed on it, since traffic is routed to all active agents.
While it is possible to install agents on servers in your cold data center, these agents will be listed as inactive in your Okta adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. dashboard. After 30 days of inactivity, the API token assigned will expire. As a result, you will have to re-install the agents if switching over to your cold backup. Because of this, Okta does not recommend installing agents on servers in your cold data center.
What is the minimum number of agents you want installed in each data center? Having only one agent installed in each center increases your risk. With a minimum of two agents, you will at least have a backup if one agent fails. Actual performance depends on the number of active users you have. You'll need to consider what your fault tolerance is and what HA or DR scenarios you want to prepare for:
- Atlanta experiences full failure, AWS picks up the traffic. If AWS then fails, the cold data center is brought online.
- If either Atlanta or AWS fail, the cold data center is brought online.
The final count
Ultimately the final decision rests with your organization. Ask yourself:
- What is our risk tolerance?
- Are we planning for individual agents or the machine they are installed on going down, or entire data centers?
- How do the Okta recommendations fit in with our existing HA and DR procedures?
When planning your AD integration, we recommend taking a look at your existing AD implementation.
- How many domains do you have?
- What kind of trusts are in place?
- What forests do you have?
- Which OUs do you plan to import into Okta?
- Are there users or resources in those OUs that you do not need to import into Okta?
The Okta AD agent does support communication across domains. However, the Okta AD agent cannot communicate across forests.
An agent must be installed in each forest and each domain in a forest where there are users you intend to import into Okta. While is it possible to register multiple domains to a single agent, be aware that if the agent goes down, all domains will be impacted.
Resource forests do not need agents installed in them because there are typically no users in the forest, just network resources.
Installing the Okta AD agent requires the use of an AD service account. It is important that the service account has permissions in all domains in that forest to read and access users in all domains to which the agent connects. For details about the service accounts required to install the agent, see Accounts required for AD agent installation.
This section contains some general considerations to keep in mind about your AD environment before you begin integrating with Okta.
Select the AD attributes in AD that you want to sync with Okta or a downstream appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. carefully and check to be sure that your organization is using those attributes for their intended purpose. If you are mapping the same data from two or more domains into one, you should ensure the data is consistent. If the domains share an attribute but that attribute is user for different values, this will create a problem once the attribute is merged into Okta.
There is a custom attribute "Attribute 1" that is being used in Domain A to store users' employee badge numbers and in Domain B it is being used to store the last four digits of their corporate credit card. When you map users from Domain A and Domain B into Okta, Attribute 1 will be mapped as an attribute in Okta. However, the value of that attribute will be referring to two different pieces of data depending which user you are looking at.
In this situation you have several options:
- Clean up the data across the different domains so that the attribute values are consistent.
- Create completely different attribute mappings between Okta and each of your AD domains. In this case, Okta recommends that you still clean up the data at a later time.
- Take advantage of Attribute Level Mastering.
We recommend that you only bring into Okta the attributes that you require. For example, if in AD you have a t-shirt size attribute, but do not need that attribute in Okta or any down-stream applications, do not import that attribute into the Okta user profile. You can always include more attributes at a later time as you require them. However, removing attribute mappings is more difficult.
Even if you remove the attribute mapping, Okta still holds the data that has already been imported. To actively remove the attribute data in Okta, you will have to intentionally map a blank value to the attribute in the Okta user profile.
Installing the Okta AD agent requires the use of an AD service account. It is important that the service account has permissions in all domains in that forest to read and access users in all domains to which the agent connects.
In general, Okta recommends you use the same AD service account to install all of your agents. This simplifies maintenance on the service account itself such as password rotation, so that the agent isn't negatively impacted.
Planning for agent updates will depend on your current change management process. Treat an agent update the same as any standard server patch process. Update each agent one or two at a time, sequentially and consistently. Avoid taking all agents down at the same time.
Agent updates can be installed over existing agents. There is no need to uninstall the existing agent first. It is possible to uninstall the existing agent and install the updated agent version. However, this requires additional steps to ensure a complete and clean uninstall.
As with all updates and configuration changes, Okta recommends that you upgrade your Okta Preview environment first to ensure everything is working correctly before upgrading your Production environment.
Okta Active Directory (AD) integration allows you to integrate Okta with your on-premise AD. AD integration provides delegated authentication support (allowing users to sign in to Okta with their AD credentials), user provisioning and de-provisioning, and the ability to import users and AD security groups.
There are several steps you must complete to integrate with AD, including:
- Install and configure the Okta Active Directory (AD) agent
This includes the following topics:
- Welcome to Okta Product Documentation. — OS, hardware, and account requirements
- Welcome to Okta Product Documentation. — How to install the AD agent.
- Welcome to Okta Product Documentation. — Basic configuration settings for how users get imported into Okta.
- Optional Provisioning settings, including:
- May apply, depending on your environment:
- Install and configure the Okta Active Directory (AD) agent— If you need to change the Okta service account running the agent.
- Install and configure the Okta Active Directory (AD) agent — Improve performance and availability.
- Install and configure the Okta Active Directory (AD) agent — An alternative to using multiple agents.
- Import Active Directory users
Includes the following topics:
- Import Active Directory users using on of the following methods:
- Confirm imported users — Based on the matching rules you set, confirm that the imported AD users have been imported correctly.
- Activate user accounts — Activate the Okta user accounts and send the activation email with the user's password so they can log into Okta.
After you have completed the steps above, your basic AD set up is complete, although you may want to iterate your profile attributes and other settings as you refine your Okta deployment needs.
The topics below are advanced and optional concepts and tasks which may apply to you, for you to explore as needed.
This includes the following topics:
- Adding and Removing Custom AD attributes — Customize which AD attributes are included in the AD app user profile.
- Base AD attributes — List of the 10 basic attributes that AD requires. All other AD attributes are considered custom attributes.
- Active Directory attribute mappings — Table showing how the AD attributes map to Okta attributes. As you are building your Okta and AD user profiles you will need to know how the AD attributes map to Okta attributes.
- Mapping Profile attributes — How to create a mapping between an Okta user profile and an app user profile.
- Expressions — How to configure expressions, override user names, and exclude AD user name updates during provisioning.
- Understand how Okta user profiles and attributes work
Includes the following topics:
- About Universal Directory and user profiles Concepts include:
- Profiles — Representations of user accounts. Okta supports 2 types of profiles: Okta end user profiles and App user profiles.
- Mappings — Allows you to precisely control the attributes exchanged during provisioning processes.
- Expression Language transformations — Allows you to concatenate attributes, manipulate strings, convert data types, and more.
- Username Overrides — Construct custom Okta user names or application user names.
- Rich SAML Assertions — UD attributes can be sent in SAMLAn acronym for Security Assertion Markup Language, SAML is an XML-based standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider (SP). The SAML standard addresses issues unique to the single sign-on (SSO) solution, and defines three roles: the end user, the IDP, and the SP. assertions and WS-Fed claims.
- Work with Okta user profiles and attributes
- About Universal Directory and user profiles Concepts include:
- Learn about Profile Masters and Attribute Level Mastering
- Learn about Okta's Security policies. — Okta policies allow control of various elements of security, including end-user passwords, the authentication challenges a user receives, the devices they can use, and the places they use them from.
Disconnect user from Active Directory — You can disconnect users who were imported from Active Directory (AD) so that they become native Okta users, allowing you to edit user fields or prevent updates from being synced from AD.
What permissions does the Okta AD Agent Management Utility require?
The default permission is domain administrator. For details, see Minimum Okta Service Account requirements.
Can I create the Okta service account myself?
Yes, you can create or use an existing AD service account for the agent install if you do not want the install process to create one for you.
Can I move the Okta service account to a different OU?
Yes. You can move the account after installing the agent. For example, to an 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. reserved just for service accounts.
How do I change the Okta service account password?
It is best practice to intermittently change the password for the Okta Service Account that was used to install the Okta AD agent.
To change the password:
- In Active Directory, use the Active Directory Users and Computers tool , locate the OktaService account. Right-click and reset the password in AD. You will require domain admin,or sufficiently elevated, privileges to perform this action.
- On the server on which the agent is installed, on the Services console:
- Locate the Okta AD agent service and stop it.
- Right-click the service and select the Properties > Log on tab.
- Chance the password to match the one you just set in AD.
- Start the service.
Tip: If you have also installed the Okta IWA SSO agent and used the same Okta Service account that was used to install the Okta AD agent, then you must also change the Okta Service account password in the IIS Server Manager dashboard > Tools > Internet Information Services (IIS) Manager. The OktaIWA service is installed under the Application Pools menu. Under Advanced Settings you can change the Okta Service password to match the new password. Due to caching, the IWA service may not stop immediately. When the cache does reset, IWA will stop working if the OktaService password has not been updated here to match the password you reset in the Active Directory Users and Computers tool and the Services console.
How do I change the Okta admin account password?
There are two options for resetting an Okta admin account password:
- Sign in using that Admin user ID and password. Navigate to the end user account Settings > Change Password section.
- While signed in as a Super admin, navigate to Admin > Directory > People > (admin account name) > Reset Password. Then select whether to send a Reset Password Link or set a Temporary password.
Do I have to open my firewall for the agent?
The Okta AD agent is outbound only. You do not have to pen your firewall for any inbound agent traffic.
Can I control which agents receive traffic?
No. All active agents will receive traffic. The only way to control whether an agent receives traffic or not is to turn an agent off. It is not possible to tailor agent traffic so that it only goes to a backup data center in the event of a failure.
Can I schedule when imports occur?
You cannot schedule a specific time of day for imports. You can schedule the frequency of imports. To schedule import frequency, navigate to Directory > Directory Integrations and select the AD integration. On the Settings tab, scroll to Import and Provisioning and the Schedule Import option to select the import interval. To perform a manual import, select the Import tab and click Import Now.
Is there a way to automate the agent install?
Currently there is no means for automating the agent installation.
How do I turn on more verbose debugging for the agent?
Logs can be an invaluable resource when troubleshooting an issue, and Okta Support will often request them while working on a case. You can enable verbose logging for troubleshooting purposes.
On the system running the affected AD Agent, navigate to the AD Agent install directory. By default, this is C:\Program Files (x86)\Okta\Okta AD Agent.
Open the OktaAgentService.exe.config file with a text editor.
Change the value:
<add key="VerboseLogging" value="False" />
<add key="VerboseLogging" value="True" />
Save your changes to the file
Restart the AD Agent Service
Note: we strongly recommend disabling verbose logging when finished troubleshooting, as it can very quickly generate several large files.
What level of performance tuning can I do on the agent?
You can configure the number of threads the AD agent uses to poll the server for tasks. If you are running the AD agent on a large-scale server, you can increase the thread count as an alternative to using multiple AD agents.
For example, to create three instances, do the following:
- Before opening or modifying the AD agent configuration files, stop the AD agent service under Windows Services.
- From the terminal, locate the OktaAgentService.exe.instances.config file for each AD agent server:
C:\Program Files (x86)\Okta\Okta AD Agent\OktaAgentService.exe.config
Open the 'OktaAgentService.exe.config' file in a suitable text editor program and then locate the following line:
<add key="PollingThreads" value="2" />
The default value is 2 and the valid range is 1 - 10. As an example to increase the number of polling threads to four, edit the line to look like this:
<add key="PollingThreads" value="4" />
- Save the file.
- Start the agent.
Once the change has been made, save the file and then start the Okta AD agent service again. You can verify that the setting has changed by opening the agent.log file at startup and observing the startup information towards the bottom of the file:
2017/07/21 06:06:22.167 Debug – TEST-SERVER-1(4) – PollingThreads: 4
Now the agent has four concurrent polling threads searching for actions to perform.