HTTP REQUESTS

SSL and TLS Configuration

Configure SSL/TLS settings for secure HTTPS connections, certificate authentication, and proxy configurations in your Karate tests.

Basic SSL Configuration

Enable SSL for HTTPS requests using the configure ssl statement:

Feature: SSL Configuration Examples

Background:
  # Enable SSL for HTTPS requests
  * configure ssl = true
  * url 'https://api.example.com'

Scenario: Basic HTTPS request
  Given path '/secure-endpoint'
  When method get
  Then status 200

The ssl = true setting enables SSL without requiring specific certificates or key stores.

SSL/TLS Version Specification

Force a specific SSL/TLS version by providing the algorithm name:

Feature: TLS Version Control

Background:
  # Force TLS version 1.2
  * configure ssl = 'TLSv1.2'
  * url 'https://api.example.com'

Scenario: TLS 1.2 connection
  Given path '/secure-data'
  When method get
  Then status 200

Supported SSL/TLS algorithms include:

• TLS (default)
• TLSv1.2
• TLSv1.3
• SSLv3 (not recommended)

Refer to the Java SSLContext documentation for the complete list of supported algorithms.

HTTP Proxy Configuration

Configure HTTP proxy settings for environments that require proxy connections:

Basic Proxy Setup

Feature: HTTP Proxy Configuration

Background:
  # Set proxy server URI
  * configure proxy = 'http://proxy.company.com:8080'
  * url 'https://api.example.com'

Scenario: Request through proxy
  Given path '/data'
  When method get
  Then status 200

Proxy with Authentication

Feature: Authenticated Proxy

Background:
  # Proxy with username and password
  * configure proxy = { uri: 'http://proxy.company.com:8080', username: 'john', password: 'secret' }
  * url 'https://api.example.com'

Scenario: Authenticated proxy request
  Given path '/secure-data'
  When method get
  Then status 200

Proxy with Non-Proxy Hosts

Exclude specific hosts from proxy routing:

Feature: Proxy with Exclusions

Background:
  * configure proxy = { uri: 'http://proxy.company.com:8080', nonProxyHosts: ['localhost', '*.internal.com'] }
  * url 'https://api.example.com'

X509 Certificate Authentication

Configure client certificate authentication (mutual TLS) for APIs requiring certificate-based authentication:

PKCS12 Certificate Store

Feature: Client Certificate Authentication

Background:
  # Configure client certificate from PKCS12 file
  * configure ssl = { keyStore: 'classpath:client-cert.p12', keyStorePassword: 'secretpass', keyStoreType: 'pkcs12' }
  * url 'https://secure-api.example.com'

Scenario: Certificate-based authentication
  Given path '/protected-resource'
  When method get
  Then status 200

Complete Certificate Configuration

Feature: Full Certificate Setup

Background:
  * configure ssl =
    """
    {
      keyStore: 'classpath:client-keystore.jks',
      keyStorePassword: 'clientpass',
      keyStoreType: 'jks',
      trustStore: 'classpath:ca-truststore.jks',
      trustStorePassword: 'trustpass',
      trustStoreType: 'jks',
      algorithm: 'TLSv1.2'
    }
    """
  * url 'https://mutual-tls-api.example.com'

Scenario: Full mutual TLS authentication
  Given path '/highly-secure-endpoint'
  When method post
  And request { data: 'sensitive information' }
  Then status 201

Certificate Configuration Parameters

Parameter	Type	Description
keyStore	string	Path to client certificate file (supports classpath: prefix)
keyStorePassword	string	Password for the key store file
keyStoreType	string	Key store format (jks, pkcs12, pem)
trustStore	string	Path to trust store containing CA certificates
trustStorePassword	string	Password for the trust store file
trustStoreType	string	Trust store format (jks, pkcs12, pem)
algorithm	string	SSL/TLS algorithm to use (default: TLS)
trustAll	boolean	Trust all certificates including self-signed (development only)

Trust All Certificates

Warning: Use only in development environments

For testing against services with self-signed certificates or during development:

Feature: Development SSL Settings

Background:
  # Trust all certificates (DEVELOPMENT ONLY)
  * configure ssl = { trustAll: true }
  * url 'https://localhost:8443'

Scenario: Self-signed certificate acceptance
  Given path '/dev-endpoint'
  When method get
  Then status 200

Security Warning: Never use trustAll: true in production environments as it disables certificate validation and makes connections vulnerable to man-in-the-middle attacks.

