Version: 3.8

Gateway

The gateway is one of the core component to the THAPI Manager platform, offering essential functions:

Authorizing users through subscription key verification
Authenticating calls using industry-standard methods
Accepting API calls via exposed endpoints and directing them to service back ends
Transforming requests and responses based on user configurations
Performing schema validation
Enforcing usage quotas and rate limits
Implementing request time-outs

Consuming APIs through the Gateway

Developer users consume APIs via THAPI Manager by authenticating, accessing endpoints, formatting requests, handling responses, managing errors and adhering to rate limits by the Gateway.

Authorization

Authorization in THAPI Manager verifies user access to subscribed backend resources via subscription keys, mandatory for all consumers, included in the HTTP request header for both paid and free API access subscriptions.

API consumers are required to set the subscription key in the HTTP request header using the format:

Authorization: THAPIM-Subs-Key <Subscription Key>

Once activated by the Publisher user, the Subscription Key will be accessible on the Subscription detail page. APIs can be consumed using methods such as Header Key, Query Parameter and IP White Listing.

IP Whitelisting restricts access to trusted IP addresses, managed by Publisher user or Developer users who can specify individual IPs or ranges during subscription.
Header Key is a key-value pair passed in the request header for API consumption, defined during authentication selection, with values set by Publisher user or Developer user.
Query Parameter is a key-value pair passed in the request URL for API consumption, defined during authentication selection, with values set by Publisher user or Developer user.

Authentication

THAPI Manager ensures secure backend API access via three authentication mechanisms:

Basic Authentication: Uses the 'Authorization' HTTP header with credentials encoded in Base64 format

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

Credentials must match those configured in the Subscription page.

WS Security: Specifically for SOAP APIs, uses credentials passed in the SOAP message's header. Credentials are validated against those configured during subscription before access is granted.

OAuth Authentication: Uses the 'Authorization' HTTP header with OAuth access tokens. Developers generate access tokens via the Developer portal or Gateway OAuth API, which are then included in requests.

Authorization: Bearer <access token>

Tokens can be validated or revoked using corresponding Gateway APIs.

API reference details

Consumers require knowledge of the API exposure endpoint, available methods, required parameters for requests and how to manage responses and errors. This information is detailed in the API documentation accessible from the Subscription and API Pack sections on the Developer portal, covering endpoint paths, parameters and error codes. The documentation's availability and content are determined by the publisher user on the THAPI Manager Publisher portal.

Protection

ModSecurity, functioning as a web application firewall, safeguards against OWASP top 10 vulnerabilities through:

Virtual Patching
IP Reputation Management
Detection of Web-based Malware, Web Shells and Backdoors
Botnet Attack Detection
Detection of HTTP Denial of Service (DoS) Attacks
Anti-Virus Scanning for File Attachments
HTTP Protocol Protection
Real-time Blacklist Lookups
Error Detection and Concealment

Configuration is managed via ModSecurity rule files, enabling customization for customer-specific security needs. Over 70 rules cover diverse threat scenarios, applied to every processed request. While rules can be selectively disabled, the blanket disabling using modsecurity off; in nginx.conf is discouraged for security reasons.

An example of necessary rule changes:

This configuration prevents Denial of Service (DoS) attacks by blocking IP addresses after receiving more than 60 requests:

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 threshold should be adjusted based on the specific number of requests required for each customer during product implementation.

For more detailed information on ModSecurity configuration, please refer to https://github.com/SpiderLabs/ModSecurity/wiki.

SOAP Attachments

THAPI Manager supports adding attachments, such as PDF or JPEG files, to SOAP messages. Attachments can be referenced, with links to files, or unreferenced, existing within the SOAP message schema.

Referenced Attachments

THAPI Manager supports referenced attachments using MIME-like methods such as MTOM and SwaRef, offering the following representation options:

MTOM Attachments

MTOM (SOAP Message Transmission Optimization Mechanism) enhances XML message efficiency by using a specified encoding to transmit binary data. This approach necessitates XML-binary Optimized Packaging (XOP) for handling binary content. Configuration settings in import and export bindings enable MTOM attachments and are recommended for new applications.

