Software AG Products 10.5 | Using API Gateway | API Gateway Administration | Security Configuration | Custom Assertions
 
Custom Assertions
 
Creating a Custom Assertion
Viewing Custom Assertion List and Assertion Configuration
Modifying Custom Assertion
Deleting Custom Assertion
Example: Custom Assertions
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, API Gateway supports the WSS policies like Username, X.509 certificate, Security Assertion Markup Language (SAML), Kerberos, Encryption, and so on, for the request or response SOAP messages, or both.
API Gateway also provides an extension to define and use custom policy assertions. Custom assertions allow the API providers to extend and provide additional security policies that are not available by default in 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 ensure secure and reliable exchanges of SOAP messages between a client and a SOAP API.
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, and so on. Common properties used by other assertions are also defined in the security binding assertion.
API Gateway supports the following 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 only through a defined medium, for example, HTTPS.
Note:
By default, 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, initiator uses it's private key to sign and the recipient's public key to encrypt. Recipient uses it's private key to decrypt and initiator's public key to verify the signature.
Note:
By default, API Gateway uses the asymmetric binding for the security policies.
Symmetric Binding
This assertion is used when only the initiator or recipient has a security token. In this binding, both the signing and encrypting of messages is done using a single security token.
Token Assertions
These assertions specify the types of tokens to be used to authenticate and secure SOAP messages.
API Gateway supports the following WS-SecurityPolicy token assertions:
Token Assertion
Description
Username Token
When using this assertion, the message-level security is implemented using a WSS username token. The assertion authenticates a client using the username and password in the SOAP request. If validation of the username token succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
X509 Token
When using this assertion, the message-level security is implemented using an X.509v3 certificate. The assertion authenticates a client using the X.509v3 certificate in the SOAP request. If validation of the X.509v3 certificate succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
Kerberos Token
When using this assertion, the message-level security is implemented using a Kerberos token. The assertion authenticates a client using the Kerberos token in the SOAP request. If validation of the Kerberos token succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
SAML Token
When using this assertion, the message-level security is implemented 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 API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
Note:
API Gateway supports both the SAML 1.1 and 2.0 standards.
Policy Assertions
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.