Add opt-out controls to bypass strict X.509 verification introduced in Python 3.13 or disable SSL verification at all

[amarrero]

User description

Description

Summary

This PR introduces flexible SSL verification controls for both Port API calls and third‑party integrations. It adds opt‑out switches that let you bypass the new strict verification (VERIFY_X509_STRICT) when needed, and optionally disable SSL verification entirely (not recommended).

What changed

• Added an SSL configuration helper that can build custom SSL contexts to:
  • Disable only the strict X.509 path checks added in Python 3.13+
  • Or disable SSL verification entirely
• Applied these settings in:
  • Port API HTTP client initialization
  • Shared third‑party HTTP client initialization (used by integrations)
• Added documentation describing the configuration and usage

Environment variables

Port API connections

• PORT_OCEAN_NO_STRICT_VERIFY=true
  • Bypasses the strict X.509 verification introduced in Python 3.13+
• PORT_OCEAN_VERIFY_SSL=false
  • Disables SSL verification entirely (not recommended)

Third‑party integration connections

• PORT_OCEAN_THIRD_PARTY_NO_STRICT_VERIFY=true
  • Bypasses strict X.509 verification for third‑party requests
• PORT_OCEAN_THIRD_PARTY_VERIFY_SSL=false
  • Disables SSL verification entirely for third‑party requests (not recommended)

Notes

• Default behavior remains unchanged; all verification stays enabled unless these env vars are explicitly set.
• Custom CA configuration still relies on HTTPX/OpenSSL standard envs: SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE (no changes here).
• These toggles are intended for environments with private PKI/self‑signed chains that fail due to Python 3.13’s stricter checks.

Security considerations

• Prefer *_NO_STRICT_VERIFY=true over disabling verification entirely.
• Avoid *_VERIFY_SSL=false in production; it disables hostname and certificate validation and increases MITM risk.

Docs

• Added/updated guidance under framework docs: SSL configuration and advanced configuration for per‑client settings and examples.

Examples

• Bypass strict chain checks only (Python 3.13+):
  • Port API: export PORT_OCEAN_NO_STRICT_VERIFY=true
  • Third‑party: export PORT_OCEAN_THIRD_PARTY_NO_STRICT_VERIFY=true
• Disable all SSL verification (not recommended):
  • Port API: export PORT_OCEAN_VERIFY_SSL=false
  • Third‑party: export PORT_OCEAN_THIRD_PARTY_VERIFY_SSL=false

Reasoning

Many enterprises use internal CAs or self‑signed chains. Python 3.13’s VERIFY_X509_STRICT can break previously working chains. These switches provide a controlled, explicit opt‑out while maintaining secure defaults.

Type of change

Please leave one option from the following and delete the rest:

• [ ] New feature (non-breaking change which adds functionality)

All tests should be run against the port production environment(using a testing org).

Core testing checklist

• [ ] Integration able to create all default resources from scratch
• [ ] Resync finishes successfully
• [ ] Resync able to create entities
• [ ] Resync able to update entities
• [ ] Resync able to detect and delete entities
• [ ] Scheduled resync able to abort existing resync and start a new one
• [ ] Tested with at least 2 integrations from scratch
• [ ] Tested with Kafka and Polling event listeners
• [ ] Tested deletion of entities that don't pass the selector

---

PR Type

Enhancement

---

Description

• Add SSL context configuration helper supporting Python 3.13+ strict verification bypass

• Implement separate SSL controls for Port API and third-party integrations

• Apply SSL settings to both Port and third-party HTTP clients

• Document SSL configuration with environment variables and security guidance

---

Diagram Walkthrough

flowchart LR
  A["Environment Variables"] -->|"OCEAN__VERIFY_SSL<br/>OCEAN__NO_STRICT_VERIFY_SSL"| B["get_ssl_context<br/>SSLClientType.PORT"]
  A -->|"OCEAN__THIRD_PARTY_VERIFY_SSL<br/>OCEAN__THIRD_PARTY_NO_STRICT_VERIFY_SSL"| C["get_ssl_context<br/>SSLClientType.THIRD_PARTY"]
  B -->|"ssl.SSLContext or bool"| D["Port API Client"]
  C -->|"ssl.SSLContext or bool"| E["Third-Party Client"]
  D --> F["HTTP Requests"]
  E --> F

File Walkthrough

	Relevant files
Enhancement	ssl.py New SSL configuration helper module                                            port_ocean/helpers/ssl.py New module providing SSL context configuration helper function Supports two client types: PORT and THIRD_PARTY with separate environment variable prefixes Implements logic to disable strict X.509 verification or disable SSL entirely based on env vars Returns ssl.SSLContext with VERIFY_X509_STRICT flag removed or False for disabled verification Includes logging warnings for non-default SSL configurations +54/-0    utils.py Apply SSL context to Port API client                                          port_ocean/clients/port/utils.py Import new SSL helper functions and SSLClientType enum Call get_ssl_context with SSLClientType.PORT in _get_http_client_context function Pass returned ssl_context to OceanAsyncClient verify parameter +4/-1      async_http.py Apply SSL context to third-party client                                    port_ocean/utils/async_http.py Import new SSL helper functions and SSLClientType enum Call get_ssl_context with SSLClientType.THIRD_PARTY in _get_http_client_context function Pass returned ssl_context to OceanAsyncClient verify parameter +3/-0
Documentation	advanced-configuration.md Document SSL verification configuration and best practices docs/framework-guides/docs/framework/advanced-configuration.md Add comprehensive SSL certificate validation section with environment variable documentation Document separate configuration for Port API and third-party connections Provide usage examples for disabling strict verification and SSL verification Include security considerations and troubleshooting guidance Explain Python 3.13+ strict X.509 verification context +80/-0

---