Getting the most out of Okta ThreatInsight


Executive Summary

Okta ThreatInsight is designed to detect and block high-volume credential-based attacks (password spraying, credential stuffing, and similar brute-force attacks) directed at Okta endpoints.

The capability offers a security baseline for all Okta customers, with minimal configuration required. A customer simply selects block mode in the Okta Admin Console to automatically deny requests identified as malicious, or log mode to audit malicious traffic.

While ThreatInsight offers this protection at no cost, Okta customers often choose to use ThreatInsight in combination with other security devices and services, such as Web Application Firewalls (WAFs), bot management services, DDoS mitigation services, or combinations of all of them. This provides for multiple differentiated layers of security: harnessing the collective insights of network security providers, Okta’s ThreatInsight, and alerts generated by the customer’s security team in a SIEM (Security Incident Event Management system).

In this whitepaper, we outline how your Okta org should be configured to accommodate third-party services that process a request before it is forwarded on to Okta.

Ultimately, Okta’s goal is to securely connect everything. This whitepaper aims to help customers with complex use cases continue to benefit from Okta’s baseline capabilities.

Identity-Based Attacks

A variety of threat actors continue to rely on abuse of common or previously-stolen credentials for account takeover or initial access to networks.

In credential stuffing attacks, attackers take lists of usernames and passwords stolen in previous data breaches or phishing campaigns, and use automated tools to test them across various other online services.

In a password spray attack, attackers automate the process of testing weak and common passwords against known usernames.

Several billion stolen credentials1 are freely traded in online forums for attackers to use in these attacks, and the tools to automate attacks are cheap or freely available.

According to the Auth0 State of Secure Identity report2, credential stuffing attacks accounted for an average of 16.5% of authentication requests made in 2020.


About ThreatInsight

ThreatInsight is a baseline security capability available to every Okta customer. It is designed to detect and mitigate large-scale attacks on an Okta org (organization).

ThreatInsight is designed to detect malicious activity prior to authentication.

This evaluation harnesses the network effect of the many millions of authentication requests made to thousands of Okta orgs on any given day. It uses heuristics (static rules) and machine learning to observe and derive intelligence from credential-based attacks detected across Okta’s customer base. Once ThreatInsight is enabled in a customer’s dashboard, requests from infrastructure identified in recent attacks are blocked (when ThreatInsight is selected in block mode) or elevated for further analysis and risk scoring (when ThreatInsight is selected in log mode).

If a sign-in attempt from a malicious IP address is detected and ThreatInsight is configured in block mode, the user is presented with an appropriate HTTP error.

ThreatInsight specifically addresses account enrollment, authentication and recovery flows.

Configuring ThreatInsight

The degree to which ThreatInsight requires configuration depends largely on customer requirements.

If all users of an org authenticate directly to the Okta tenant, administrators can toggle ThreatInsight on with confidence (see Basic Configuration below).

This paper provides additional advice for customers with more complex authentication flows, such as customers who use:

  • Third-party security network providers that intercept access requests between an originating client and Okta, or
  • Externally-hosted resources such as Content Delivery Networks or self-hosted sign-in widgets, or
  • Trusted applications that process authentication requests en route to Okta.

Detailed advice for these scenarios is provided under Advanced Configuration.

Basic Configuration

Customers can enable ThreatInsight by navigating to Security > General and choosing from the following options under Okta ThreatInsight Settings.

Table 1: ThreatInsight options

Table 1: ThreatInsight options
[3] This is the default setting for Okta tenants created after September 2021.


Figure 2: ThreatInsight settings

Figure 2: ThreatInsight Settings

Admins can also choose to exempt certain groups of IP addresses (Network Zones) from ThreatInsight evaluation.

Requests from IP addresses included in a customer-configurable Network Zone marked as an Exempt Zone will not be logged or blocked by ThreatInsight. Admins often mark trusted IP addresses such as the IPs used by office network gateways or Okta agents as Exempt Zones.

Advanced Configuration

There are several scenarios in which proxies positioned between the source of an access request and Okta might not be correctly configured to pass on the originating client IP and user-agent to Okta. This diminishes the value of ThreatInsight to the customer. If ThreatInsight evaluates the reputation of the proxy rather than the originating client, there is a risk that legitimate requests could be blocked, or for IPs with a poor reputation to proceed to authentication. The most common scenario is the use of some kind of HTTP proxy, such as a web application firewall (WAF) or network security device.

6.1 - Configuring a Trusted Proxy

If an organization uses third-party network security services such as web application firewalls or DDoS/bot detection services, Okta admins can configure an Okta org to assess the reputation of the originating client IP of access requests, rather than assessing the reputation of the HTTP proxy server. This assessment uses the Okta concept of a Trusted Proxy.

When an IP address is added as a Trusted Proxy in the Admin Console, Okta will skip that address in any subsequent evaluations of a Dynamic Zone and examine the IP address that immediately preceded it in the IP chain (the IP chain is the IPs of all the HTTP-aware network hops between the originating request and Okta). Where multiple IPs are marked as a Trusted Proxy, ThreatInsight will continue to shift its evaluation to the previous IP in the chain.

Configuring a Trusted Proxy requires admins to:

  • Set the X-Forwarded-For (XFF) header in the proxy device and configure it to include the originating client IP address. The XFF header (see Appendix 10.3) is a standardized method for identifying the originating IP address of a client connecting to a web server through an HTTP proxy.
  • Configure the Okta org to identify the Trust Proxy using the steps below.
Figure 2: HTTP proxies and the X-Forwarded-For

Figure 2: HTTP proxies and the X-Forwarded-For


To assign an IP as a Trusted Proxy4:

  1. In the Admin Console, go to Security > Networks
  2. Select Add Zone > IP Zone
  3. Add a Zone Name, and enter the IPs or IP range under Proxy IPs
  4. Click Save

[4] NB: Proxy IPs can also be added to an existing network zone.

Figure 3: Adding a Proxy IP in the Okta console

Figure 3: Adding a Proxy IP in the Okta console

To troubleshoot the configuration of a trusted proxy, see Appendix items 10.1 (Proxy Reports) and 10.2 (Check your Configuration).

6.1.1 - Understanding Network Zones

When assigning Network Zones in Okta, it is important to consider the difference between how ThreatInsight processes an IP designated as a Trusted Proxy and an IP designated as a Gateway.

Admins typically create a network zone from Gateway IPs for the purpose of configuring access policies. For example, an organization might create different access policies for users requesting access from an office branch network and another for users connecting from the public internet.

Unlike a Trusted Proxy, ThreatInsight ignores the X-Forwarded-For set in requests from Gateway IPs and evaluates only the IP of the network gateway.

There are specific scenarios in which an internal application that sits within the IP range of a Gateway IP accepts traffic from the public internet before it passes the request to Okta. In these scenarios, ThreatInsight requires the network gateway to be set as both a Gateway IP and a Trusted Proxy to evaluate the originating IP.

6.1.2 - Restricting Access to the Origin

Organizations that make use of HTTP proxies and custom domains can also configure the origin (Okta org) to only accept authentication requests that pass through these third-party security services.

Okta Support can help admins restrict direct access to the Okta origin (<org> domain) by allow-listing access to unauthenticated endpoints only from:

  • Trusted IP addresses
  • Trusted Proxies

Assume, for illustrative purposes, that a cloud-hosted WAF is configured to process traffic sent to a custom domain used by an Okta organization. Under this configuration, requests to the origin {org} should ideally pass through okta.{customdomain}.com for evaluation by the WAF. On that basis, access to unauthenticated APIs at the origin {org} should be restricted only to a set of trusted IPs and the IPs associated with the trusted proxy at okta.{customdomain}.com.

Figure 4: Use of custom domains

Figure 4: Use of custom domains

6.2 - Custom Apps that Process Authentication Events

Many customers use the Okta Software Development Kit (SDK) to build custom applications that process authentication requests before they are forwarded to Okta. Okta calls these Trusted Applications.

These apps effectively operate as a middleware layer or “authentication broker” betweena front-end app and the Okta cloud. If misconfigured, the public IP address of the servers hosting the custom application will be evaluated by ThreatInsight instead of the IP address of the client requesting access. With foresight and a little fine-tuning, these apps can also be configured to benefit from ThreatInsight and Risk Engine.

