Okta SCIM Provisioning Connection Fails With "Received fatal alert: protocol_version" Error

When testing a System for Cross-domain Identity Management (SCIM) provisioning connection, Okta generates a fatal alert error. This issue occurs due to a Transport Layer Security (TLS) protocol mismatch between the SCIM client and the SCIM server, or due to issues with the underlying infrastructure. Resolving this requires identifying the component enforcing outdated TLS protocols and updating the configuration to support TLS 1.2.

When this failure occurs, Okta generates the following error:

Received fatal alert: protocol_version

• Okta Identity Engine (OIE)
• Okta Classic Engine
• System for Cross-domain Identity Management (SCIM) Provisioning
• Transport Layer Security (TLS) Configuration

This error indicates a TLS handshake failure. Okta requires TLS 1.2. The failure occurs when the target SCIM server, an intermediary device, or a local SCIM client negotiates an older, unsupported protocol. The potential causes depend on where the component is hosted:

SCIM Server (Target Application and Hosting Environment)

• The SCIM endpoint only supports TLS 1.0 or 1.1.
• Web server configuration disables TLS 1.2 (Tomcat, Nginx, Apache, IIS).
• Java Virtual Machine (JVM) defaults to TLS 1.0 or 1.1 (Java 7 or early Java 8).
• Java security configuration overrides defaults (jdk.tls.client.protocols, jdk.tls.disabledAlgorithms in java.security).
• .NET Framework versions prior to 4.7 do not enable TLS 1.2 by default.
• OpenSSL versions fall below 1.0.1 (Node, Python, Ruby on older base images).
• Operating System (OS) level TLS settings lack modern protocol activation (Windows SCHANNEL registry, Linux crypto policies).
• Cipher suite mismatch or Federal Information Processing Standards (FIPS) mode surfaces as a protocol version alert.

Intermediary Network Devices

• A load balancer, reverse proxy, Web Application Firewall (WAF), or API gateway terminates TLS with outdated protocols.
• An outbound proxy or TLS inspection appliance downgrades protocols.

SCIM Client (Custom Clients or On-Premises Provisioning Agents)

NOTE: Okta cloud infrastructure strictly enforces TLS 1.2. Client-side causes only apply to custom inbound SCIM clients or local provisioning agents.

• An HTTP client library hardcodes an older TLS version (custom Apache HttpClient, OkHttp, explicit SSLContext.getInstance("TLSv1")).
• Mutual TLS misconfiguration causes certificate negotiation failure during the handshake.

How is the "Received fatal alert: protocol_version" error resolved?

Identify the component causing the TLS downgrade based on its hosting location and update the configuration to support TLS 1.2 by following these steps:

1. Verify the SCIM endpoint supports TLS 1.2 using a third-party TLS checker or OpenSSL.
2. Inspect the SCIM server web server (Tomcat, Nginx, Apache, IIS) and ensure the configuration files enable TLS 1.2.
3. Review the SCIM server application runtime environment to ensure the JVM, .NET framework, or OpenSSL versions support and default to TLS 1.2.
4. Examine OS-level TLS settings on the SCIM server, such as the Windows SCHANNEL registry or Linux crypto policies, to ensure the settings activate modern TLS protocols.
5. Check intermediary devices, such as load balancers, reverse proxies, WAFs, or API gateways, to confirm they do not terminate the connection with outdated TLS protocols.
6. Review network appliances, such as outbound proxies or TLS inspection tools, to ensure they do not downgrade the connection.
7. Update any custom SCIM client or On-Premises Provisioning agent HTTP libraries to remove hardcoded legacy TLS versions.
8. Retest the SCIM provisioning connection in the Okta Admin Console.