Two-Way SSL

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).

IBM webMethods 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:

• An SSL connection is established and information is exchanged between the client and the server.

  or

• The next phase of the authentication process occurs, and the server requests the SSL credentials of the client. If the server verifies those credentials, that is, the client’s identity, an SSL connection is established and information exchange takes place.

High-level tasks for configuring SSL

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

Two-Way SSL Security modes

IBM webMethods 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

IBM webMethods 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 Flow service 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.

1. From the IBM webMethods Integration navigation bar, click on the profile icon located at the top-right corner of the IBM webMethods 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 IBM webMethods Integration to generate a private key and a new IBM webMethods Integration signed client certificate. IBM webMethods 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.

Example

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

High-level Steps

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

Before you begin

You must have permissions for your role to create and run a Flow service in the project.

Basic Flow

1. Log in to IBM webMethods Integration and create a Flow service.

2. On the Flow service card, click the ellipsis icon, select Overview, and on the Overview page, select the Enable Flow service to be invoked over HTTP option.

   

3. From the IBM webMethods 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 any REST client and configure the certificate generated from the tenant.

6. Go to IBM webMethods Integration and for the Flow service, 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 IBM webMethods Integration, note the request details (Sample JSON input and the mandatory Content-Type parameter).

   

8. In the REST Client, 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 of the REST Client, add the required headers noted from the Advanced details section of the Flow service. For example, specify Content-Type as the Key and application/json as the Value.

10. On the Body page of the REST Client, add the body for the Flow service noted from the Advanced details section. For example, specify the sample JSON input.

11. Run the Flow service endpoint.