Global SSL Configuration

Set SSL configuration globally in karate-config.js:

function fn() {
  var config = {};

  if (karate.env == 'dev') {
    // Development: trust all certificates
    karate.configure('ssl', { trustAll: true });
  } else if (karate.env == 'staging') {
    // Staging: specific TLS version
    karate.configure('ssl', 'TLSv1.2');
  } else if (karate.env == 'prod') {
    // Production: client certificate authentication
    karate.configure('ssl', {
      keyStore: 'classpath:prod-client-cert.p12',
      keyStorePassword: karate.properties['cert.password'],
      keyStoreType: 'pkcs12',
    });
  }

  return config;
}

System Properties for SSL

Configure SSL settings using Java system properties:

Certificate Store Properties

# Key store configuration
-Djavax.net.ssl.keyStore=/path/to/client-keystore.jks
-Djavax.net.ssl.keyStorePassword=clientpass
-Djavax.net.ssl.keyStoreType=jks

# Trust store configuration
-Djavax.net.ssl.trustStore=/path/to/ca-truststore.jks
-Djavax.net.ssl.trustStorePassword=trustpass
-Djavax.net.ssl.trustStoreType=jks

HTTP Proxy Properties

# HTTP proxy settings
-Dhttp.proxyHost=proxy.company.com
-Dhttp.proxyPort=8080
-Dhttp.proxyUser=username
-Dhttp.proxyPassword=password

# HTTPS proxy settings
-Dhttps.proxyHost=proxy.company.com
-Dhttps.proxyPort=8080
-Dhttps.proxyUser=username
-Dhttps.proxyPassword=password

# Non-proxy hosts
-Dhttp.nonProxyHosts=localhost|*.internal.com

Environment-Specific SSL Settings

Configure different SSL settings per environment:

Feature: Environment-specific SSL

Background:
  * def sslConfig = karate.env == 'dev' ? { trustAll: true } : 'TLSv1.2'
  * configure ssl = sslConfig
  * url baseUrl

Scenario: Environment-aware SSL configuration
  Given path '/api/data'
  When method get
  Then status 200

SSL Configuration Examples

Corporate Environment

Feature: Corporate SSL Setup

Background:
  # Corporate proxy with authentication
  * configure proxy = { uri: 'http://corporate-proxy:8080', username: '#(proxyUser)', password: '#(proxyPass)' }
  # Corporate CA certificate
  * configure ssl = { trustStore: 'classpath:corporate-ca.jks', trustStorePassword: '#(trustStorePass)' }
  * url 'https://internal-api.company.com'

Microservices with mTLS

Feature: Microservice Authentication

Background:
  # Service-to-service authentication
  * configure ssl =
    """
    {
      keyStore: 'classpath:service-identity.p12',
      keyStorePassword: '#(servicePassword)',
      keyStoreType: 'pkcs12',
      algorithm: 'TLSv1.3'
    }
    """
  * url 'https://secure-microservice.example.com'

Cloud API with Custom Certificates

Feature: Cloud Service Integration

Background:
  # Cloud service with custom CA
  * configure ssl = { trustStore: 'classpath:cloud-service-ca.pem', trustStoreType: 'pem' }
  * url 'https://api.cloud-provider.com'

SSL Troubleshooting

Common SSL Issues

1. Certificate Validation Errors

   • Verify certificate chain in trust store
   • Check certificate expiration dates
   • Ensure hostname matches certificate

2. Proxy Connection Issues

   • Verify proxy URL and credentials
   • Check nonProxyHosts configuration
   • Test direct connection without proxy

3. TLS Version Mismatches

   • Confirm server supports specified TLS version
   • Check Java version compatibility
   • Use TLS for automatic version negotiation

Debug SSL Connections

Enable SSL debug logging:

-Djavax.net.debug=ssl:handshake:verbose

Or in code:

Feature: SSL Debugging

Background:
  * configure ssl = true
  * configure logPrettyRequest = true
  * configure logPrettyResponse = true

Best Practices

1. Use Environment Variables: Store sensitive credentials in environment variables, not in code
2. Certificate Rotation: Plan for certificate expiration and rotation procedures
3. Least Privilege: Use certificates with minimal required permissions
4. Secure Storage: Keep private keys and certificates secure
5. Testing: Test SSL configurations in staging environments before production
6. Documentation: Document certificate requirements and configuration for your team

For more advanced networking configurations, see the FAQ for additional SSL/TLS troubleshooting guidance.