WSS Inbound policies in API Gateway

Knowledge base
,
1

Supported Versions: 9.12 and above

webMethods API Gateway tutorial

Introduction

WS Security has been a popular way of securing SOAP APIs over the past. With the increased demand for securing SOAP APIs it is important for users of API Gateway to have a clear understanding on the usage of the above WS Security policies with API Gateway. This tutorial will give a brief explanation on the various WS Security policies in API Gateway and the different use-cases behind them.

This tutorial will cover the following topics:

  • Require signing.
  • Require encryption.
  • Token Assertions 
    • Require X.509 Certificate
    • Require WSS Username token
    • Require Timestamp

Use cases for WS-Security policy

WS-Security policies are used for the variety of use cases with security. This section will explain the most common use cases with which the WS-Security policies are most commonly used.
 
Confidentiality is securing the messages we transfer by encrypting them and the recipient would decrypt the messages to understand it. Encryption is achieved using a public-private key combination. The encryption process is,

  • Alice encrypts the message by using Bob’s public key.
  • Bob decrypts the message using his private key.

Since the private key is only known to Bob, no one else will be able to decrypt the message sent by Alice.

Integrity ensures that the message from the sender is not changed by an Eaves dropper and/or preventing ourselves against the middle in the man attacks. This is achieved by the sender signing parts of the document using the private key of the sender. If Alice wants to send a message to Bob, then the message is

  • Encrypted using the private key of Alice and sent to Bob.
  • Bob will be able to decrypt using the public key of Alice.

This ensures that the sender of the message is Alice. Signing does not mean that the message itself is not readable by man in the middle. The following diagram shows what involves in the process of Signing.

In order for signing only parts of the document, a digest is generated for the parts of the message that requires signing using a crypto algorithm and then encrypted using the private key of the sender. At the receiving end, the receiver will decrypt the message using the public key of the sender and re-compute the digest for the parts using the same algorithm as mentioned in the request. The integrity of the message and that the message indeed came from the Sender can be confirmed when the recomputed digest is same as the digest in the request.

It depends on the user to choose between Signature and Encryption or both based on his\her use case.

It is often important for the Recipient/Initiator to be able to determine the freshness of the message that they receive. In some cases, it is possible for Replay attacks when the security semantics of either of the parties are known. For this purpose the Server would demand the client to add timestamp information that indicates when this request was generated. Again to ensure Integrity this timestamp should be Signed/Encrypted. This can also be the case with the client for ensuring that it receives only fresh data from the Server. 

Identity can be achieved using WS Security policies helping the server to identify the Client. The Client identification can be through Require WSS-Username tokens and X 509 certificates.

Pre-requisite for WS-Security policies

To enforce the WS-Security policies in webMethods API Gateway, a prerequisite is to configure the keystore and truststore aliases in Integration Server and configure API Gateway to use these aliases for processing the incoming security headers.  The following steps explain the configuration of keystore and truststore in Integration Server and API Gateway.Refer to the Integration Server documentation for keystore and truststore configurations.

To configure certificates in Integration Server and API Gateway, you perform the following high-level steps:

  1. Create a keystore alias in Integration Server
  2. Create a truststore alias in Integration  Server
  3. Import the certificate for the alias in Integration Server
  4. Configure API Gateway to use the keystore and truststore
An API cannot be activated with WS-Security policy until the security configurations are done.The security configurations should be done and the system should be restarted for the changes to take effect.

Create a Keystore and Truststore

Navigate to APIGateway Adminisration→Security → Keystore/Truststore page.

create a new keystore alias using the default keystore that is shipped with the APIGateway installation.

For demonstration purpose, we will call the new keystore alias as “APIGatewayKeystoreAlias” and truststore alias as "APIGatewayTrustAlias"

Note: For APIGateway version 9.12 you have to create the keystore and truststore navigating to the Integration Server Administration page

Import the Certificate for Alias in Integration Server

 It is important to import the certificate for the alias that is selected in the Integration Server. The user should be a valid Integration Server user.

1018×235 12.9 KB

Configure API Gateway to use Keystore and Truststore

Once the keystore and truststore alias are created in the Integration Server, configure API Gateway to use the aliases as described below:

In API Gateway navigate to the Administration screens by clicking the drop-down in the logged in user.

1260×254 22.7 KB

Under Security -> Keystore/Truststore select the alias of the Keystore and Truststore alias that are created in Integration Server.

852×398 15 KB

Inbound Authentication - Message Policy action in API Gateway

The 'Inbound Authentication-Message' policy action helps the API Provider to configure the WS-Security actions under one umbrella.

This policy action is present under the 'Identify and Access' section in the policy catalog. 

This Policy action can be configured,

  • Globally  - Inside a global policy to be used across all the SOAP APIs or some filtered with a condition.
  • API Level  - Inside the API.
  • Scope level - For a particular scope that is defined inside an API.

An API can have once occurrence of this policy action applied to it form the above levels.

The below snapshots show the configuration for the Policy action.

564×578 17.8 KB

For working with WSS Policies in general you need to perform the following high level steps.

  1. Configure the 'Inbound Authentication-Message' policy action either at the Global Policy, API level or the scope level.
  2. Activate the API if inactive. 
  3. The WSDL of the API would contain the Policy action reference.
  4. Configure the client with the respective settings.

The remaining parts of the tutorial will discuss the above steps briefly for each policy.
 

Working with Require WSS-Username token action

Require username token security ensures that API Gateway uses WS-Security authentication to validate user names and passwords that are transmitted in the SOAP message header. API Gateway rejects requests that do not include the username token and password of an Integration Server user. API Gateway only supports clear text passwords with this kind of authentication.

This section gives examples of how you can use the Require Username Token with API Gateway.

To configure and use the WSS Username Token Security Policy in Mediator, you perform the following high-level steps:

Configure the 'Inbound Authentication-Message' policy action 

Require WSS Username token is token assertion. Just select it from the list of token assertions.

344×671 19.5 KB

Changes to the WSDL

The WSDL will have the following section added.

1211×681 72.6 KB

Client Settings

Requests for the above API will be rejected if a WSS username token is not added to it. 

A proper request for the createEmployee operation of our API would be like: