Setting up secure connections with Mutual TLS (mTLS)

Mutual Transport Layer Security (mTLS) is a mechanism for securing network communications by helping ensure that both the sender and the receiver authenticate each other, allowing only trusted parties to exchange sensitive data.

  • In server authentication, the client verifies the server certificate.
  • In client authentication, the server verifies the client certificate.

webMethods Integration supports mTLS for inbound connections. You can store client certificates, associate each certificate with a user account, and configure the mTLS security mode to establish a secure, authenticated connection.

Transport Layer Security (TLS) connection

In a TLS connection, the client authenticates the server’s credentials before a secure session is established. The client verifies the server’s certificate to make sure that it is communicating with a trusted endpoint.

In the TLS model, the server typically does not authenticate the client, so the client remains anonymous from the server’s perspective. If required, client identity can be verified by using mechanisms such as basic authentication (username and password). This type of connection is common in browser-to-server interactions, where a browser connects securely to a server to perform actions such as viewing account information or completing transactions. In such cases, the client verifies the server’s identity, while the server does not need to verify or maintain identity information for every client.

TLS is also commonly used when client applications or external systems need to validate the server’s identity, without requiring client authentication.

mTLS connection

mTLS (mutual TLS), also known as client authentication, uses digital certificates to verify the identity of both the client and the server. In the mTLS model, the client verifies the server’s certificate, and the server also verifies the client’s certificate. This process makes sure that both parties authenticate each other before a secure connection is established. Both identities are validated by using certificates that are issued by trusted certificate authorities (CAs).

webMethods Integration supports mTLS for inbound connections. The request for an mTLS connection originates from a client. During the handshake, the server responds by presenting its mTLS credentials, such as an X.509 certificate, to the client.

If the client successfully verifies the server’s certificate, one of two things happens. A secure connection is established, and data exchange begins, or the authentication process continues, where the server requests the client’s certificate.

If the server successfully validates the client’s certificate, the mTLS connection is established, and secure communication begins.

Note: webMethods Integration supports mTLS connections on HTTPS port 443. When a client application connects to webMethods Integration, the client acts as the TLS client, and webMethods Integration acts as the TLS server.

Verifying mTLS configurations

To verify whether mTLS is configured in the environment, go to Settings > Key/Certificate > Client Certificate or Settings > Key/Certificate > Tenant Certificate. The Secure API Access section displays the configured mTLS settings and related details.

High-level tasks for configuring SSL

The following steps outline the high-level process for configuring mTLS:
  1. Create keys and certificates
    • Generate a public–private key pair.
    • Create a Certificate Signing Request (CSR) and submit it to a certificate authority (CA).
    • Receive a CA-signed client certificate.
    Note: A valid client certificate is required for mTLS connections.
  2. Upload or generate client certificates

    This step is mandatory for enabling mTLS.

    Upload the CA-signed client certificate in webMethods Integration from the User certificate page. A new client certificate signed bywebMethods Integration is created.

    Alternatively, generate a private key and create a client certificate signed by webMethods Integration.

  3. Configure client to use the certificate

    Configure your REST client or application with the client certificate and private key. Optionally, provide more authentication credentials (such as username and password).

  4. Establish mTLS connection

    Connect to webMethods Integration by using HTTPS.

mTLS security modes

In webMethods Integration, you can configure the following Two-Way SSL security modes at the SSL connection level:

Default
The system supports API execution calls over TLS and mTLS. Authentication can be performed using either credentials or a certificate. By default, API execution is allowed regardless of whether mTLS is enabled.

When mTLS is configured, the system behaves as follows:

  • If both credentials and a certificate are provided, the system validates the credentials against the user. The system verifies the certificate but does not match the certificate to the user or to the tenant certificate.
  • If only a certificate is provided, the system verifies the certificate and validates the certificate against the user certificate.
Force
The system supports API execution over TLS and mTLS. A certificate is mandatory for API execution. In the forced mode, API execution is allowed only when a certificate is provided, with or without mTLS.

When mTLS is configured, the system behaves as follows:

  • If both credentials and a certificate are provided, the system validates the credentials against the user. The system also verifies the certificate and validates the certificate against the user or tenant certificate.
  • If only a certificate is provided, the system verifies the certificate and validates the certificate against the user certificate.
Exclusive
The system supports API execution calls over mTLS only. A certificate is mandatory for all API execution requests. When mTLS is configured, the system behaves as follows:
  • If both credentials and a certificate are provided, the system validates the credentials against the user. The system also verifies the certificate and validates the certificate against the user or tenant certificate.
  • If only a certificate is provided, the system verifies the certificate and validates the certificate against the user certificate.

In webMethods Integration, you can configure the following Two-Way SSL security modes at the SSL connection level:

Force

Allow one-way and Two-way SSL API execution calls. The certificate is mandatory. In the force mode, API execution with or without Two-way SSL is allowed. With Two-way SSL, if you provide both credentials and certificate, the credentials are validated against the user, and the certificate is also verified against the user or tenant certificate. If you provide only the certificate, the certificate is verified and validated against the user certificate.

Exclusive

Allow only Two-way SSL API execution calls. The certificate is mandatory. In the exclusive mode, API execution with only Two-way SSL is allowed. With Two-way SSL, if you provide both credentials and certificate, the credentials are validated against the user and the certificate is also verified against the user or tenant certificate. If you provide only the certificate, the certificate is verified and validated against the user certificate.