Custom assertions
webMethods API Gateway uses WS-Security (WSS) to provide message-level security and protection for SOAP message requests from a client to an API, and SOAP message responses from an API to a client. By default, webMethods API Gateway supports the WSS policies like Username, X.509 certificate, Security Assertion Markup Language (SAML), Kerberos, Encryption, for the request or response SOAP messages, or both.
webMethods API Gateway also provides an extension to define and use custom policy assertions. Custom assertions allow the API providers to extend and provide more security policies that are not available by default in webMethods API Gateway.
In WS-Security, custom assertions are used for expressing individual security requirements, constraints, or both. The individual policy assertions can be combined to create security policies that can ensure reliable exchanges of SOAP messages between a client and a SOAP API.
webMethods API Gateway supports the following assertion types for enforcing a custom security policy.
Binding assertions
These assertions specify the security mechanism that is to be used by the client or API such as the keys being used, algorithms. Common properties used by other assertions are also defined in the security binding assertion.
webMethods API Gateway supports the WS-SecurityPolicy binding assertions:
| Binding Assertion | Description |
|---|---|
| Transport Binding | This assertion is used when the message is protected at the transport level.
In this binding, messages are exchanged through a defined medium, for example, HTTPS. Note: By
default, webMethods API Gateway uses the transport binding
for Kerberos authentication.
|
| Asymmetric Binding | This assertion is used when both the initiator and the recipient possess
security tokens. In this binding, the initiator uses its private key to sign and the recipient's
public key to encrypt. Recipient uses its private key to decrypt and initiator's public key to
verify the signature. Note: By default, webMethods API Gateway uses the asymmetric binding for the
security policies.
|
| Symmetric Binding | This assertion is used when the initiator or recipient has a security token. In this binding, both the signing and encrypting of messages is done by using a single security token. |
Token assertions
These assertions specify the types of tokens to be used to authenticate and secure SOAP messages.
webMethods API Gateway supports the WS-SecurityPolicy token assertions:
| Token Assertion | Description |
|---|---|
| Username Token | When using this assertion, the message-level security is implemented by using a WSS username token. The assertion authenticates a client by using the username and password in the SOAP request. If validation of the username token succeeds, then webMethods API Gateway passes the message to the API. If validation fails, then webMethods API Gateway returns a SOAP fault. |
| X509 Token | When using this assertion, the message-level security is implemented by using an X.509v3 certificate. The assertion authenticates a client by using the X.509v3 certificate in the SOAP request. If validation of the X.509v3 certificate succeeds, then webMethods API Gateway passes the message to the API. If validation fails, then webMethods API Gateway returns a SOAP fault. |
| Kerberos Token | When using this assertion, the message-level security is implemented by using a Kerberos token. The assertion authenticates a client by using the Kerberos token in the SOAP request. If validation of the Kerberos token succeeds, then webMethods API Gateway passes the message to the API. If validation fails, then webMethods API Gateway returns a SOAP fault. |
| SAML Token | When using this assertion, the message-level security is implemented by using
a SAML (Security Assertions Markup Language\ token. SAML is a standard data format for exchanging
authentication and authorization data between the client and the SOAP API. If validation of the SAML
token succeeds, then webMethods API Gateway passes the message to the API. If validation fails, then API
Gateway returns a SOAP fault. Note: webMethods API Gateway supports both the SAML 1.1 and 2.0 standards.
|
Policy assertions
webMethods API Gateway allows you to even define a complete custom policy assertion. For example, a policy assertion might specify a symmetric binding and the security token types that are used to digitally sign or encrypt SOAP messages between the client and API.