6. Gateway

The DigitMarket™ API Manager gateway is the core component of the DigitMarket™ API Manager platform.

As its core features, the Gateway:

  1. Authorizes users by verifying Subscription keys
  2. Authenticates the calls using industry-standard authentication methods
  3. Accepts API calls on its exposure endpoints and routes them to its service back ends
  4. Transforms the request and response as per user-configurations
  5. Performs schema validation
  6. Enforces usage quotas and rate limits
  7. Enforces request time-outs

6.1. Consuming APIs through the Gateway

Consuming an API exposed via DigitMarket™ API Manager involves submitting authenticated and authorized requests to the Gateway. The following activities must be carried out by Developer users to enable them to consume the exposed APIs through the DigitMarket™ API Manager Gateway.

  • Authorization

    Authorization helps DigitMarket™ API Manager identify whether the authenticated user can be given access to the backend resource under a Usage Plan that the user has subscribed. In DigitMarket™ API Manager, the Gateway carries out authorization based on subscription keys. A Subscription Key is mandatory for paid as well as free consumers who subscribe to access APIs. The Subscription Key needs to accompany the request, and must be included in the HTTP request header. The consumers of APIs need to set the subscription key giving the header name as DMAPIM-Subs-Key, like so:

    Authorization: DMAPIM-Subs-Key <Subscription Key>

    The Subscription Key will be available in the Subscription detail page after the Publisher activates the same from their end. For more details on how to get the Subscription Key, refer View Subscription Details.

    APIs can be consumed via Header Key, Query Parameter and IP White listing.

    IP Whitelisting:

    IP Whitelisting is a way to limit access control only to a list of trusted IPs addresses. Publisher users or Developer users can add the list of IP addresses, or define the IP address range that can be allowed to access the resources at the time of subscription.

    Header key:

    Header key is the key that needs to be passed in the request header to consume an API. Header key consists of a key-value pair. The Header key (or header name) can be defined when selecting the authentication type. The value can be defined by Publisher users or Developer users at the time of subscription.

    Query Parameter:

    Query parameter is the parameter that needs to be passed in the request URL. Query parameter consists of a key-value pair. The Query parameter key (or Query parameter name) can be defined when selecting the authentication type. The value can be defined by Publisher users or Developer users at the time of subscription.

  • Authentication

    Using the Authentication mechanisms, DigitMarket™ API Manager is able to ensure that only users with valid authenticated credentials are allowed access to backend APIs.

    DigitMarket™ API Manager supports the following three types of Authentication:

    1. Basic Authentication

      Basic Authentication uses the ‘Authorization’ HTTP header for carrying out authentication based on user credentials. A request message must contain the user name and password fields in Base64 encoded form in the request header.

      If Basic Authentication is the authentication mechanism:

      • The Authorization header should have content as below:

        Authorization: Basic <Base64 encoded string of 'username:password'>

      • The user name and password must match the value specified under Basic Authentication in the Subscription page. Refer Configure a Subscription > Configuring Credentials for more details.

      The Key Concepts>Gateway> Authentication section has more information on authentication.

    2. WS Security

      WS Security is specific to SOAP APIs. In DigitMarket™ API Manager, WS security uses the user name and password that is passed in the SOAP message under SOAP header tag. These credentials are validated against the credentials configured during subscription, and on successful validation the credentials are replaced with the credentials configured in endpoints during API configuration. The authentication happens in the Gateway before access is allowed to the backend resource.

    3. OAuth Authentication

      OAuth Authentication uses the ‘Authorization’ HTTP header for carrying out the authentication. OAuth-related administrative activities as explained in the topic: ‘Using OAuth in DigitMarket™ API Manager’ under section: Authentication forms the groundwork that allows the Developer user to generate the access token needed to make OAuth authenticated requests. Find more information about OAuth Authentication in the Key Concepts>Gateway> Authentication section.

      For OAuth authentication, an API consumer needs to complete the steps given below:

      • Generate Access token

        The Developer user can generate access token in one of the following ways:

        • From the Developer portal: Visit Generate an Access Token for more information on generating and revoking access tokens from the Developer portal.
        • Generate an access token using the Gateway OAuth API. For details on using Gateway APIs to generate access token, visit: Generate an access token API.

      • Include the generated access token in the HTTP Authorization header of your request:

        Authorization: Bearer <access token>

      DigitMarket™ API Manager allows the Developer user to validate the access token using the Validate an access token API, and if required, revoke an access token using the Revoke an access token API.

  • API reference details

    As a consumer, you need to know the exposure endpoint, API methods to use, the mandatory and other parameters to use in a request, and how to parse responses and handle errors.

    Users need to know the API exposure endpoint, which is the URL that the Consumer apps use to send requests. You can find information related to the exposure endpoint path of an API in the API documentation of the subscribed pack. API documentation is a part of the Subscription details page and API Pack details page in the Developer portal. For more information, see View Subscriptions and filter Subscriptions view and View API Pack Documentation.

    All other information related to making a request, such as required parameters, error codes and messages, could be found in the API documentation provided by the publisher. The API Documentation link is available from the API Packs details page and Subscription details page in the Developer portal. Refer the section: View API Pack Documentation and follow the instructions therein to view API documentation for an API Pack.

    Note

    The DigitMarket™ API Manager** Publisher portal provides a provision for the publisher to upload the API Pack and Usage Plan documentation. DigitMarket™ API Manager does not mandate nor validate what must be provided as part of API documentation provided by the Publisher. The Publisher decides at its sole discretion what information will be uploaded for the Packs and Usage Plans.