Figure 5: Custom apps and the X-Forwarded-For

Figure 5: Custom apps and the X-Forwarded-For

To benefit from ThreatInsight, application code must dynamically place the originating client IP from the client request in the X-Forwarded-For header (See Figure 5).

Further, to benefit from Okta’s Risk Engine, application code should also include the User-Agent from the originating client request in the API call to Okta.

Exporting and Alerting on ThreatInsight Events

Okta surfaces notable security events, such as the number of users self-reporting suspicious activity and the number of sign-in events from suspicious IPs detected within the last seven days, in the Security Monitoring section of the Admin Dashboard.

Access requests are also recorded in the System Log, which offers an intuitive interface for monitoring Okta-specific events and the ability to save custom searches as reports.

The System Log can also be exported into one of many common SIEM tools for further correlation, analysis, and alerting by security teams.

Some common System Log events security teams alert on are included below.

Table 2: System log events to alert on

Table 2: System log events to alert on


Okta Workflows offers a “no code” solution to automatically act on these events: such as adding users to restricted groups that require step-up authentication. Okta’s Event Hooks can also be used by developers to trigger similar actions in external applications.

Security teams often use Okta’s System Logs and ThreatInsight in combination for proactive threat hunting. For example, analysts can build regular reports on all requests ThreatInsight identified as malicious, and use these to search logs for previous or related activity.

Your Next Line of Defense

In a standard configuration, ThreatInsight is Okta’s first line of defense against credential-based attacks.

The next layer of defense for Okta customers is the Okta Risk Engine, which determines the likelihood of an anomalous sign-in event during the authentication process. The Risk Engine assigns a risk score to each Okta sign-in event using models that observe contextual information (device, network, and factor context) and historical information about the user.

Admins can configure user sign-on policies based on these risk scores. In this respect, ThreatInsight plays a role in feeding context into the risk score in whatever mode it is enabled.


10.1 - Proxy Reports

Okta admins can generate reports that help to troubleshoot the configuration of network proxies. Okta’s Proxy Report helps administrators determine what proxy IP addresses have been used in sign-in requests to an Okta org over the prior 30 days. The report includes both proxies the org trusts (such as networking devices used to inspect requests) or that shouldn’t be trusted (unauthorized use of VPNs or TOR, for example).

  1. In the Admin Console, go to Reports > Proxy Reports > Reports
  2. Select Proxies > Proxy IP Usage
  3. Select Generate Report
Figure 6: Generate a Proxy Report

Figure 6: Generate a Proxy Report

Alternatively, admins can manually observe whether there are multiple entries under the Request.IPChain.IP of access requests in the System Log.

10.2 - Checking your Configuration

Admins can use the System Log to manually check whether a trusted proxy is configured correctly. This requires checking requests that pass through the proxy to determine if the Client.IPaddress matches the last IP or the second-to-last IP in the IP chain.

  • If the Client.IPaddress matches the last IP address in the Request.IPChain.IP, it is likely that a middleware app or networking device intercepted the request and is failing to pass on the originating client IP (through X-Forwarded-For) to Okta.
  • If the Client.IPaddress matches the second-to-last IP address in the Request. IPChain.IP, the service has likely already been configured to pass the correct information to Okta.

Take a look at the example below to illustrate.

Figure 7: In the System Log query captured above

Figure 7: In the System Log query captured above, the Client.IPaddress matches the last IP address in the Request.IPChain.IP (the lowest listed in System Log). The client IP address ( is actually part of Cloudflare’s network, but in this scenario ThreatInsight is evaluating the proxy device, not the client that made the request. We can thus assume the org in question has not properly configured the Cloudflare service as a Trusted Proxy.

10.3 - X-Forwarded For resources

Provided below is a non-exhaustive list of help pages published by HTTP proxy and CDN providers relating to support for the X-Forwarded-For header.

[8] Akamai substitutes the X-Forwarded-For with a different identifier (True-IP), but it can be explicitly configured to use X-Forwarded-For.