Inbound Auth - Message

Edit online

An API Provider can use this policy to enforce authentication on the API. When this policy is configured for an API, API Gateway expects the clients to pass the authentication credentials through the payload message that will be added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as X.509 Certificate, WSS Username, SAML, and Kerberos, in addition to signing and encryption, at the message-level.

Note: Message-level authentication can be used to secure inbound communication of only SOAP APIs.
The table lists the properties that you can specify for this policy:
Property Description
Binding Assertion Specifies the type of binding assertion required for the message transfer between the recipient and the initiator.
Require Encryption. Specifies that a request's XML element, which is represented by an XPath expression or by parts of a SOAP request such as the SOAP body or the SOAP headers, be encrypted.
Encrypted Parts Click + Add encrypted part to add the required properties. This allows you to encrypt parts of a SOAP request such as the SOAP body or the SOAP headers.

Provide the following information:

  • Entire SOAP Body. Specifies encryption of the entire SOAP body.
  • All SOAP Attachments. Specifies encryption of all the SOAP attachments.

In the SOAP Header section, provide the following information:

  • Header Name. Specifies the name for the SOAP header field.
  • Header Namespace. Specifies the namespace of the SOAP header to be encrypted.

You can add more SOAP headers by clicking .

Encrypted Elements Click + Add encrypted element to add the required properties. Select this option to encrypt the entire element, which is represented by an XPath expression.

Provide the following information:

XPath. Specifies the XPath expression in the API request.

In the Namespace section, provide the following information:

  • Namespace Prefix. Specifies the namespace prefix of the element to be encrypted.
  • Namespace URI. Specifies the generated XPath element.

You can add more namespace prefixes and URIs by clicking .

Require Signature. Specifies that a request's XML element, which is represented by an XPath expression or by parts of a SOAP request such as the SOAP body or the SOAP headers, be signed.
Signed Elements Click + Add require signature to add the required properties. Select this option to sign the entire element represented by an XPath expression.

Provide the following information:

XPath. Specifies the XPath expression in the API request.

For the Namespace section, provide the following information:

  • Namespace Prefix. Specifies the namespace prefix of the element to be signed.
  • Namespace URI. Specifies the generated XPath element.

You can add more namespace prefixes and URIs by clicking .

Signed Parts Click + Add signed part to add the required properties. Select this option to sign parts of a SOAP request such as the SOAP body or the SOAP headers.

Provide the following information:

  • Entire SOAP Body. Specifies signing of the entire SOAP body.
  • All SOAP Attachments. Specifies signing of all the SOAP attachments.

For the SOAP Header section, provide the following information:

  • Header Name. Specifies the name for the SOAP header field.
  • Header Namespace. Specifies the Namespace of the SOAP header to be signed.

You can add more namespace prefixes and URIs by clicking .

Validate SAML Audience URIs. Validates the audience restriction in the conditions section of the SAML assertion. It verifies whether any of the valid audience URI within a valid condition element in SAML assertion matches with any of the configured URI. If two conditions are available, then one of the audience URIs in the first condition, and one of the audience URIs in the second condition must match with any of the configured URIs in this policy for the SOAP API.
This property is used in the following scenarios:
  • When the native API is enforced with the SAML policy, and the service provider wants to delegate audience restriction validation to API Gateway.
  • When Require SAML Token assertion is defined for the SOAP API in API Gateway.
URI Specifies the SAML audience URI.
Match Criteria Select one of the following options:
  • Allow Sublevels. Any one of the audience URI in the incoming SAML assertion either has to be an exact match or it can have sub paths to the configured URI. For example, if http://yahoo.com is configured as the URI and the Allow Sublevels option is selected, the audience URI has http://yahoo.com/mygroup and condition is matched because the main URI matches with the configured URI (http://yahoo.com). The extra path mygroup is a sublevel path.
  • Exact match. Any one of the audience URI in the incoming SAML assertion is verified for the exact match with the configured URI. For example, if http://yahoo.com is configured as the URI and the Exact match option is selected, the audience URI must be configured with http://yahoo.com in order to match the condition. This is selected by default.

For more information on audience URI, see conditions and audience restriction sections in the SAML specification available in the https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf location.

Token Assertions Select the type of token assertion required to authenticate the client.

Select any of the following:

  • Require X.509 Certificate. Mandates that there should be a wss x.509 token in the incoming SOAP request.
  • Require WSS Username token. Mandates that there should be a WSS username token in the incoming SOAP request. Uses WS-Security authentication to validate user names and passwords that are transmitted in the SOAP message header for the WSS Username token.
  • Kerberos Token Authentication. Mandates that there should be a Kerberos token in the incoming SOAP request. Authenticates the client based on the Kerberos token. API Gateway extracts the Kerberos token from the SOAP body and validates the token with the KDC using SPN credentials configured by the provider for the API. If the Kerberos token sent by the client is valid, API Gateway forwards the request to the native service and the response to the client.
    • Service Principal Name. Specifies a valid SPN, which is the name type to use while authenticating an incoming client principal name. The specified value is used by the client or the server to obtain a service ticket from the KDC server.
      Note: API Gateway supports the username format for Service Principal Names (SPNs). This format represents the principal name as a named user defined in LDAP used for authentication to the KDC.
    • Service Principal Password. Specifies a valid password of the Service Principal Name user or the Service Principal Name host.
  • Require SAML Token. Mandates that there should be a SAML token in the incoming SOAP request. Uses a Security Assertion Markup Language (SAML) assertion token to validate applications. Provide the following information:
    • SAML Version. Specifies the supported SAML version. Available values are SAML 1.0, SAML 2.0
    • SAML Subject Configuration. Select one of the following:
      • Bearer of Token. Select the bearer method when the client wants a security token to be issued without a proof of possession.
      • Holder of Key - Symmetric. Select the Holder of Key (Symmetric) method when either the client or the server has to generate security tokens such as X509 tokens. A symmetric key is established using the security token. You can use this token to sign and encrypt parts and elements.
      • Holder of Key - Public. Select the Holder of Key (Public) method when both the client and the server have security token such as X509 certificates. In this method, the client uses its private key to sign and the recipient’s (API Gateway) public key to encrypt.
    • WS-Trust Version. Specifies the WS-Trust version to be used. Available values are WS-Trust 1.0, WS-Trust 1.3
    • Encrypt Signature. Select Yes to encrypt the signature.
    • Issuer Address. Specifies the SAML issuer address.
    • Metadata Reference Address. Specifies the address from where the metadata reference document is obtained.
    • Algorithm Suite. Specifies the applicable algorithm suite.
    • Key. Specifies the Key type of the security token template.
    • Value. Specifies a value for the request token.

      You can add more values for the key-value pair by clicking .

  • Custom Token Assertion. Type a search string, select a custom token assertion name to authenticate the client, and click to add. You can add more custom token assertions in a similar way.

    Click the Custom Token Assertion arrow to see a list of all custom token assertions available in API Gateway.

    Click to delete the custom token assertion added.

Require Timestamp Specifies that the time stamps be included in the request header. API Gateway checks the time stamp value against the current time to ensure that the request is not an old message. This serves to protect your system against attempts at message tampering, such as replay attacks.