6.2. Protection

OWASP top 10 vulnerability threat protection is achieved using ModSecurity. ModSecurity acts as the web application firewall. This layer, provides protection against the following:

  1. Virtual Patching
  2. IP Reputation
  3. Web-based Malware Detection
  4. Web shell/Backdoor Detection
  5. Botnet Attack Detection
  6. HTTP Denial of Service (DoS) Attack Detection
  7. Anti-Virus Scanning of File Attachments
  8. HTTP Protocol Protection
  9. Real-time Blacklist Lookups
  10. Error Detection and Hiding

All configuration is controlled via the ModSecurity rule files. While we define the rules to ensure maximum security, there maybe customer specific rules which need to be tweaked/created. There are 70+ rules implemented for various threat scenarios which are run over every request which is processed by the gateway. These rules can be selectively turned off or all of them can be turned off by setting modsecurity off; flag in the nginx.conf file. Note that this is not recommended.

Example of rule changes needed:

The below configuration blocks DOS attacks once more than 60 calls from an IP address are received.

SecRule IP:DOS_BLOCK "@eq 1" \

  "id:912120,\

  phase:1,\

  drop,\

  msg:'Denial of Service (DoS) attack identified from %{tx.real_ip} (%{tx.dos_block_counter} hits since last alert)',\

  tag:'application-multi',\

  tag:'language-multi',\

  tag:'platform-multi',\

  tag:'paranoia-level/1',\

  tag:'attack-dos',\

  chain"

SecRule &IP:DOS_BLOCK_FLAG "@eq 0" \

  "setvar:'ip.dos_block_counter=+1',\

  setvar:'ip.dos_block_flag=1',\

  setvar:'tx.dos_block_counter=%{ip.dos_block_counter}',\

  setvar:'ip.dos_block_counter=0',\

  expirevar:'ip.dos_block_flag=60'"

This will need to be changed based on customer specific number of calls during the product implementation.

To further understand about ModSecurity configuration, please refer https://github.com/SpiderLabs/ModSecurity/wiki.

6.3. SOAP attachments

DigitMarket™ API Manager supports adding of attachments to your SOAP messages. You can send and receive SOAP messages that include binary data (such as, PDF or JPEG files). SOAP messages can contain referenced attachments, in which case the message has references to the attached file, and unreferenced attachments, which is carried in a SOAP message without any representation in the message schema.

6.3.1. Referenced Attachments

