Outbound SSL settings
Outbound SSL settings control how Boomi API Gateway secures and authenticates outbound calls to backend services. By default, the Gateway validates, or optionally skips validating, the backend's certificate during the TLS handshake. Outbound mutual Transport Layer Security (mTLS) is an optional, stricter mode within these settings: it requires the Gateway to also present its own certificate so the backend can authenticate the Gateway, establishing identity in both directions before exchanging payload data. Organizations enable outbound mTLS specifically when backends require client authentication to satisfy corporate security policies or regulatory standards.
Outbound mTLS operates independently of inbound mTLS configurations. The Gateway can establish mutual authentication on outbound calls regardless of whether inbound connections use standard HTTP or SSL. Enabling outbound mTLS at the Gateway or API level introduces no operational changes to existing APIs until the feature is explicitly activated.
During an outbound mTLS transaction, the Gateway functions as the TLS client and the backend functions as the TLS server. Authentication relies on two primary certificate repositories:
- Keystore: Holds the Gateway's private key and client certificate. The Gateway presents this identity certificate to the backend when requested during the TLS handshake.
- Truststore: Holds trusted root and intermediate CA certificates. The Gateway uses these certificates to verify the identity and authenticity of the backend server certificate.
System administrators can configure certificate validation rules to fit backend security requirements: Trust All and Hostname Verifier control whether and how strictly the Gateway validates the backend's certificate. For the exact behavior and defaults of each setting, refer to the Configuration reference table.
During request execution, the Gateway initiates the TLS handshake and receives the backend server certificate. The Gateway verifies the certificate against its truststore unless Trust All is active. If the backend requests client authentication, the Gateway transmits its certificate from the keystore for backend validation. The connection proceeds only after both endpoints complete validation. While mTLS successfully proves cryptographic identity, backend services can still evaluate authenticated requests against access control rules, potentially rejecting connections based on certificate attributes such as the Subject, Common Name (CN), or Organizational Unit (OU).
For outbound SSL configuration steps, refer to:
Recovering the Gateway truststore
Outbound certificate validation uses its own dedicated store: a separate outbound-truststore.jks for backend certificates the Gateway trusts, and a separate outbound-keystore.jks for the client certificate the Gateway presents to the backend. Client Certificate Authentication uses a separate inbound Gateway truststore that does not share either file, so recovering one does not affect the other. If the outbound truststore is corrupted, not found, or a certificate operation throws an input/output (I/O) exception, the Gateway automatically rebuilds it from the trusted certificates and keystore certificate you configured for that Gateway.
Adding, updating, or removing a trusted certificate or keystore certificate takes effect on the Gateway without a restart. You do not need to redeploy the API or restart the Gateway container for the change to apply.
Errors
| Code | Message |
|---|---|
| 403 | Forbidden. The backend requires a client certificate for the handshake, but you have not enabled Outbound MTLS (or have not set a Keystore Certificate). |
| 502 | Bad Gateway. The backend's certificate failed trust validation (Trust All is off and you have not configured a matching Gateway Trusted Certificate), or Hostname Verifier is on and the backend's certificate hostname does not match the server. |
Configure outbound SSL settings using the GraphQL API
You can also configure Gateway-level and API-level Outbound SSL settings programmatically, using the gatewayUpdate and deployedApiUpdate mutations with a new outboundSslSettings input. For the field list, error codes, and example queries, see the API Gateway APIs documentation on developer.boomi.com.
