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