DigitMarket™ API Manager supports a referenced attachment using MIME-like approaches such as MTOM and SwaRef. Hence, attachments can be represented in one of the following ways:

6.3.1.1. MTOM attachments

MTOM attachments use the SOAP Message Transmission Optimization Mechanism(MTOM) specified encoding for sending binary data as part of an XML message. MTOM requires the use of XML-binary Optimized Packaging (XOP) packages for transmitting binary data. MTOM attachments are enabled through a configuration option in the import and export bindings and are the recommended way to encode attachments for new applications.

With MTOM, the binary data is transmitted outside the envelope as a MIME attachment. In a MIME multipart SOAP message, the SOAP body is the first part of the message, and the attachment or attachments are in subsequent parts. For efficient processing of the message, the binary data that makes up the attachment, instead of being parsed as XML, is held separately from the SOAP message body. The binary data element in the message contains an XOP <include> element referring to the second part of the message that contains the attachment. In case MTOM is disabled on the client side, then the attachment is converted to xml data type (xs:base64Binary) and sent as a part of the SOAP envelope.

For MTOM, in the SOAP message, the SOAP body contains codes as below:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xm="http://www.w3.org/2005/05/xmlmime">
<soapenv:Header/>
 <soapenv:Body>
  <Attachment_Add>
   <binaryData><inc:Include href="cid:sample.gif" xmlns:inc="http://www.w3.org/2004/08/xop/include"/></binaryData>
  <Attachment_Add>
  </soapenv:Body>
</soapenv:Envelope>

Content-Type: image/gif; name=sample.gif
Content-Transfer-Encoding: binary
Content-ID: <sample.gif>
Content-Disposition: attachment; name="sample.gif"; filename="sample.gif"

6.3.1.2. SWA and swaRef attachments

For SWA (Soap with Attachments) and swaRef attachments are an older mechanism to add attachments to SOAP messages. For each, the WSDL has different elements.

For SWA, in the SOAP message, the SOAP body contains codes as below:

SOAP definition with SWA element

Fig. 6.1 SOAP definition with SWA element

For swaRef, in the SOAP message, the SOAP body contains codes as below:

SOAP definition with swaRef element

Fig. 6.2 SOAP definition with swaRef element

SOAP message with swaRef element

Fig. 6.3 SOAP message with swaRef element

6.3.2. Unreferenced Attachments

An unreferenced attachment is carried in the SOAP message without any reference to the message schema. You can send and receive unreferenced attachments that are not declared in the message schema. No reference to the attachment is included in the SOAP message body.

SOAP message with unreferenced attachment

Fig. 6.4 SOAP message with unreferenced attachment

6.4. WSDL Download

DigitMarket™ API Manager, through its gateway, allows users to download WSDL or ZIP(Where the zip folder contains xsd’s or WSDL files for the respective SOAP service) files that they upload when creating and configuring SOAP APIs. The uploaded WSDL has data for adding operations for a SOAP API. Refer: Add Operations to a SOAP API and Assign a Name and Type to an API for more information.

To download the WSDL files, users can use the following APIs from the gateway:

  • Download using exposure base path

    Method

    GET  

    API URI

    http://<gatewayip>:<gatewayport>/<exposed_basepath>?wsdl

    Where,

    • gatewayip is the IP/Host name for the gateway,
    • gatewayport is the port number for the IP/Host name,
    • exposed_basepath is the exposure basepath for the SOAP API.

  • Download using API name and API version

    Method

    GET  

    API URI

    http://<gatewayip>:<gatewayport>/<API_Name>/<API_Version>?wsdl

    Where,

    • gatewayip is the IP/Host name for the gateway,
    • gatewayport is the port number for the IP/Host name,
    • API_Name is the name of the SOAP API,
    • API_Version is the version of the SOAP API.

6.5. Charset and Emoji support

6.5.1. Charset support

UTF-8 is the charset supported by DigitMarket™ API Manager gateway.

6.5.2. Emoji support

The table below shows the emoji characters supported by DigitMarket™ API Manager gateway.

Emoji Support

Fig. 6.5 Emoji Support