Part of the Okta-AD Integration guide
Okta sends this email when an Okta Active Directory (AD) agent stops checking in with an Okta org. This article explains what the notification means, how urgent it is, and the most common reasons an agent disconnects. Each cause links to Okta's steps for fixing it.
What the "agent has stopped connecting" email means
The Okta AD agent is a Windows service that runs on a server in your client's domain. It connects on-premises AD to Okta and handles AD imports, provisioning, and delegated authentication (users signing in to Okta with their AD password). The agent keeps checking in with Okta over port 443 to pick up work and report its status. If Okta can't reach the agent for more than 120 seconds, Okta marks it as disconnected and emails the org's admins.
The email names the AD domain and server, says when the agent last connected, and says how many agents are still connected. For example:
The Okta Active Directory agent for domain [domain].local, running on machine [SERVER-NAME] has stopped connecting. … There is one connected agent remaining.
How urgent is an Okta AD agent disconnect?
How urgent it is depends on whether another agent for the same domain is still connected.
At least one agent is still connected: Imports and delegated authentication keep working, so users aren't affected. However, the org has lost its backup agent. Restore the disconnected agent as soon as you can.
No agents are connected: Users who sign in with delegated AD authentication can't sign in to Okta, and AD imports stop until at least one agent reconnects. Treat this as an outage.
If the email says no connected agents remain, start the checks below right away.
First checks for a disconnected Okta AD agent
These checks match the ones in Okta's email:
Confirm the agent server is powered on and can reach your Okta org URL (for example,
https://yourorg.okta.com) over HTTPS.On the agent server, open Services (
services.msc) and confirm the Okta AD Agent service is running. If it's stopped, start it and note any error.Log into the Okta Admin Console with Okta Super Administrator privileges. Go to Directory > Directory Integrations, select the AD instance, and open the Agents tab to see the agent's status and version. The email includes a direct link to this page.
If the agent still doesn't reconnect, check the agent logs on the server at
C:\Program Files (x86)\Okta\Okta AD Agent\logs. The errors there usually point to one of the causes below.
Common causes of Okta AD agent connectivity loss
Most disconnects come from one of four causes.
Server reboots and Windows updates
Occasional, short disconnects that leave no errors in the agent logs usually mean the server restarted, often because of a Windows update. To confirm, open Event Viewer on the server, go to Windows Logs > System, and look for Event ID 1074 from User32. This event records the most recent restart.
If the server didn't restart, check its CPU and memory use. Also check whether the network card goes to sleep during quiet periods, because either can cause the agent to drop.
Okta resolution steps: Okta AD Agent infrequently disconnects from Okta and Okta AD Agent disconnects with "Error Retrieving Next Action" timeout
Clock skew on the agent server
AD agent version 3.18.0 and later use OAuth 2.0 to authenticate to Okta, and that only works if the server's clock matches standard time. If the clock is off by more than about 30 seconds, Okta rejects the agent's connection attempts.
To fix it, sync the server to an NTP time source, then restart the Okta AD Agent service. To confirm that the clock is the problem, search the Okta System Log for AD agent events with reasons such as token_timestamp_invalid.
Okta resolution steps: AD Agent connection issues for version 3.18.0 and above
Account and permission problems (401 and 403 errors)
Two different accounts can stop the agent from working, and they fail in different ways.
The Windows service account: The Okta AD Agent service runs as an AD account. If that account's password changes or the account is deactivated, the service can't run. After a password change, enter the new password on the service's Log On tab on every agent server in the org.
The Okta admin account used to install the agent (versions 3.17 and earlier): Older agents connect to Okta through the admin account that installed them. If that account is deactivated, the agent logs show 401 Unauthorized. If it loses the Super Administrator role, the logs show 403 Forbidden. Restoring the role reconnects the agent, but if the account was deactivated you'll need to reinstall the agent. Versions 3.18.0 and later don't depend on this account, so upgrading prevents this problem.
A 401 Unauthorized error can also appear after the agent server is restored from an earlier snapshot. Okta invalidates the agent's token for security reasons, so you'll need to reinstall the agent.
Okta resolution steps: AD Agent version 3.17 and earlier shows disconnected while running, How to update the password for the Okta AD Agent service, and AD Agent fails to reconnect after server restore
Network and firewall blocks
The agent needs two network paths to work:
Agent to Okta: outbound HTTPS on TCP 443. The agent starts this connection, so you only need to allow outbound traffic. If a proxy server or next-generation firewall is in the path, exclude your Okta domain (
*.okta.com) from SSL decryption and inspection.Agent to domain controllers: DNS, Kerberos, LDAP, SMB, and RPC ports, including dynamic RPC ports TCP 49152–65535. Port 464 (Kerberos change/set password) is used for password operations. If it's blocked, the agent can stay connected while provisioning and password resets fail.
If the agent connects through a proxy that requires authentication, enter the new service account password in the agent's proxy settings as well. Otherwise the agent can disconnect on and off with 407 ProxyAuthenticationRequired errors.
Okta resolution steps: Okta AD and LDAP agent communication requirements and Configure DMZ server ports for Active Directory integrations
If the Okta AD agent was shut down on purpose
If you retired the server or moved the agent to a new machine, deactivate and delete the old agent in the Agents tab so Okta stops reporting it as disconnected. See Uninstall Okta Active Directory agent.
Still having trouble? Partners can email ZeroTek Support ([email protected]) and our team will be happy to help.