Two-Way SSL

webMethods.io Integration supports Two-Way SSL for inbound connections. You can store client certificates, associate a certificate with a user account, and also set the Two-Way SSL security mode while configuring an SSL connection.

Overview

Secure Sockets Layer (SSL) is a means of securing communications over a network so that only the sender and receiver have access to the sensitive data.

One-way SSL Connection

In a one-way SSL connection, an anonymous client authenticates the credentials of a server in preparation for setting up a secure transaction, that is, the client only verifies the certificate of the server. In most cases, the server knows nothing about the client’s identity because verification of its credentials is not required. When desired, the client can be authenticated using basic authentication by providing a username and password.
This type of authentication typifies connections where a browser establishes a connection to a server to perform a secure transaction, for example, viewing a savings account or buying items with a credit card. The client must authenticate the server’s credentials before initiating the transaction, but it is not necessary for the server to authenticate and keep a record of every possible client (browser). This type of connection is typically one where a partner application or resource needs to verify the authenticity of the server without itself needing to be authenticated.

Two-Way SSL Connection

Two-Way SSL authentication or client authentication refers to two parties authenticating each other by verifying the provided digital certificate so that both parties are assured of the others’ identity. It refers to a client (web browser or client application) authenticating itself to a server and the server also authenticating itself to the client by verifying the public key certificate or digital certificate issued by Certificate Authorities (CAs).

webMethods.io Integration supports Two-Way SSL for inbound connections. The request for an SSL connection originates from a client. During the SSL handshake process, the entity acting as the SSL server responds to the request for a connection by presenting its SSL credentials (an X.509 certificate) to the requesting client. If those credentials are authenticated by the client, then either:

Note: When a client or partner application submits a request to webMethods.io Integration using HTTPS on port 8443, and a Two-Way SSL connection is established, the client acts as the SSL client and webMethods.io Integration acts as the SSL server.

High-level tasks for configuring SSL

The following table provides the high-level tasks for configuring SSL.

Task Activities Notes
Create keys and certificates. - Generate a public key/private key pair.
- Generate a certificate signing request (CSR) and send it to the certificate authority (CA) for signing.
- Receive CA signed client certificate from the CA.
Two-Way SSL connection requires a valid client certificate.
Upload client certificate or generate a certificate. Upload the CA signed client certificate for the user in webMethods.io Integration, Profile icon > Settings > Client Certificate > User Certificate page or generate a private key and a new webMethods.io Integration signed client certificate. Required for Two-Way SSL connections.
Connect to webMethods.io Integration using the client certificate. Configure the REST client with the private key and certificate. Optionally, you can also pass the basic authentication credentials. webMethods.io Integration supports Two-Way SSL on port 8443.

Two-Way SSL Security modes

webMethods.io Integration allows you to set the following Two-Way SSL security modes while configuring an SSL connection:

Default

Allow one-way and Two-Way SSL API execution calls. Use either credentials or certificate.
In the default 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 verified but not validated against the user or tenant certificate. If you provide only the certificate, the certificate is verified and validated against the user certificate.

Force

Allow one-way and Two-Way SSL API execution calls. 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. 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.

Adding client certificates

webMethods.io Integration allows you to store the client certificates and associates a certificate with a user account. You can add client certificates for users on the Client Certificate page. When a user runs a FlowService through the HTTP interface, or a REST API, or a SOAP API, the user authentication happens with the certificate.

A tenant certificate enables you to configure your organization-level certificate so that incoming traffic for execution can be authenticated against the tenant certificate. If a tenant certificate is configured along with a user certificate, then the user certificate validation takes precedence. Tenant level certificates can be generated only by administrators and using the tenant certificate, you can run integrations for all users in that tenant.

Note: An administrator can generate or replace certificates for all users. Normal users can generate only their own certificates.

  1. From the webMethods.io Integration navigation bar, click on the profile icon located at the top-right corner of the webMethods.io Integration home screen and select Settings > Client Certificate > User Certificate.

  2. In the Select User field, select a user. Only active users are listed in the Select User field.

  3. In the Select Certificate field, if you want to upload a new certificate, select Upload New Certificate and click Browse File to upload a new client certificate signed by a trusted certificate authority (CA). If a valid certificate is configured for a user, the Certificate Details panel displays the configured certificate. You can click Download to download the user certificate or click Delete to delete the user certificate. The downloaded file is named as username.crt.
    In the Select Certificate field, you can also select Generate Private Key and Certificate and click Generate if you want webMethods.io Integration to generate a private key and a new webMethods.io Integration signed client certificate. webMethods.io Integration validates it against the issuer of the certificate. The generated certificate is named as username.fileformat. The file format is based on the certificate format (.txt, .jks, .pkcs12, or .pfx) selected while generating the certificate. The certificate contains the private key and the client certificate.

    Note: The default password for the generated certificate is changeit. It is recommended to change the password.

Example

Let us see how to run a FlowService using Two-Way SSL, with the Two-Way SSL security mode as Force.

High-level Steps

  1. Create a FlowService in webMethods.io Integration.
  2. Expose the FlowService over HTTP, which allows you to run the FlowService from an outside environment.
  3. Select the Two-Way SSL security mode as Force in the webMethods.io Integration Client Certificate > Configuration page.
  4. Run the FlowService using Two-Way SSL authentication by using a REST client (Postman).

Note: You can also use the same technique for SOAP APIs, REST APIs, or any other exposed APIs.

Before you begin

You must have the execute permission for your role to create and execute a FlowService in the project.

Basic Flow

  1. Log in to webMethods.io Integration and create a FlowService.
  2. On the FlowService card, click the ellipsis icon, select Overview, and on the Overview page, select the Enable FlowService to be invoked over HTTP option.

  3. From the webMethods.io Integration main navigation bar, click the profile icon > Settings > Client Certificate > Configuration.
    Select Force as the Two-Way SSL Security mode and click Apply.

  4. Go to the Client Certificate > User Certificate page. In the Select User field, select the user. In the Select Certificate field, select Generate Private Key and Certificate. Click Generate and select the format to generate the certificate. The generated certificate is named as username.fileformat.

  5. Open the Postman REST client, click Settings > Certificates, and click Add Certificate.

  6. Go to webMethods.io Integration and for the FlowService, select Overview > Advanced details.
    Copy the synchronous URL and specify it in the Host field (mydomain.webmethods.io:8443/integration/rest/external/integration/run/development/fl0f52fe1a7f628a7670f576/BasicFlowService_ForAPI).
    Specify the port number as 8443.
    Select the generated certificate and provide the certificate passphrase. The default passphrase is changeit.
    Click Add.

  7. From the Overview > Advanced details page in webMethods.io Integration, note the request details (Sample JSON input and the mandatory Content-Type parameter).

  8. In Postman, specify the request URL, add the port as 8443, and select the Authorization type as No Auth.

    Note: If you select the Authorization type as Basic Auth, you need to also provide the username and password.

  9. On the Headers page, add the required headers noted from the Advanced details section of the FlowService. For example, specify Content-Type as the Key and application/json as the Value.

  10. On the Body page, add the body for the FlowService noted from the Advanced details section. For example, specify the sample JSON input.

  11. Click Send to run the FlowService.