With MTOM, binary data is sent as a MIME attachment outside the SOAP envelope. In a MIME multipart SOAP message, the SOAP body forms the initial part, with attachments following in subsequent parts. This separation optimizes message processing by keeping binary data outside the SOAP body. The message's binary content is referenced within the SOAP message using an XOP <include> element that points to the attachment's location in the multipart message.

If MTOM is disabled on the client side, attachments are converted to the XML data type (xs) and included within the SOAP envelope.

For MTOM, the SOAP body comprises codes as follows:

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

SWA and swaRef Attachments

For SWA (Soap with Attachments), the SOAP body within the SOAP message typically contains the following structure:

att1

For swaRef attachments in a SOAP message, the SOAP body includes the following code structure:

att2

att3

Unreferenced Attachments

An unreferenced attachment in a SOAP message is transmitted without being explicitly referenced in the message schema. These attachments can be sent and received without being declared in the schema. Importantly, the SOAP message body does not contain any reference to these attachments.

att4

WSDL Download

THAPI Manager facilitates users to download either WSDL or ZIP files via its gateway. The ZIP file includes XSDs or WSDL files related to the SOAP service that users upload during the creation and configuration of SOAP APIs. The uploaded WSDL contains necessary data to define operations for the SOAP API.

Users can utilize the following APIs from the gateway to download the WSDL files:

GET /api/wsdl/{wsdl_id}: Retrieves the WSDL file identified by {wsdl_id}.
GET /api/wsdl/download/{wsdl_id}: Initiates the download of the WSDL file identified by {wsdl_id}.

These APIs allow users to access and download specific WSDL files they have uploaded or configured within THAPI Manager.

Charset support

The THAPI Manager gateway supports UTF-8 character encoding (charset).

Emoji support

Here are some commonly used basic emoji characters supported by the THAPI Manager gateway:

Emoji Character	Description	Emoji Character	Description
😀	Grinning Face	😊	Smiling Face with Smiling Eyes
😂	Face with Tears of Joy	🥰	Smiling Face with Hearts
😎	Smiling Face with Sunglasses	😍	Heart Eyes
🤩	Star Eyes	🥳	Party Face
🤗	Hugging Face	🤔	Thinking Face
😐	Neutral Face	😕	Confused Face
😢	Crying Face	😡	Pouting Face
😴	Sleeping Face

Gateway OAuth APIs

This section explains the interface definition of THAPI Manager's OAuth APIs along with examples. Common circumstances, such as error conditions, apply to all use cases and are discussed at the conclusion.

Base URL

All URLs in this section use the following base URL with Gateway's NGINX:

http(s)://<gateway_nginx_ip>:<port>/<OAuth Basepath>

info

The 'OAuth Basepath' refers to the base path configured in the OAuth gateway and portal properties.

Generate an access token

POST Method

URL Format: <base URL>/getToken

Note: 
For all requests to generate an access token, ensure the content-type is set to "application/x-www-form-urlencoded". This should be reflected in the HTTP header field "Content-Type".

Resource Properties

Field	Mandatory?	Description
grant_type	Mandatory for all grant types	The grant type using which the access token is created
client_id	Mandatory for all grant types	The client ID of the registered application
client_secret	Mandatory for all grant types	The client secret of the registered application
username	Mandatory for password grant type	The username should be sent with request for password grant type
password	Mandatory for password grant type	The password should be sent with the request for password grant type
refresh_token	Mandatory for refresh token grant type	The value of refresh_token obtained along with an access token issued; used only with refresh_token grant type
scope	Mandatory for all grant types	The scope of the access token that will be issued

Error Scenarios

If the scope passed is not allowed for that client application or the scope does not exist, the response from the OAuth provider is as follows (applicable to all grant types):

<Actual response from the OAuth provider>

If there is an error at the OAuth Service Provider’s end, the response is as follows (applicable to all grant types):

<Actual response from the OAuth provider>

Details for Grant Types

Client Credentials Grant Type

Request:

grant_type=client_credentials&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxxxxx&scope=read

Response:

<Actual response from the OAuth provider>

Password Grant Type

Request:

grant_type=password&client_id=xxxxxxxxxxxxxxx&client_secret=xxxxxxxxxxxxxx&username=
username&password=xxxxxxxxx&scope=read

Response:

<Actual response from the OAuth provider>

Refresh Token Grant Type

Request:

grant_type=refresh_token&client_id=xxxxxxxxxxxx&client_secret=xxxxxxxxxxxxx&refresh
        _token=xxxx&scope=read

Response:

<Actual response from the OAuth provider>

Validate an access token

POST Method

URL Format: <base URL>/validateToken

Resource Properties

Field	Mandatory?	Description
access_token	Yes, mandatory	The token to be validated

Error Scenarios

If the token is invalid, the response will be as follows:

<Actual response from the OAuth provider>

Request (Request Body):

{
"access_token":"access_token_to_be_validated",
}

Response:

If the provided token is valid, the response will be as follows:

<Actual response from the OAuth provider>

Revoke an access token

POST Method

URL Format: <base URL>/revokeToken

Resource Properties

Field	Mandatory?	Description
access_token	Yes, mandatory	The token to be revoked
client_id	Yes, mandatory	The client_id of the application for which the token was generated

Request(Request Body):

{
"access_token":"access_token_to_be_revoked",
"client_id":"xxxxxxxxxxxxxxxxxxxxxxx"
}

Response:

If the token was successfully revoked, the response would be as follows:

<Actual response from the OAuth provider>

If the token revocation fails, the response will be as follows:

<Actual response from the OAuth provider>

Common Scenarios

The following scenarios are common for all APIs:

OAuth Provider Unreachable: If the OAuth provider cannot be reached, the gateway responds with a standard REST fault structure predefined in the global configuration named OAuth Server Unavailable.
OAuth Plugin Error: If an error occurs during plugin execution, the gateway responds with a standard REST fault structure predefined in the global configuration named OAuth Plugin Error.
Plugin Unavailable: When the OAuth plugin is unavailable, the gateway responds with a standard REST fault structure predefined in the global configuration named OAuth Plugin Unavailable.
OAuth Request Timeout: Each request sent to the OAuth Service Provider has a configurable timeout. If the response is not received within this timeout period, the gateway closes the connection and responds with a standard REST fault structure predefined in the global configuration named OAuth Server Request Timeout.
Invalid OAuth Request URL: If a base path starts with "oauth" and is invalid, the gateway responds with the message "Invalid OAuth Request URL."

Get a list of all scopes for an application

GET Method

Resource URI:

URL Format: <base URL>/scopes/{client_Id}

Request(Request Body): Not required

Response:

[
 {
  "scope": "scope name",
  "description": "scope description",
  "cc_expires_in": 3000,
  "pass_expires_in": 1200,
  "refresh_expires_in": 3000
 }
]

Error Scenarios

If the client Id is invalid, Gateway will respond with the following fault response:

{
 "error": "invalid client id"
}

If the request URL is /oAuth/scopes, Gateway responds the following fault response:

{
 "Faults": {
   "FaultCode": "GW_401",
   "FaultString": "Invalid OAuth Request URL",
   "detail": {
      "Fault": {
        "FAULTCODE": "GW_401",
        "FAULTDESC": "Invalid OAuth Request URL",
        "FaultOriginator": "AG",
        "TransactionID": "29485aba-46a3-4f70-a432-d2c4482be3c4"
      }
    }
  }
}

If the request URL is /oAuth/scopes/, Gateway considers it as an empty client Id and responds with the following error response:

{
   "error": "invalid client id"
}

If the get scope API call is requested for a deactivated/inactive application, the gateway responds with the following fault response:

{
 "error": "application is inactive"
}

Consuming APIs through the Gateway​

Authorization​

Authentication​

API reference details​

Protection​

SOAP Attachments​

Referenced Attachments​

MTOM Attachments​

SWA and swaRef Attachments​

Unreferenced Attachments​

WSDL Download​

Charset support​

Emoji support​

Gateway OAuth APIs​

Generate an access token​

Validate an access token​

Revoke an access token​

Get a list of all scopes for an application​

Consuming APIs through the Gateway

Authorization

Authentication

API reference details

Protection

SOAP Attachments

Referenced Attachments

MTOM Attachments

SWA and swaRef Attachments

Unreferenced Attachments

WSDL Download

Charset support

Emoji support

Gateway OAuth APIs

Generate an access token

Validate an access token

Revoke an access token

Get a list of all scopes for an application