Implement APIs

API Implementation

After you create an API, it is time to start defining the behavior of the API.

Some of the important considerations that you take into account when you define your API’s behavior are:

• Enable API mocking

• Enforce policies

• Ensure proper caching, filtering and error handling mechanisms

• Enforce policies

• Apply rate limiting

• Enable API testing and debugging

• Define monitoring and debugging mechanisms

API Gateway UI provides a visual guided experience for designing, developing, and testing APIs. The API caching, filtering, and sorting capability helps in retrieving your APIs faster. You can use the pagination function to determine how much data must be displayed and at what frequency. These features ensure minimum processing and good response time.

API Gateway provides various policies that are designed to let you add management capabilities, to an API or to all APIs at a global level, easily. You can enforce these policies on an API to secure, limit, and route requests sent to APIs.

The API testing capability allows you to test your APIs before you publish them onto a portal for consumption. API Gateway also provides the API mocking capability that enables you to simulate the behavior of a real API for testing the API.

API Gateway provides logging and monitoring capabilities that help debug your APIs so that locating the root cause of the issue based on what is observed is easy. In addition, you can monitor API usage to understand API trends.

The following sections describe the various ways in which you can implement your APIs such as, API mocking, enforcing different types of policies as required, creating and managing applications and aliases, creating API mashup, and so on.

API Mocking

Using API Gateway, you can mock an API by simulating the native API. For example, if you have an API without a native implementation, you can mock that API. The mocked response is returned to the consumer when the API is invoked.

In API Gateway, when you enable mocking for an API, a default mock response is configured for each combination of resource, operation, status code, and content-type based on the example and schema specified in that API. You can add a condition to the operation in the resource.

As an API Provider, you can create or modify the default mock response. You can specify conditions and associate an IS service with the mocked API. When an IS service is associated with a mocked API, the associated IS service must adhere to the apigateway.specifications:mockService specification.

At runtime, when the mocked API is invoked, instead of calling the native API, API Gateway returns the mocked response to the consumer based on the following priorities:

1. If any of the conditions for the invoked operation satisfies, API Gateway returns the associated mocked response.

2. If any of the conditions for the invoked operation is not satisfied, and if an IS service is configured for the API, then API Gateway invokes the IS service and returns the IS service response.

3. If any of the conditions for the invoked operation is not satisfied, and if an IS service is not configured for the API, then API Gateway returns the default mocked response.

API mocking is supported only for SOAP and REST APIs.

Enabling API Mocking

You can enable or disable API mocking through the API details page.

To enable API mocking

1. Click APIs in the title navigation bar.

2. Select the required API from the list of available APIs.
   The API details page for the selected API appears.

3. Click and select Enable mocking.
   This generates the default mock responses.

Modifying API Mocking Details

You must select Enable mocking from the API details page.

You can modify API mocking details, as required, from the API details page.

To modify API mocking details

1. Click APIs in the title navigation bar.
   A list of all registered APIs appears.

2. Click the required API. The API details page appears.

3. Click Edit.

4. Click API mocking.

5. Specify the following information in the IS service section:

   Field	Description
   Invoke service	Specifies the webMethods Integration Server service to be invoked.
   Run as user	Type the user name you want API Gateway to use to invoke the IS service.

6. Select the operation that you want to modify from the Mocked responses section.

7. Click Add Response if you want to add a response and select the status code from the drop-down.

8. Click .
   This adds the status code created to the existing status code list.

9. Select the status code you want to modify.

10. Click + Add Response Header and provide the following information to add the required response headers:

    Field	Description
    Header key	Specify the HTTP header key that would be contained in the header of HTTP response.
    Header value	Specify the HTTP header value that would be contained in the header of HTTP response.

    You can add more response headers by clicking .

11. Click + Add Content-type to add a content-type to the status code selected and provide the following information:

    Field	Description
    Content type	Select the content-type to be added to the selected status code from the drop-down list.
    Mock payloads	Specify a mock response payload for the content-type selected.

    You can add more content-types by clicking Add.

12. Click + Add Conditions to add a condition to the operation in the resource:

    Field	Description
    Condition name	Specify the name for the condition.
    Condition parameter	Select the type to which the condition is to be applied. The available options are: Body Header Query parameter (Applicable only for REST APIs)
    Key	The key can be a string for the header and query parameter and for body it can be a JSON path or an XML path.
    Value	The value of the condition. Additionally, you can type an * (asterisk) to ignore the value specified in this parameter and the condition is satisfied based on the value specified in the Key parameter.
    Status code	Select the status code from the drop-down list. Note: You must enable the property Send native provider fault in the Administration > General > API fault section in order to have correct mock response for status code 506. While invoking an API remember to use the query parameter expectedStatusCode in order to have correct mock responses for status codes 100 and 202.
    + Add Response Header	Add a response header to the resource selected by providing the following information: Header key. Specify the HTTP header key that would be contained in the header of HTTP response Header value. Specify the HTTP header value that would be contained in the header of HTTP response.
    + Add Content-type	Add a content-type to the status code selected by providing the following information: Content type. Select the content-type to be added to the selected status code from the drop-down list. Mock payload. Specify a mock response payload for the content-type selected.

    You can add more conditions by clicking Add.

13. Click Save.

Custom Replacer

API Gateway allows you to send a dynamic custom response instead of a static mocked response to the consumer when the mocked API is invoked. In the mocked response, you can specify multiple custom replacers. Custom replacer is used to replace the custom variables with the values defined in the request headers, query parameters, and request body. The custom replacer is available in the ${request.<ConditionParameter>.<Key|JsonPath|XPath>} format. The custom replacers are:

• ${request.header.<headerKey>}: To replace the value of the headerKey from the request headers.

• ${request.query.<queryKey>}: To replace the value of the queryKey from the query parameters in the request URL.

• ${request.body.<JsonPath|XPath>}: To replace the value of the <JsonPath|XPath> from the request body.

Consumer Applications

An application defines the precise identifiers by which messages from a particular application is recognized at run time. The identifiers can be, for example, user name in HTTP headers, a range of IP addresses, such that API Gateway can identify or authenticate the applications that are requesting an API.

The ability of API Gateway to relate a message to a specific application enables it to:

• Control access to an API at run time (that is, allow only authorized applications to invoke an API).

• Monitor an API for violations of a Service-Level Agreement (SLA) for a specified application.

• Indicate the application to which a logged transaction event belongs.

An application has the following attributes for specifying the identifiers:

• IP address, which specifies one or more IP addresses that identify requests from a particular application. Example: 192.168.0.10
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using IP address.

• Claims set, which specifies one or more claims that identify requests from a particular application. The claims are a set of name-value pairs that provide sufficient information about the application. Example: sub = Administrator.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications using a JWT token or an OpenID token.

• Client certificate, which specifies the X.509 certificates that identify requests from a particular application.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify the applications by a client certificate.

• Identification token, which specifies the host names, user names or other distinguishing strings that identify requests from a particular application.
  This attribute is queried when the Identify and Authorize Application policy is configured to identify applications by host name, token, HTTP user name, and WSS user name.

You can configure various authentication strategies to authenticate an incoming request to the application. You can create multiple strategies authorized by an API for an application. These strategies provide multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. For example, in case of OAuth authentication scheme, you want the application to support both OKTA and PINGFederate or OKTA with multiple tenants. This can be configured as OAuth strategy for the application.

If you have the Manage Application functional privilege assigned, you can create and manage applications, and register applications with the APIs.

These are the high level stages of managing and using an application:

1. API developers request the API Gateway administrators to create an application for access as per the required identification criteria.

2. API Gateway provider or administrator validates the request and creates a new application, there by provisioning the application specific access tokens (API access key and OAuth credentials).

3. API Developer, upon finding a suitable API, sends a request to API Gateway for consumption by providing the application details.

4. After validating the request, API Gateway provider or administrator associates the application with the API. Keys are generated for applications and not for every API that the application consumes.

   Note

   The approval process, if any, is handled by the requesting application and not handled by API Gateway.

5. The API developer can then use the application with the proper identifier (such as the access key or identifier) to access the API.

API key expiration date

An API Gateway application has an optional expiration date for its API key. When the API access key expires, the application cannot be identified. The API Gateway Administrator can configure the apiKeyExpirationPeriod parameter from the General > Extended settings page. If the expiration date is not specified, then the API key never expires.

Suspended Applications

You can suspend applications so as to disable the identification of requests temporarily. If a suspended application is identified while processing a request the request is rejected with HTTP 403 (Forbidden) error. The response body has the following content:

Application has been identified but it is currently suspended. Please contact
the API Gateway administrator for further details.    

You can resume the suspended applications to enable the identification again.

Creating an Application

You must have the API Gateway’s manage applications functional privilege assigned to perform this task.

To create an application

1. Click Applications in the title navigation bar.

2. Click Create application.

3. Provide the following information in the Basic information section:

   Field	Description
   Name	Type a name for the application.
   Version	Version of the application. By default it is 1.0 but can be modified to a required value.
   Owner	Name of the team who owns the application. The application owner can view all details of the application including the API access key. If you specify a team as application owner, then all members of the team can view the API access key. Note: You cannot modify ownership details of the applications you create through Developer Portal.
   Description	Type a description of the application.
   Requestor comment	Specify your comments, if any. This field is visible only when the approval configuration for Create application is enabled in the Administration > General > Approval Configuration > Create application section.

   The pending requests for an application can be approved by one of the following:

   • List of users and user groups of the teams that the application is associated with. You must specify the required users and user groups in the Approvers section of the Basic information tab when creating or editing the corresponding team.
   • List of users and user groups of the teams that the application is associated with. You must specify the required users and user groups in the Team Administrators section of the Basic information tab when creating or editing the corresponding. This is applicable only if the Include team administrators as approvers option is selected.
   
   For information on options that can be configured for a team, see Creating Teams.

4. Click Continue to Identifiers.
   Alternatively, you can click Identifiers in the left navigation panel.
   You can save the application by clicking Save at this stage and add the Identifiers and APIs at a later time.

5. Provide the following information in the Identifiers section:

   Field	Description
   IP address range	Provide the IP address range or range of trusted IPv4 or IPv6 addresses that identify requests from a particular application. You can add more range options by clicking +Add and adding the required information.
   Partner identifier	Specifies the third-party partner’s identity.
   Client certificates	Click Browse and select the client certificate or certificate chain to be uploaded. The client certificate specifies the X.509 certificates that requests from a particular application. Note: API Gateway supports .cer and .pem certificates for identifying consumer applications. You can add multiple certificates by clicking +Add
   Claims	Provide a set of claims for the JWT and OpenID clients. A claim is a unique identifying information that identify requests from a particular consumer application. The claim set is identified by a unique Name and is defined as a name-value pair that consists of a Claim name and a Claim value. You can add more claims and claims sets by clicking +Add and adding the required information.
   Header key	Specify the HTTP header key to identify the requests from an application.
   Header value	Specify the HTTP header value to identify the requests from an application. You can add multiple header key and value by clicking +Add.
   Other identifiers	Select one of the options to identify requests from a particular application and provide the required value: Hostname. Specify the host name. Token. The token that is required to identify requests from an application. Username. The username credential to identify requests from an application. WS-Security username. The WSS username to identify requests from an application. Payload identifier. The payload identifier that is required to identify requests from an application.

6. Click Continue to APIs >.
   Alternatively you can click APIs in the left navigation panel.
   You can save the application by clicking Save at this stage and add the APIs at a later time.

7. Type a keyword to find the required API and click + to add the API.
   Adding an API to the application enables the application to access the API. An API developer while invoking the API at runtime, has to provide the access token or identification token for API Gateway to identify the application.

8. Type the required Requestor comment.

9. Click Continue to Advanced >
   Alternatively you can click Advanced in the left navigation panel.
   You can save the application by clicking Save at this stage and add the APIs at a later time.

10. Specify the origin from which the responses originating are allowed during response processing for the application.

11. Click +Add to add the origin.
    You can add multiple origins using .

12. Click Continue to Authentication >
    Alternatively you can click Authentication in the left navigation panel.
    You can save the application by clicking Save at this stage and add the Authentication strategy at a later time.

13. Click Create strategy.
    A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. You can create multiple strategies authorized by an API for an application.

14. Select one of the Authentication schemes:

    • OAUTH2. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The available values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials	Enable the toggle button to generate the client dynamically in the authorization server and provide the following information: Type. Select one of the client types: Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password. Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password. Application type. Specify the application type. WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential. USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded. NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too. Token lifetime. Specify the token lifetime in seconds for which the token is active. Token refresh limit. Specify the number of times you can use the refresh token to get a new access token. Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add. Grant type. Specify the grant type to be used to generate the credentials. Available options can be authorization_code, passeord, client_credentials, refresh_token, and implicit which are dynamically populated from the authorization server. For example, if the authorization server does not support client credentials, the option is not available in the options list. Scopes. Select the scopes that are to mapped for the authentication strategy. Note: In API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id	Specify the Client identifier for a client application available in the authorization server that identifies the client application in the authorization server to map the client to the API Gateway application. This is required if you have a client application available in the authorization server and do not want to dynamically create a client.

    • JWT. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The possible values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      HMAC algorithm	Select if the authorization server is returning a JWT with HMAC algorithm and provide the shared secret value to validate the JWT.

    • OPENID. Provide the following information:

      Field	Description
      Name	Provide the name for the strategy.
      Description	Provide a description to describe the strategy.
      Authentication server	Specify the authentication server. The available values are local, which is the default server or any other configured external authorization server.
      Audience	Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
      Generate Credentials	Enable the toggle button to generate the credentials required to identify the client application and provide the following information: Type. Select the client type, Public or Confidential. Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password. Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password. Application type. Specify the application type. WEB. A web application is an application running on a web server. In reality, a web application typically consists of both a browser part and a server part. The client password could be stored on the server. The password would thus be confidential. USER_AGENT. A user agent application is for instance a JavaScript application running in a browser. The browser is the user agent. A user agent application may be stored on a web server, but the application is only running in the user agent once downloaded. NATIVE. A native application is for instance a desktop application or a mobile phone application. Native applications are typically installed on the users computer or device (phone, tablet etc.). Thus, the client password will be stored on the users computer or device too. Token lifetime. Specify the token lifetime in seconds for which the token is active. Token refresh limit. Specify the time in seconds for which the token refresh is applicable. Redirect URIs. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add. Grant type. Specify the grant type to be used to generate the credentials. Available options are Authorization code, Implicit, Resource owner, Client credentials. Scopes. Select the scopes that are to be associated to the generated client. Note: In API Gateway 10.2, the scopes are automatically created when you associate an API to an application. From API Gateway 10.3 onwards you have to select scopes from the authorization server that have to be associated with the strategy.
      Client id	Specify the Client identifier that identifies the client application in the authorization server to map the client to the API Gateway application. This is required if you do not choose to generate credentials to identify the client application.

15. Click Add.
    The strategy is configured and listed in the Strategies table.
    

    Note

    API Gateway allows you to generate a new Client ID and Client Secret for an existing strategy. However, once the credentials are generated for a strategy, it can no longer be removed. The Generate credentials toggle is disabled in the UI when you update a strategy.

16. Click Save.
    The application is created and listed in the list of applications in the Manage applications page, once approved.

Viewing List of Applications and Subscriptions

You can view the list of applications in the Manage applications page from where you can create, delete, and select an application to view its details.

To view the application list and application and subscription details

1. Click Applications in the title navigation bar.
   A list of all registered applications and subscriptions appear.

   • denotes application.
   • denotes subscription.
   
   

2. Select an application.
   
   The application details page displays the following information: basic information that contains details such as name, description, owner, and creation time, identifiers, access tokens, APIs registered for the application, advanced configurations, and authentication strategies configured for the application.

   Application credentials, such as, API Keys or OAuth client secrets are visible only to the application owner. All other users can only see an encrypted value. Since Developer Portal and API Gateway do not support a central user management, API Gateway users cannot see the application credentials of the application requested through Developer Portal.

3. Select a subscription.
   
   You can view the applications and the associated package, plan, used quota, start time, end time, and the remaining period of the subscription.

   Note

   You cannot create a subscription from this page. To create a subscription, use the subscription API. For details about creating subscriptions using a REST API, see Subscription Management.
   You can also create a subscription from the Developer Portal.

Regenerating API Access Key

You must have the API Gateway’s Manage applications functional privilege assigned to perform this task.

You can regenerate an API access key in the application details page from where you can view application details.

To regenerate an API key

1. Click Applications in the title navigation bar.
   A list of all registered applications is displayed.

2. Select an application.
   The application details page displays the basic information, identifiers, access tokens, API key, APIs registered and strategies configured for that application.

3. Click .
   The API access key is regenerated and the new API access key appears in the API access key field.

Modifying Application Details

You can modify the details of an application as required from the application details page.

To modify application details

1. Click Applications in the title navigation bar.
   A list of registered applications is displayed.

2. Select an application.

3. Click Edit in the application details page.

4. Modify the required fields in the Basic information section.
   

   Note

   You cannot modify ownership details of the applications you create through Developer Portal.

5. Click Identifiers.

6. Modify the required fields in the Identifiers section.

7. Click APIs.

8. Add or delete the APIs that are registered.

9. Modify the strategies or create a new strategy.

10. Modify the required values.

11. Click Save.

Registering an API with Consumer Applications from API Details Page

Consumer applications created in API Gateway can be associated with APIs from the API details page.

To register APIs with consumer applications

1. Click APIs in the title navigation bar.
   A list of APIs is displayed.

2. Select an API.

3. Click Edit in the API details page.

4. Click Application tab in the API details page.

5. Type characters in the search field and click the Search icon.
   This field displays the only list of applications that are assigned to the teams that you are a part of.

6. Select the required applications and click +.
   You can add more applications in a similar way.

7. Click Save.

Suspending an Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

To suspend an application

1. Click Applications in the title navigation bar.
   A list of all the available applications are displayed.

2. Click the toggle button (Active state), in the action column for the respective application, to suspend the application.
   Alternatively, you can click Suspend in the application details page.

3. Click Yes in the confirmation dialog box.
   The application is suspended. The toggle button in the Applications page changes to (suspended state) and the option in the application details page changes to Suspend.

Activating a Suspending Application

You must have the API Gateway’s Manage applications functional privilege assigned or you must be the owner of the application to perform this task.

You can activate a suspended application, from the application details page.

To activate a suspended application

1. Click Applications in the title navigation bar.
   A list of all the available applications are displayed.

2. Click the toggle button (suspended state), in the action column for the respective application, to activate the application.
   Alternatively, you can click Activate in the application details page.

3. Click Yes in the confirmation dialog box.
   The application resumes. The toggle button in the Applications page changes to (active state) and the option in the application details page changes to Suspend.

Policies

API Gateway provides a policy framework that enables you to program API behavior and implements specific limited management functions without writing any code. You can enforce a policy on an API to perform specific tasks, such as transport, security, logging, routing of requests to target services, and transformation of data from one format to another. You can also define a policy to evaluate and process the various API invocations at runtime. For example, a policy could instruct API Gateway to perform any of the following tasks and prevent malicious attacks:

• Verify that the requests submitted to an API come from applications that are authenticated and authorized using the specified set of identifiers in the HTTP header to access and use the particular API.

• Validate digital signatures in the security header of request and response messages.

• Monitor a user-specified set of run-time performance conditions and limit the number of invocations during a specified time interval for a particular API and for applications, and send alerts to a specified destination when these performance conditions are violated.

• Log the request and response messages, and the run-time performance measurements for APIs and applications.

You can enforce policies in an API in the following ways:

• Global policy enforcement. This enforcement applies globally to all APIs defined in API Gateway. For example, the threat protection policies can be enforced for all APIs to protect against malicious attacks. For more information about threat protection policies, see Threat Protection Policies.

• API-level policy enforcement. This enforcement applies to all resources and its nested methods of a REST API, or all operations of a SOAP API. These policies are further categorized into stages depending on their usage such as:

  • Transport
  • Identify and Access
  • Request Processing
  • Response Processing
  • Routing
  • Error Handling
    
    

  For example, the Identify and access category of policies can be enforced on an API to specify the kind of identifiers that are used to identify the application and authorize it against all applications registered in API Gateway.

• Scope-level policy enforcement

  • Resource-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more resources and its nested methods in the REST API.
  • Method-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more methods nested within a resource in the REST API.
    -OR-
    
  • Operation-level policy enforcement. Applicable only for SOAP APIs. This enforcement applies to one or more operations in the SOAP API.

How does policy enforcement work?

When you apply the policies both globally (through global policies) and directly (through API-level policies and scope-level policies) to an API, API Gateway determines the effective set of policies for that API by taking into account the precedence of policy enforcement at the API-level, the policy stages, the priority of policies, run-time constraints, and the status (activated or deactivated) of any applied global policy.

For example, consider an API is enforced with the identify and access policy at the following policy enforcement levels: global, API-level, and scope-level. The precedence of the policy enforcement that is effective for the API at runtime is as follows:

1. Global Policy Enforcement

2. Method-level Policy Enforcement or Operation-level Policy Enforcement

3. Resource-level Policy Enforcement

4. API-level Policy Enforcement

If the API has the Identify and access policy applied through both globally and at the API-level, API Gateway does not show conflict. The Identify and access policy applied through the global policy takes precedence and is processed at runtime.

Similarly for a REST API, Identify and access policy is applied through a scope-level policy at the resource level and also at the API level, the Identify and access policy applied through the scope-level policy takes precedence and is processed at runtime.

When you apply a transport policy at the global level, the transport policy applied at the API level is in the disabled state. When you try deleting the API-level transport policy that is in the disabled state, an error displays and you are not allowed to delete this policy as the API-level transport policy is required and gets enforced when you deactivate the global policy.

Variable framework

All types of variables such as request, response, custom, custom-context, and system context variables are handled through the common framework called variable framework. The variable framework in API Gateway provides an option to extract variable values that can be used across stages. For example, you can use the extracted variable to transform request and response contents such as headers, query parameters, path parameters payload, and so on as per your requirement. With the variable framework, you can normalize the syntax and create a common template for accessing the various variable types. For details about the variable syntaxes to use, see Variable Framework.

Aliases

API Gateway provides the capability of using aliases. An alias holds stage-specific property values that can be be shared by multiple policy configurations. Aliases referenced by policy configurations are substituted during runtime. Changing an alias value affects all referencing policies. Aliases are referenced through a name, therefore, alias names have to be unique within an API Gateway. The corresponding alias value is substituted in place of an alias name during run-time. Thus the same alias can be referred to in multiple policies and the change in a particular alias would affect all the policy properties. For more details about aliases and how to use them, see Aliases.

Policy templates

API Gateway provides policy templates, which are a set of policies that can be associated directly with an individual API. Policy templates provide the flexibility to alter the policy’s configurations to suit the individual API requirements. These policy templates apply at the API level, and can be customized to suit the needs of a particular API. For more details about policy templates and how to use them, see Policy Templates.

Policy Validation and Dependencies

When you enforce a policy to govern an API at run-time, API Gateway validates the policies to ensure that:

• Any policy (for example, Log Invocation) that can appear in an API multiple times is allowed to appear multiple times.

• For policies (for example, Require HTTP / HTTPS) that can appear only once in an API, API Gateway issues an error message.

• For policies (for example, Monitor SLA) that are dependent and use another policy in conjunction (for example, Identify and Authorize Application) in an API, API Gateway prompts you with a warning message to include the dependent policy.

When you save an API, API Gateway combines the policies from all of the global and direct policies that apply to the API (that is, at the API-level) and generates what is called the effective policy for the API. For example, let’s say your REST API is within the scope of two policies: one policy that performs a logging task and another policy that performs a security task. When you save the REST API, API Gateway automatically combines the two policies into one effective policy. The effective policy, which contains both the logging task and the security task, is the policy that API Gateway actually uses to publish the REST API.

When API Gateway generates the effective policy, it validates the resulting policy to ensure that it contains no conflicting or incompatible policies.

If the policy contains conflicts or inconsistencies, API Gateway computes the effective API policy according to policy resolution rules. For example, an effective API policy can include only one Identify and Authorize Application policy. If the resulting policy list contains multiple Identify and Authorize Application policies, API Gateway shows the conflict by including an including a Conflict () icon next to the name of the conflicting policies in the effective policy. For details about policy validation and dependencies, see Policy Validation and Dependencies.

Transport

The policies in this stage specify the protocol to be used for an incoming request and the content type for a REST request during communication between API Gateway and an application. The policies included in this stage are:

• Enable Bulkhead

• Enable HTTP/HTTPS

• Set Media Type

Enable Bulkhead

Bulkhead configuration allows you to specify the maximum number of concurrent requests processed by an API. You can configure this setting individually for an API or globally for all APIs.

When the number of concurrent requests to an API exceeds the specified limit, the excess requests are rejected. In such scenarios, the policy violation events are generated to report the violations occurred for an API. If there are 100 violations, then 100 policy violation events are generated.

As per the order of policies, the Bulkhead limit policy is applied first. That is, if you have applied multiple policies including the Bulkhead limit policy, then the Bulkhead limit policy is applied first.

Why do we configure bulkhead limit for APIs?

In an environment where multiple APIs are running, there are chances of one API making maximum use of the system resources due to the number of invocations. This in turn suppresses the performance of other APIs. Consider the following example. The maximum thread pool size of your system is 100, and it is shared among five APIs. When there are 100 invocations to one API, then that API uses up all the available threads to process its requests. The others APIs must wait till there are available threads.

To prevent this, you can specify the maximum number of concurrent requests that an API can process. This number depends on the maximum thread pool size of your system. Consider the same scenario after specifying the bulkhead limit for the APIs. In our example, the thread pool size is 100 and if you configure 20 as the maximum concurrent limit for each API, then each of the APIs can process a maximum of 20 requests, exceeding which the requests are rejected.

This ensures optimal usage of the system resources.

As part of bulkhead configuration, you can specify

• Bulkhead limit for an API at the API level. Specifies the maximum concurrent request limit for an API, exceeding which the requests are rejected. This number does not include the callbacks that an API receives. So, you can separately specify the maximum concurrent callbacks that an API can handle. The 503 Service unavailable error code is sent to the client service when the requests are rejected. You can configure the required error code and status phrase using the extended settings. You can customize the required status code and message using the extended settings pg.bulkhead.statusCode and pg.bulkhead.statusMessage respectively.

• Bulkhead limit for all APIs (Global policy). Specifies the maximum concurrent request limit for all APIs. Similar to the API level configuration, you can provide the maximum concurrent callbacks and your choice to retry the rejected requests.

  When you have configured global-level bulkhead limit for APIs, and if you configure a different bulkhead limit at an API-level, then the limit configured at the global level takes precedence. To override this, you must exclude the required APIs from the global-policy using filters. You can apply the required API filters when creating or editing the bulkhead global policy. For information about creating global policies and applying API filters, see Creating a Global Policy.

• Add Retry-After response header. Specifies whether the Retry-After header must be included in the response sent to the client when requests are rejected. If you select to add, you must also specify the duration (in seconds) that the system must wait before sending the consecutive requests. You can configure this setting to keep the client informed on the waiting duration before processing the consecutive requests.

Enabling bulkhead for APIs at the API-level

This use case explains how to configure the bulkhead limit for an API.

This use case starts when you have an API for which you have to enforce a bulkhead limit and ends when you have successfully applied the bulkhead limit to the API.

To enforce bulkhead limit to an API

1. Click APIs in the title navigation bar.

2. Select the required API.

3. Click the Policies tab.

4. From the Policy catalog section, expand Transport, and select Enable bulkhead.

5. Provide the following values in the Policy properties section:

   Field	Description
   Maximum concurrent calls	Specify the maximum number of concurrent requests that the API can process, exceeding which the requests are rejected.
   Enable bulkhead for callbacks	Select this option to specify the maximum number of concurrent callbacks for the API. If you select this, the Maximum concurrent callbacks field appears. Note: This setting is applicable only for REST APIs. Hence, this field is not displayed when you perform the bulkhead limit configuration for any other APIs.
   Maximum concurrent callbacks	Specify the maximum number of concurrent callbacks that the API can process, exceeding which the callbacks are rejected. This field appears only when you have selected the Enable bulkhead for callbacks check box.
   Add Retry-After response header	Select this option to include the Retry-after header in the response sent to the client when requests are rejected. This is to keep the client informed about the waiting duration before sending any consecutive requests. Note: This option is to provide an approximate waiting duration before sending any consecutive requests; and it does not guarantee that the requests sent after the specified time are processed. The maximum number of concurrent requests that are processed is purely dependant on the configured bulkhead limit.
   Retry after (value, in seconds)	Specify the duration that the client must wait, after requests are rejected by API Gateway, to send consecutive requests. This field appears only when you have selected the Retry after (value, in seconds) check box.

6. Click Save.

   The bulkhead limit is applied to the API.

Bulkhead feature considerations

This section lists the impact of the bulkhead policy on other features that you must remember when using the policy:

Applicable API types

Bulkhead policy is applicable for REST, SOAP, OData, and GraphQL APIs.

However, you can specify the number of maximum concurrent callbacks only for the REST APIs.

Bulkhead limit configuration for APIs in a mashup

API-level bulkhead limit is not applied to the participating APIs. Instead, the bulkhead limit configured at the mashup API-level takes effect.

Bulkhead limit configured for APIs in cluster

In cluster environments, you can specify the bulkhead limit in each node. API Gateway checks the number of concurrent requests per instance and allows or rejects the requests based on the bulkhead limit configured for an API in the corresponding node.

Overall thread pool violation

When you enable the Bulkhead policy and if the overall thread pool is violated, then the requests exceeding the thread pool count are all rejected, and the Connection timeout message is displayed.

Conditional Routing policy

When the Bulkhead policy is enabled with the Conditional Routing policy, then bulkhead limit configured at API-level for the participating APIs is applicable.

Enable HTTP/HTTPS

This policy specifies the protocol to use for an incoming request to the API on API Gateway. If you have a native API that requires clients to communicate with the server using the HTTP and HTTPS protocols, you can use the Enable HTTP or HTTPS policy. This policy allows you to bridge the transport protocols between the client and API Gateway.

For example, you have a native API that is exposed over HTTPS and an API that receives requests over HTTP. If you want to expose the API to the consumers of API Gateway through HTTP, then you configure the incoming protocol as HTTP.

The table lists the properties that you can specify for this policy:

Set Media Type

This policy specifies the content type for a REST request. If the content type header is missing in a client request sent to an API, API Gateway adds the content type specified here before sending the request to the native API.

The table lists the properties that you can specify for this policy:

As both these properties support variable framework, you can use the available variables to specify the content type and accept header. For details about the variables available in API Gateway, see Variables Available in API Gateway.

Identify and Access

The policies in this stage provide different ways of identifying and authorizing the application, and provide the required access rights for the application. The policies included in this stage are:

• Inbound Auth - Message

• Identify & Authorize

• Custom Extension
  

The Inbound authentication policies are used to authenticate the application by specifying user-based SPN or host-based SPN for a Kerberos token, using the basic credentials for the HTTP basic authentication or through various token assertions or through the XML security actions.

The Identify and Authorize Application policy is used to identify the application, authenticate the request based on policy configured and authorizes it against all applications registered in API Gateway.

Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

Inbound Auth - Message

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.

The table lists the properties that you can specify for this policy:

Identify & Authorize

This policy identifies and validates the authorization of the applications to access the APIs. The applications are identified using a set of identification types such as API key, hostname address, and HTTP basic authentication and so on based on the configuration. API Gateway can identify and authorize the application based on the following Application Lookup condition:

• Registered applications. Identifies the application and validates the identified application against the registered applications. On successful validation, API Gateway allows access to the API. The applications that are associated with the API are called as registered applications.
• Global applications. Identifies the application and validates the identified application against the global applications. On successful validation, API Gateway allows access to the API. All the active applications that are available in API Gateway are called as global applications.
• Global applications and DefaultApplication. Verifies the identity of the application against the global applications and on identification failure, the API Gateway allows access to the API as default application.

The table lists the properties that you can specify for this policy:

OAuth, JWT, and OpenID Configuration

This section describes the Open Authorization (OAuth), JSON Web Token (JWT), and OpenID Connect (OpenID) authentication protocols that you can use to identify and authorize a client application. The application is first identified based on the criteria provided in the strategy configured. A strategy is a way to authenticate the incoming request and provides multiple authentication mechanisms or multiple authorization servers for a single authentication scheme. API Gateway identifies the application and validates the token submitted through the strategy configured in the application.

OAuth Authentication Use Case and Workflow

The Open Authorization is a flexible authorization framework for securing application access to protected resources of APIs. OAuth 2.0 uses access tokens that are presented by client applications (on behalf of the end users) to access the protected resources.

The OAuth authorization framework includes the following terms:

Roles

• Resource Owner (or the End User). This is the holder of the protected resources that the client application accesses. The resource owner is typically a person (usually the end user), but could also be an application.

• Client Application (or the Client). This is the application that is requesting access to protected resources on behalf of the end user.

• Resource Server (or API Gateway). This is the server that stores the protected resources the application is trying to access. API Gateway acts as a resource server.

• Authorization Server. This is the server that acts as an interface between the client application and end user, authenticates the end user, and issues access tokens after proper authorization. API Gateway can be configured to act as an OAuth 2.0 authorization server. You can configure API Gateway for use with a third-party OAuth 2.0 authorization server, such as PingFederate.

Authorization Grant Types

• Authorization Code. This is the grant type used to obtain access tokens (and optionally refresh tokens) and is optimized for confidential clients.
  For public clients, the Authorization Code grant type can be further secured by PKCE mechanism. For details, see Securing Access Token Calls with PKCE.

  Note

  API Gateway supports the confidential client authentication using Authorization headers. The confidential clients have to authenticate using their credentials, the client id and client secret combination. Few points to consider using the Authorization Code grant type:
  

  • If the property watt.server.oauth.token.endpoint.auth=session (the default value) and the confidential client already has a session when it comes to the token endpoint, the access to the endpoint is granted even if there are no credentials in the header.
  • If the property watt.server.oauth.token.endpoint.auth=credentials or if the client does not already have a session, the confidential client must provide the client_secret in the Authorization header.
  • API Gateway does not support the client secret in the body of the request for the Authorization code grant.

  For details about the properties mentioned, see webMethods Integration Server Administrator’s Guide.

• Implicit. This is the grant type used to obtain access tokens and is optimized for public clients. It does not support the issuance of refresh tokens.

• Client Credentials. This is the grant type used to obtain access tokens for client-only authentication.

• Resource Owner Password Credentials. This is the grant type used to obtain access tokens when the resource owner has a trust relationship with the client, and clients are capable of obtaining the resource owner’s credentials.

Clients

• Confidential. A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.

• Public. A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password.

API Gateway can be used as an authorization server and as a resource server.

API Gateway as a Resource Server

When API Gateway acts as a resource server, it hosts the protected resources, and accepts and responds to the client applications’ requests that include an access token. The client application sends the access token in the Authorization request header field using the Bearer authentication scheme. The resource server validates the access token locally or remotely if it cannot validate locally.

If the token is valid and the client application has privileges to access the protected resources, the resource server executes the request. If the access token is invalid, it rejects the request.

API Gateway as an Authorization Server

When API Gateway acts as an authorization server, it receives authorization requests from client applications. The authorization server handles the interactions between the client application, resource server, and resource owner for approval of the request.

As an authorization server API Gateway issues tokens to client applications on behalf of a resource owner for use in authenticating subsequent API calls to the resource server. The resource server hosts the protected resources, and can accept or respond to the protected resource requests using access tokens. If the client application is authorized to access the protected resources, the resource server executes the request. The authorization server retains the information about the access tokens it issues, including the user information. When a client presents an access token to the resource server, the resource server sends the token to the authorization server to ensure that the token is valid and that the requested service is within the scope for which the access token was issued. A scope is the definition of the resources that the client application can access on behalf of a resource owner. If the client application does not have privileges to access the resources, the resource server rejects the request.

Using API Gateway with an External Authorization Server

When API Gateway is the resource server, you must specify an authorization server. As an alternative to using API Gateway as the authorization server, you can use a third-party server as the authorization server. This allows API Gateway to validate access tokens issued by third-party servers and also allow to dynamically create clients in the third-party server.

To use an external authorization server, you must configure your third-party authorization server. This includes, but is not limited to, the following:

• To introspect the token, you should have a JWKS URI or you should create a client account that API Gateway uses to call the authorization server’s introspection endpoint.
  
  Make a note of the client_id and client_secret values. You provide this information as part of defining the external authorization server alias for the API Gateway resource server.
  
  Make a note of the URL for the introspection endpoint. You provide this information as part of defining the external authorization server alias in the API Gateway resource server.
  
  Validation of JWT token of the external authorization server happens in the following ways:

  Local Introspection

  Remote Introspection

  Validation of the JWT token happens within the gateway in the following methods: Using JWKS URI. The external authorization server’s signature is verified by using the public certificate in the JWKS URI. API Gateway’s cache has a key as kid claim and its value is the certificate corresponding to the kid claim. The cache is populated on every restart of API Gateway by invoking the JWKS URI. In the runtime, while validating the token using the local introspection, the kid value from the incoming JWT is fetched and the corresponding certificate is retrieved from the cache and the signature validation happens. Using RSA. The external authorization server’s signature in the JWT is verified by the truststore defined in the local introspection configuration. Using HMAC. If the authorization server uses HMAC algorithm, that means the signature validation of the JWT is performed using a shared key between the authorization server and API Gateway. You must specify the HMAC shared secret when creating the strategy of the application. The HMAC shared secret in the application is used to validate the authorization server’s signature present in JWT.

  Validation of the JWT token happens with the authorization server. Therefore, token caching is not possible in remote introspection. It has an introspection endpoint, which is used to validate the token. In addition, the client id and client secret are used to protect the endpoint, so that anonymous users cannot access the resource. To invoke an endpoint, you require a user; Gateway user is the one you can use to invoke the endpoint.

• Create the required scopes.

• Configure an alias to the authorization server.

Currently, API Gateway, by default, can be used with the following third-party authorization servers, but are not limited to, that are RFC 7662, OAuth 2.0 token introspection compliant:

• Okta

• PingFederate
  

You can also use other third-party authorization servers like Google, keycloak, and so on.

Authorizations for applications created from Developer Portal

When you create applications through Developer Portal, you must specify the required authorization server using the watt.server.oauth.authServer.alias settings in the Administration section of API Gateway.

If API Gateway is the authorization server, then provide local as the value of the watt.server.oauth.authServer.alias setting. Else, provide the name of the corresponding authorization server. For information on extended settings, see Configuring Extended Settings.

Use case 1: OAuth Authentication with API Gateway as a Resource server as well as an Authorization server

This describes the high level workflow for the scenario where API Gateway is a resource server as well as an Authorization server.

1. Configure API Gateway as an internal authorization server. Ensure you configure OAuth scopes while configuring the authorization server. For a complete procedure on configuring API Gateway as an internal authorization server, see Configuring the Internal Authorization Server.

2. Map the scopes.
   For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

3. Enforce the Identify and authorize application policy on the API.
   Ensure to select OAuth2 token. For details of the Identify and authorize application policy see, Identify and Authorize Application.

4. Associate an application with the API.
   You can create a new application or use an existing one. Ensure that the application associated contains the strategy for OAuth authentication. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

5. Activate the API.
   User on invoking the API uses the OAuth identification method to access the protected resource.

6. Get access token through the following URLS:

   invoke/pub.apigateway.oauth2/authorize

   invoke/pub.apigateway.oauth2/getAccessToken

7. Use the access token to invoke the API.

Use case 2: Oauth Authentication with API Gateway as a Resource server and an external Authorization server

This describes the high level workflow for the scenario where API Gateway is the resource server with a third-party authorization server. This is generally used in an environment where there is an existing authorization server, which is used with API Gateway as a resource server.

1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
   For a complete procedure on configuring a provider, see Adding a Provider.

2. Configure an external authorization server.
   Ensure you configure OAuth scopes while configuring the authorization server. For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

3. Map the scopes.
   For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

4. Enforce the Identify and authorize application policy on the API.
   Ensure to select OAuth2 token. For details of the Identify and authorize application policy see, Identify and Authorize Application.

5. Associate an application with the API.
   You can create a new application or use an existing one. Ensure that the associated application contains the strategy for OAuth authentication and contains the client ID. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. If the authorization server supports dynamic client registration, then you can select the option Generate credentials. If the application is already created in authorization server, then provide the respective client id. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

6. Activate API.
   User on invoking the API uses the OAuth identification method to access the protected resource.

7. Get the access token from the authorization server.

8. Use the access token to invoke the API.

For a detailed procedure on using OAuth Authentication with API Gateway as a Resource server and OKTA as an external Authorization server, see Securing APIs using 3rd party OAuth 2 provider in API Gateway.

OAuth Authorization Workflow

The flow of authorization requests and responses between the end user, client application, authorization server, and resource server is as depicted in the following figure:

The OAuth authorization workflow is as follows:

1. The end user logs in, the client application sends the authentication request to the authorization server to obtain an access token.

2. Authorization server validates the request and generates an access token for the client.

3. Client uses this access token to send HTTP requests to API Gateway.

4. API Gateway then performs the following:

   a. Identifies the application using the client ID.

   b. Validates the token locally or remotely if it is not possible locally.

   c. Checks if the requested resource is part of the scopes in the token.

   d. Checks the audience.

   If all the above are validated, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

   Note

   When a Policy violation event is logged in case of expired Oauth2 tokens, the application that is associated turn in to Unknown.

JWT Authentication Use Case and Workflow

JSON Web Token is a JSON-based open standard (RFC 7519) means of representing a set of information to be securely transmitted between two parties. A set of information is the set of claims (claim set) represented by the JWT. A claim set consists of zero or more claims represented by the name-value pairs, where the names are strings and the values are arbitrary JSON values. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, enabling the claims to be digitally signed. JWTs can be signed using a shared secret (with HMAC algorithm), or a public or private key pair using RSA.

API Gateway can generate a JWT token itself or validate the JWT token generated by a trusted third-party server. API Gateway uses the RSA-based JWT to provide stronger integrity protection to JWTs when API Gateway is the issuer of the token. The JSON-based access tokens contain one or more claims. A claim is any piece of information that serves as an unique identifier, and that the token issuer who generated the token has verified. API Gateway extracts the claims from the JWT, identifies the application and then authorizes access to the protected resource.

Use case 1: JWT authentication with API Gateway as a JWT issuer

This describes the high level workflow for the scenario where API Gateway can generate the JSON Web Token itself.

1. Configure API Gateway as an internal authorization server.
   For a complete procedure on configuring API Gateway as an internal authorization server, see Configuring the Internal Authorization Server.

2. Enforce the Identify and authorize application policy on the API. Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

3. Associate an application with the API.
   You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token. For a complete procedure on creating an application with a strategy, see Creating an Application. See Authorizations for applications created from Developer Portal for information on configuring authorization server for the applications created from Developer Portal.

4. Activate the API.
   User on invoking the API uses the JWT identification method to access the protected resource.

5. You get the JWT in one of the following ways (with or without claims), which you can pass as a bearer token to invoke the API.
   The following internal APIs are used for user and application authentication.

   getJsonWebtoken

   Used for user authentication without custom claims

   User authentication happens using the basic auth credentials of any valid IS user.

   • Method: GET

   • URL: http://hostname/rest/pub/apigateway/jwt/getJsonWebToken

   This endpoint can be used to create a JWT without custom claims.

   Used for application authentication with custom claims.

   If you want to add the custom claims in the JWT then you can use this URL with the payload specifying the custom claims.

   The application is authenticated using the application identifiers supplied in the request, such as, APIKey or Username or Host name, and then a token is generated with application id as a subject.

   • Method: POST

   • URL: http://hostname/gateway/security/getJsonWebToken

   This endpoint can be used to create a JWT with custom claims

   • Payload:

     	{
     	"claimsSet": {
     			"customclaim1": "name",
     			"customclaim2":"company name"
     				}
     	}
     

Use case 2: API Gateway with an external JWT issuer

This describes the high level workflow for the scenario where API Gateway accepts JSON Web Token generated by a trusted third-party server.

1. Configure an external authorization server.
   For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

2. Enforce the Identify and authorize application policy on the API.
   Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

3. Associate an application with the API.
   You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token and the external authorization server that would be the JWT issuer. For a complete procedure on creating an application with a strategy, see Creating an Application.

4. Activate the API.
   User on invoking the API uses the JWT identification method to access the protected resource.

5. Pass the JWT as a bearer token to invoke the API.

JWT Authorization Workflow

The flow of authorization requests and responses between the end user, client application, JWT issuer, and resource server is as depicted in the following figure:

The JWT authorization workflow is as follows:

1. The end user logs in, the client application sends an authentication request to API Gateway or to any third-party JWT issuer, to obtain a JWT token.

2. If API Gateway is the JWT issuer, then it validates the user or the application. If the user or application credentials are valid, API Gateway generates the JSON token using a private key that was specified in the JWT configuration, and sends the generated token to the client.
   If the user credentials are invalid, API Gateway returns a specific error response.

3. Client sends the generated JSON token in the HTTP Authorization request header as a Bearer token to access the protected API in API Gateway.

4. API Gateway first identifies the application based on claims from the JWT, then validates the JWT using the public certificate of the issuer (the issuer can be API Gateway or a third-party issuer) and provides access to the protected resources.
   If the validation fails, API Gateway returns a specific error response.

   Note

   • If API Gateway has generated the JSON token, it validates the signature using a public certificate that was specified in the JWT configuration. Else, if the HTTP request is sent from a third-party JWT issuer, API Gateway validates the token using a public certificate or the JWKS URI of the issuer.
   • When a Policy violation event is logged in case of expired JWT tokens, the application is associated as the identified application since the identification happens before the expiry is checked.

OpenID Authentication Use Case and Workflow

OpenID Connect is an open standard and decentralized authentication protocol that extends on the OAuth 2.0 authorization framework. It combines the capability of Open ID in verifying the client’s identity and OAuth’s capability of accessing the client’s resources.

In case of OpenID support in API Gateway, you can use the OpenID authentication protocol to identify and authorize a client application to access the protected resources in one of the following ways (these are explained in detail in the use cases.):

• Use just the access tokens (that is OAuth token) to invoke the protected resources.

• Use the ID token (that gives information about the user) to invoke the protected resources in one of the following ways:

  • Present the ID token to exchange it for an access token and use the access token to access the protected resources.

  • Use the ID token directly to access the protected resources.

API Gateway does not act as a OpenID Connect server but can validate the tokens issued by other OpenID Connect servers.

The following internal API is used for getting an access token for an ID token.

exchangeIDToken

• Method: POST

• URL: http://hostname/gateway/security/exchangeIDToken

• Payload:

  {
  	"gatewayScopes": ["OktaTenant1:inventory"],
  	"idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
  	"expiry": 3000
  }
  

For details on scopes, see Mapping OAuth or OpenID Scopes.

Use case 1: OpenID authentication using OpenID Connect Provider

This describes the high level workflow for using the OpenID authentication protocol to identify and authorize a client application to access the protected resources.

1. Configure a Provider if you are using the Dynamic client registration. Else you can proceed to step 2.
   For a complete procedure on configuring a provider, see Adding a Provider.

2. Configure an external authorization server.
   Ensure you configure the external authorization server with the introspection URL and OAuth scopes. For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

3. Map the scopes.
   For a complete procedure on mapping scopes, see Mapping OAuth or OpenID Scopes.

4. Enforce the Identify and authorize application policy on the API.
   Ensure to select OpenID Connect or JWT as options. For details of the Identify and authorize application policy see, Identify and Authorize Application.

5. Associate an application with the API.
   You can create a new application or use an existing one. Ensure that the application associated contains the strategy for OpenID authentication. While creating a strategy you can associate it with the scopes that are available to be used while using dynamic client registration. For a complete procedure on creating an application with a strategy, see Creating an Application.

6. Activate the API.
   User on invoking the API uses the access token or the ID token provided by the provider to access the protected resource.

7. User can access the protected resources in one of the following ways:

   • The user presents the access token to API Gateway and on validation accesses the protected resource.

   • The user presents the ID token to API Gateway to exchange it for an access token (if the user has configured the OpenID Connect option in step 4). The client then presents the access token to API Gateway and on validation accesses the protected resource.
     
     The following internal API is used for getting an access token for an ID token.
     

     exchangeIDToken
     

     • Method: POST
       

     • URL: http://hostname/gateway/security/exchangeIDToken

     • Payload:

       {
       "gatewayScopes": ["OktaTenant1:inventory"],
       "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
       "expiry": 3000
       }
       

   • The user presents the ID token as a JWT directly to API Gateway (if the user has configured the JWT option in step 4), and on validation accesses the protected resource.

OpenID Authorization Worklow

The OpenID Connect support in API Gateway provides two different ways for a client to access a protected resource depending on whether the provider has provided an access token or an ID token. The workflow diagram depicts both these cases. The first 2 steps are same in both the cases, the arrows in blue depict the flow where an access token is used to access the protected resource, and the arrows in orange depict the flow where an ID token is used to access the protected resource.

OpenID authorization workflow using the OpenID Connect Provider

The flow of authorization requests and responses between the end user, client application, OpenID Connect provider, and resource server is as depicted in the following figure. The client application makes an OpenID call to the OpenID Connect provider and receives an access token or an ID token in the response. It uses these tokens to access the protected resources.

OpenID authorization workflow using the access token provided by the Open ID Connect Provider

1. The client makes an OpenID call to the OpenID connect Provider.

2. The OpenID Connect Provider provides an access token to the client.

3. The client application presents the access token received from the OpenID Connect Provider to send HTTP requests to API Gateway.

4. API Gateway then performs the following:

   a. Identifies the application using the client ID.

   b. Validates the token locally or remotely if it is not possible locally.

   c. Checks if the requested resource is part of the scopes in the token.

   d. Checks the audience.

   API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

OpenID authorization workflow using the ID token provided by the Open ID Connect Provider

1. The client makes an OpenID call to the OpenID Connect Provider.

2. The OpenID Connect Provider provides an ID token to the client.

3. The client application presents the ID token received from the OpenID Connect Provider to API Gateway.

4. API Gateway validates the ID token and returns an access token to the client application.

   The following internal API is used for getting an access token for an ID token.

   exchangeIDToken

   • Method: POST

   • URL: http://hostname/gateway/security/exchangeIDToken

   • Payload:

     {
     "gatewayScopes": ["OktaTenant1:inventory"],
     "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
     "expiry": 3000
     }
     

   For details on mapping scopes, see Mapping OAuth or OpenID Scopes.

5. The client then uses this access token to send HTTP requests to API Gateway.

6. API Gateway then performs the following:

   a. Identifies the application using the client ID.

   b. Validates the token locally or remotely if it is not possible locally.

   c. Checks if the requested resource is part of the scopes in the token.

   d. Checks the audience.

   API Gateway provides access to the protected resource if all the validations are done. If the access token is valid, API Gateway provides access to the protected resource. If the access token is expired, authorization server returns a specific error response. The client application can then use Refresh Token to request a new access token. The Authorization Server returns a new access token that can be used to access the protected resource.

Secure API using OAuth2 with refresh token workflow

When using the authorization code grant type to get the access token, you need to get the permission from the resource owners at least for the first time. In the subsequent attempts to get the access token, if you do not want to get the permission from the resource owners, then you can use the refresh token.

This use case explains how to secure the API using OAuth2 authentication strategy. It also explains the refresh token workflow in detail.

Configuring OAuth2 Authentication with Refresh Token

This use case explains how to secure the API using OAuth2 authentication strategy with authorization_code and refresh_token grant types.

The use case starts when you create an API and ends when you create an application strategy with OAuth2 authentication scheme.

To configure OAuth2 Authentication with Refresh Token

1. Create an API. For details about creating an API, see Creating an Rest API.

   

2. Enable the OAuth2 token identification type in the Identify & Authorize policy. For details about Identify & Authorize policy, see Identify & Authorize.

   

3. Create OAuth scope in the local authorization server.

   

4. Map the OAuth scope to the API scope. For details about mapping OAuth scope, see Mapping OAuth or OpenID Scopes.

   

5. Create an application with OAuth2 authentication strategy.

   

   a. Create a new application.
   

   For details about creating an application, see Creating an Application.
   

   b. Associate the application with the API that you have created.
   

   c. Click the Authentication tab to create strategy with OAuth2 authentication.
   

   

   d. Select the Authentication schemes as OAUTH2.
   

   e. Specify the Authentication server as local.
   

   f. Enable the Generate credentials toggle button to generate the client dynamically in the authorization server and provide the following information:

   i. Select the Application Type as Confidential. A confidential client is an application that can keep a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.

   ii. Select the application profile from the Application profile drop-down menu. For example, web.

   iii. Specify the duration in seconds for which the access token is active in the Token lifetime (seconds).

   iv. Specify the number of times you can use the refresh token in the Token refresh limit to get a new access token.

   Note

   To use refresh token unlimitedly, specify the limit as -1.

   v. Specify the URIs that the authorization server can use to redirect the resource owner’s browser during the grant process. You can add multiple URIs by clicking +Add.

   vi. Specify the grant type to be used to generate the credentials. For this specific use case, we have selected authorization code, client_credentials, and refresh_token, which are dynamically populated from the authorization server.

   Note

   Make sure you have selected refresh_token grant_type, if you want to get the refresh tokens.

   vii. Select the scopes that are to be mapped for the authentication strategy.

   viii. Click Add to save the strategy.

   ix. Click Save to save the application.

Refresh Token Process Flow

This use case explains the following workflow:

• How to get the access token with resource owner permission?

• How to get the access token without resource owner permission using refresh token in the subsequent attempts?

How to get the access token with resource owner permission?

This use case starts when you get the authorization code and ends when you access then API.

To get access token using authorization code grant type (With resource owner permission)

1. Get authorization code.

   a. Click the http(s)://hostname/invoke/pub.apigateway.oauth2/authorize?response_type=code&redirect_uri=<redirectURI>&client_id=<Client ID>.

   Note

   Make sure you have replaced the <redirectURI > and <ClientID > in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

   

   b. Click the Approve button.

   c. Enter the credentials of your API Gateway instance.
   

   You will be re-directed to the redirect URI as per to the configuration. The below screenshot is just a sample, you will be redirected to a different URL based on your configuration and so the screenshot varies accordingly . If the given redirect URI is not a valid web page, you may get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

   

   d. Make a note of the authorization code that is displayed in the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code= field of the URL.

2. Get Access Token.

   a. Invoke the access token endpoint.
   

   Request: POST http(s):// hostname/invoke/pub.apigateway.oauth2/getAccessToken
   

   In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.
   

   Sample request body

   {
              "redirect_uri":"http://test.com",
              "scope":"email",
              "grant_type":"authorization_code", 
              "code":"4b4b16c68f1c4b6fa7f26e0cb00b5daa"
   }
   

   Note

   You must replace the redirect_URI, scope, and code with appropriate values. For the code field value, make sure you use the authorization code that you have noted down in the previous step.

   Sample response body

   {
           "scope": "TestRefreshtoken",
           "access_token": "c92b6227a19c46f1a6545bf370bb6ee6e30ff87957ef4b1aaa9577f7e86e4bd7",
           "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947",
           "token_type": "Bearer",
           "expires_in": 3600
   }
   

3. Access API using the REST API client.
   In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step.

How to get the access token without resource owner permission using refresh token in the subsequent attempts?

This use case starts when you get the authorization code and ends when you access then API.

To get access token using refresh token (Without resource owner permission)

When the access token expires and if you need to access the same API, you need to get another access token. If you have refresh token, you can get a new access token without getting the permission from the resource owner.

1. Invoke the access token endpoint.
   

   Request: POST http(s)://hostname/invoke/pub.oauth/refreshAccessToken
   

   In the Authorization tab, select the authorization type as Basic Auth. Provide the client ID as username and client secret as password. You can get the client ID and client secret in the Authentication tab of the Application screen.
   

   Sample request body

   {
   "grant_type":"refresh_token", 
   "refresh_token":"f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947"
   }
   

   Note

   Make sure you have replaced the refresh token that you got from the Step 2 using How to get the access token with resource owner permission? use case.

   Sample response body

   {
   "grant_type": "refresh_token",
   "refresh_token": "f78dd4fc5b8d4d799cf066427e828e26ce7e3723e4334416a7b9cd8a274e6947",
   "scope": "TestRefreshtoken ",
   "access_token": "c102bcaebecf451ca705bf54d26fae732ea9790a0ff64a87a010b3875b4b8da2",
   "token_type": "Bearer",
   "expires_in": 3600
   }
   

2. Access API using the REST API client.
   In the Authorization tab, select the authorization type as Bearer Token and provide the access token that you get from the response payload of the previous step. .

Securing Access Token Calls with PKCE

PKCE (Proof Key for Code Exchange - RFC 7636) is supported to enhance the security of the OAuth 2.0 authorization code grant. PKCE is applicable only for public OAuth clients that use the authorization code grant, which are vulnerable to the Man In The Middle (MITM) attack. In such cases, the client application should enforce PKCE by giving proof to the authorization server that the authorization code belongs to the client application. Only then the authorization server issues an access token for the client application. For more information about PKCE specification, see https://datatracker.ietf.org/doc/html/rfc7636.

The PKCE flow works with these parameters:

• Code Verifier. The code verifier should be a high-entropy cryptographic random string with a minimum of 43 characters and a maximum of 128 characters.
• Code Challenge. The code challenge is created by SHA256 hashing the code verifier and then applying base64 URL encoding of the resulting hash. If the client cannot do the hashing and encoding transformation, it can use the code challenge method as plain where the code challenge is same as code verifier
• Code Challenge Method. This is an optional parameter. If the client uses SHA256 hashing, the code challenge method value must be S256. If no hashing is done, then the code challenge method value must be plain. When code challenge method is plain , the code challenge value is the same as the code verifier. If the code challenge method value is not passed in the client request, then plain would be considered as default value.

When you enforce PKCE, the public OAuth client creates a secret called the code verifier. The client also generates the code challenge for the corresponding code verifier. The PKCE flow is explained as follows:

1. When the client invokes the authorization endpoint (http(s)://hostname/invoke/pub.apigateway.oauth2/authorize) on the authorization server, the client sends the code challenge and code challenge method to the authorization server.

2. The authorization server validates the request. If the request is valid, the authorization server generates the authorization code and saves the supplied code challenge and code challenge method in the OAuthPKCE cache.

3. The client invokes the token endpoint (http(s)://hostname/invoke/pub.apigateway.oauth2/getAcessToken) on authorization server to exchange the authorization code for an access token. The client also supplies the additional input parameter code verifier.

4. Authorization server applies the code challenge method to the supplied code verifier and generates the code challenge. If the generated code challenge value matches with the code challenge value supplied to the authorization endpoint service (in step 1), then the token endpoint service issues the access token to the client.

The following diagram summarizes the PKCE flow:

In API Gateway, you can enforce PKCE at the following levels:

The flow chart explains when the API Gateway enforce and does not enforce the PKCE.

How do I enforce PKCE globally?

This section explains how to enforce PKCE globally in the local authorization server. When you enforce PKCE at global level, then it is applied for all the public OAuth2.0 clients of local authorization server.

To enforce the PKCE at global level

1. Expand the menu icon, in the title bar, and select Administration.

2. Select Security > JWT/OAuth/OpenID.
   The Authorization servers section displays a list of available internal and external authorization servers.

   

3. In the Internal authorization servers section, click local .

4. Expand the OAuth configurationsection, select the Enforce PKCE checkbox.

5. Click the Update button.
   Once you enforce PKCE, you get access token only on successful validation of code verifier.

How do I enforce PKCE at application level?

This section explains how to enforce PKCE at an application level in the local authorization server. When you enforce PKCE at an application level, it is enforced only for that application.

To enforce PKCE at an application level

1. Create OAuth scope in the local authorization server.

   

2. Create a new application or update an existing application with OAuth2 authentication strategy.

   For details about creating an application, see Creating an Application.

3. Open the application and click the Authentication to create a strategy with OAuth2 authentication.

   

   Make sure you have selected the following mandatory fields for this use case:

   • Select the Authentication schemes as OAUTH2.
   • Specify the Authentication server as local.
   • Select the Application Type as Public.
   • Specify the grant type to be used to generate the credentials. For this specific use case, you must select authorization_code, which is dynamically populated from the authorization server.
   • In the Enforce PKCE section, select one of the following:

   PKCE Settings	Description
   Enforced	If you select this option, the local authorization server enforces PKCE even if the PKCE is not enforced at the global level.
   Not Enforced	If you select this option, the local authorization server does not enforce PKCE even if the PKCE is enforced at the global level.
   Use Global Setting (Enforced)	If you select this option, the local authorization server enforces PKCE based on the PKCE setting at the global level. Note: The value inside the parenthesis depicts whether you have enforced the PKCE at the global level or not. For details about how to enforce PKCE at global level, see How do I enforce PKCE globally?

   Note
   The application level PKCE enforcement takes precedence over the global level PKCE enforcement.
   • Specify the postman https://oauth.pstmn.io/v1/callback URL as redirect URI.
   • Specify the OAuth scope that you have created for the local authorization server in Step 1.

4. Click Add to save the strategy.

5. Click Save to update and save the application.
   Once you enforce PKCE, you get access token only on successful validation of code verifier.

How do I secure the access token with Authorization Code (With PKCE) grant type using postman?

This section explains how to secure the get access token calls using postman.

To test the access token

1. In the Postman, under the Authorization tab, select the authorization type as OAuth2.0 from the TYPE drop-down menu.

   

   a. In the Configure New Token section, select the grant type as Authorization Code (With PKCE).

   b. Type the redirect URL as https://oauth.pstmn.io/v1/callback in theCallback URLtext box.

   c. Select the Authorize using browser check box.

   d. Type the authorization URL as http(s)://hostname/invoke/pub.apigateway.oauth2/authorize in the Auth URL text box.

   e. Type the http()://hostname/invoke/pub.apigateway.oauth2/getAccessToken in the Access Token URL text box.

   f. Type the client ID and client secret in the Client ID and Client Secret text boxes respectively.

   Note

   You can get the client ID and client secret from the Authentication tab of the Application screen.

   g. Select the hashing method used to generate the code challenge from the Code Challenge Method drop down menu.

   h. Specify the OAuth scope that you have created for the local authorization server in Step 1 in the Scope text box.

   i. Select the client authentication as Send client credentials in body.

   j. Click the Get New Access Token button.

   

   k. Click the Approve button.
   TheMANAGE ACCESS TOKENS pop-up window displays the access token.

   

How do I secure the access token by directly calling API Gateway’s REST APIs?

This section explains how to secure the get access token calls when you enforce the PKCE using REST APIs.

Before you begin

Ensure that you have:

• generated Code Challenge and Code Verifier. For details about how to generate code challenge and code verifier, see How do I generate code verifier and code challenge?

• enforced PKCE at global level at global level or application level.

To secure the access token

1. Get authorization code.

   a. Call the authorize endpoint using a REST client.
   http(s)://hostname/invoke/pub.apigateway.oauth2/authorize? response_type=code&redirect_uri=&client_id=&code_challenge=&code_challenge_method=S256

   Note

   Make sure you have replaced the redirectURI , ClientID, and Code_Challenge in the above mentioned URL. You can get the redirect URI and client ID from the Authentication tab of the Application screen.

   

   b. Click the Approve button

   c. Provide the credentials of API Gateway user to approve the request.

   You are re-directed to the redirect URI as per the configuration in the application strategy. The screenshot below is just a sample, you are redirected to a different URL based on your configuration, so the screenshot varies accordingly. If the given redirect URI is not a valid web page, you might get a Page not found error, which is fine, because we get the authorization code value from the browser URL.

   

   d. Make a note of the authorization code.

   Note

   If the redirect URL screen is not able to display the authorization code, then you can take it from the address bar of the browser. As highlighted in the above image’s URL, you can see the authorization code in the code=field of the URL.

   e. Click Save to save the application.

2. Get access token.

   a. Invoke the access token endpoint using a REST client.
   Request: POST http(s)://hostname/invoke/pub.apigateway.oauth2/getAccessToken.

   You need to pass authorization header using basic authentication with the client ID as username and client secret as the password. You can get the client ID and client secret in the Authentication tab of the Application screen in the API Gateway UI.

   Sample request body

   {
   "redirect_uri":"http://test.com",
   "scope":"email",
   "grant_type":"authorization_code",
   "code":"0025abe9f96d4901b61340344c29a576",
   "code_verifier":"a4793f15479a4c5697f93b44d055ab6cbd16be50400a4591892f914b1a256da8",
   "client_id":"374b1fae-4405-411b-85a0-6e1ab90923ba"
   }
   

   Note

   You must replace the redirect_URI, scope, code, and code_verifier with appropriate values. For the code field, make sure you use the authorization code you noted down in the step 1.d.

   Sample response body

   {
   "access_token": "b5b33bc9c57945f388010f8caf5fe9b6b14abef468d346e68e0cd374c0df60d7",
   "token_type": "Bearer",
   "expires_in": 3600
   }
   

How do I enforce PKCE selectively for each access token call?

You can enforce PKCE specific to each GET access token call. To perform this use case, you must clear the Enforce PKCE check box in the Administration > Security > JWT/OAuth/OpenID screen. When you disable the PKCE global option, by default PKCE is not verified. But if you send the authorize request with the code challenge and code challenge method parameters, you get an access token with PKCE verification.

How do I generate code verifier and code challenge?

To generate code verifier and code challenge

1. You can generate code verifier and code challenge using the Postman tool. You can select the code challenge method and postman automatically generates the code verifier for you. For more details, see How do I secure the access token with Authorization Code(With PKCE) grant type using postman?

   

2. Additionally, If you want to create a code verifier and code challenge on your own, please follow the instructions available in the PKCE RFC document RFC 7636, particularly sections 4.1 and 4.2

Inbound Auth - Message

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.

The table lists the properties that you can specify for this policy:

Authorize User

This policy authorizes incoming requests against a list of users, a list of groups, or users who belong to LDAP groups registered in API Gateway.

Use this policy in conjunction with an authentication policy (for example, Require HTTP Basic Authentication, Require WSS Username Token).

The table lists the parameters of this policy and how they are applied to authorize the incoming requests.

Parameter	Description
List of Users	Authorizes applications against a list of users registered in API Gateway. Type a search string, select a user, and click to add. You can add more users. Click to delete the user added.
List of Groups	Authorizes applications against a list of groups registered in API Gateway. Type a search string, select a group, and click to add. You can add more groups. Click to delete the group added.
List of Teams	Authorizes applications against a list of teams registered in API Gateway. Type a search string, select a team, and click to add. You can add one or more teams. Click to delete a team.

Request Processing

These policies are used to specify how the request message from an application has to be transformed or pre-processed and configure the masking criteria for the data to be masked before it is submitted to the native API. This is required to protect the data and accommodate differences between the message content that an application is capable of submitting and the message content that a native API expects. The policies included in this stage are:

• Validate API Specification

• Request Transformation

• Data Masking

• Custom Extension

  Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

Validate API Specification

This policy validates the incoming request against API’s various specifications such as schema, query parameters, path parameters, content-types, and HTTP Headers referenced in their corresponding formats as follows:

• The schema is available as part of the API definition. The schema for SOAP API are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.

• The query parameters, path parameters and content- types are available as part of the API definition.

• The HTTP Headers are specified in the Validate API Specification policy page.
  

The request sent to the API by an application must conform with the structure or format expected by the API. The incoming requests are validated against the API specifications in this policy to conform to the structure or format expected by the API.

Various API specifications validated are:

• Schema:

  The incoming requests are validated against the schema provided in the API definition. The schema defines the elements and attributes and specifies the data types of these elements to ensure that only appropriate data is allowed through to the API.

  For a REST API, the schema can be added inline or uploaded in the Technical Information section on the API Details page. The validation depends on the Content-type header in the request or Accept header in the response and the corresponding schema validation would be executed.

  The schema type for validation is selected based on:

  • The Content-Type header when the policy is added in the Request processing stage.
  • The Accept header when the policy is added in the Response processing stage.
    
    

  If the header or payload is missing the schema validation is skipped.

  The table lists the default Content type/Accept header and schema validation type mapping.

  Content-type/Accept	Schema validation type
  application/json application/json/badgerfish	JSON schema
  application/xml text/xml text/html	XML schema
  text/plain	Regex schema

  For a SOAP API, the WSDL and the referenced schema must be provided in a zip format. The JSON schema validation is supported for the operations that are exposed as REST.

  Note

  If schema mapping is not found for a content-type of the request in the API, the behavior is as follows:

  • If schema mapping is not available in a REST API or SOAP-to-REST transformed API, the validation is skipped.
  • If application/json is mapped to XML schema in the API definition, then the JSON content in the request is validated against XML schema to provide a backward compatibility support for APIs migrated from the 10.1 version.
  • If only XML schema mappings exist for any of the content-types, the payload is converted into XML and validated against all the XML schemas. If the payload is valid against one of the schemas, the validation is successful.
  • If the payload is not XML convertible, the validation is not performed and the request is allowed to reach the native API.

• Schema validation for GraphQL API:

  The incoming query or mutation payloads are validated against the GraphQL schema type system.

• Query Parameters:

  This is applicable only for a REST API. The incoming requests are validated against the query parameters specified in the API definition.

• Path Parameters:

  This is applicable only for a REST API. The incoming requests are validated against the path parameters specified in the API definition.

• Content-types:

  This is not applicable to a GraphQL API. The incoming requests are validated against the content-types specified in the API definition.

  Note

  When Content-type validation is selected for a SOAP API, the validation fails in case of SOAP to REST scenarios and displays an error with 500 status code instead of 400 as displayed in the other scenarios.

  When we have Content type validation selected for SOAP API, when SOAP TO REST scenarios, this validation does not happen, that is, an error displays with 500 status code and not 400 as the other scenarios.

• HTTP Headers:

  This is not applicable to a GraphQL API. The incoming requests are validated against the HTTP Headers specified in this policy to conform to the HTTP headers expected by the API.
  

The runtime invocations that fail the specification validation are considered as policy violations. You can view such policy violation events in the dashboard.

The table lists the API specification properties, you can specify for this policy, to be validated:

Request Transformation

This policy enables you to configure several transformations on the request messages from clients into a format required by the native API before it is submitted to the native API.

The transformations include Header, Query Parameter, Path Parameter transformation, HTTP Method transformation, Payload transformation, and Advanced transformation. You can configure conditions according to which the transformations are executed.

The table lists the properties that you can specify for this policy:

Parameter	Description
Condition	Conditions are used to specify when the policy has to be executed. You can add multiple conditions with logical operators. Available values are: AND. API Gateway transforms the requests that comply with all the configured conditions. OR. This is selected by default. API Gateway transforms the requests that comply with any one configured condition. Click Add Condition and provide the following information and click . Variable: Specifies the variable type with a syntax. Operator: Specifies the operator to use to relate variable and the value provided. You can select one of the following: Equals Equals ignore case Not equals Not equals ignore case Contains Not Contains Exists Not Exists Range Greater Than Less Than Value: Specifies a plain value or value with a syntax. For details about the variables available in API Gateway, see Variables available in API Gateway.
Transformation Configuration. Specifies various transformations to be configured.
Header/Query/Path Transformation for REST API and Header Transformation for SOAP API	Specifies the Header, Query or path transformation to be configured for incoming requests. You can add or modify header, query or path transformation parameters by providing the following information: Variable. Specifies the variable type with a syntax. Value: Specifies a plain value or value with a syntax. You can add multiple variables and corresponding values by clicking . You can remove any header, query, or path transformation parameters by typing the plain value or value with a syntax. Note: Software AG recommends you not to modify the headers ${request.headers.Content-Length} and ${request.headers.Content-Encoding} as API Gateway adds the right values for these headers before sending the response back to client. For details about the variables available in API Gateway, see Variables available in API Gateway. Note: Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure that you do payload transformation. For example, if you change the content-type header from application/xml to application/json, you must also change the respective payload from application/xml to application/json.
Method transformation for REST API	Specifies the method transformation to be configured for incoming requests. Select any of the HTTP Method listed: GET POST PUT DELETE HEAD CUSTOM Note: When CUSTOM is selected, the HTTP method in incoming request is sent to the native service. When other methods are selected, the selected method is used in the request sent to the native service.   Note: Only Method Transformation happens when configured, but you have to take care of adding payload during transformations involving method change like GET to POST, and so on.
Payload Transformation	Specifies the payload transformation to be configured for incoming requests. Provide the following information: Payload Type. Specifies the content-type of payload, to which you want to transform. The Payload field renders the respective payload editor based on the selected content-type. Payload. Specifies the payload transformation that needs to be applied for the incoming requests As this property supports variable framework, you can make use of the available variables to transform the request messages. For example, consider the native API accepting two integer values value1 and value2, and you want to pass these two values from API Gateway to the native API, you can configure the payload field as follows: {"value1" : 12,"value2" : 34} You can also configure the payload field using one or more variables by using variable framework. Let us see another syntax. For example, for the same native API seen in the previous example, if your client sends both the values through headers val1 and val2, and you want to add it to payload for the native API to recognize the input, you can do so by configuring the payload field as follows: {"value1" :${request.headers.val1},"value2" :${request.headers.val2}} For details about the variables available in API Gateway, see Variables available in API Gateway. Note: If your payload content-type is different from the incoming payload's content-type, you need to transform the content-type of the header using Header Transformation. Click + Add xslt document to add an xslt document and provide the following information: XSLT file. Specifies the XSLT file used to transform the request messages as required. Click Browse to browse and select a file. Feature Name. Specifies the name of the XSLT feature. Feature value. Specifies the value of the XSLT feature. You can add more XSLT features and xslt documents by clicking . Note:API Gateway supports XSLT 1.0 and XSLT 2.0. Click + Add xslt transformation alias and provide the following information: XSLT Transformation alias. Specifies the XSLT transformation alias When the incoming request is in JSON, you can use a XSLT file similar to the below sample: <?xml version="1.0" ?> <xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml"/> <xsl:template match="/" > <xsl:element name="fakeroot"> <xsl:element name="fakenode"> <!-- Apply your transformation rules based on the request from the Client--> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet> When the incoming request is in XML, you can use a XSLT file similar to the below sample: <?xml version="1.0" ?> <xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <xsl:output method="xml"/> <xsl:template match="/"> <xsl:element name="soapenv:Envelope"> <xsl:element name="soapenv:Body"> <!-- Apply your transformation rules based on the request from the Client--> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
Transformation Metadata. Specifies the metadata for transformation of the incoming requests. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${request.payload.xpath} For example: ${request.payload.xpath[//ns:emp/ns:empName]}
Namespace	Specifies the namespace information to be configured for transformation. Provide the following information: Namespace Prefix. The namespace prefix of the payload expression to be validated. For example, specify the namespace prefix as SOAP_ENV. Namespace URI. The namespace URI of the payload expression to be validated. For example, specify the namespace URI as http://schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace: http://schemas.xmlsoap.org/soap/envelope/. Note: You can add multiple namespace prefix and URI by clicking .

Data Masking

Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

This policy is used to mask sensitive data at the application level. At the application level you must have an Identify and Access policy configured to identify the application for which the masking is applied. If no application is specified then it will be applied for all the other requests. Fields can be masked or filtered in the request messages received. You can configure the masking criteria as required for the XPath, JSONPath, and Regex expressions based on the content-type. This policy can also be applied at the API scope level.

The table lists the content-type and masking criteria mapping.

The table lists the masking criteria properties that you can configure to mask the data in the request messages received:

Routing

The policies in this stage enforce routing of requests to target APIs based on the rules you can define to route the requests and manage their respective redirections according to the initial request path. The policies included in this stage are:

• Straight Through Routing

• Custom HTTP Header

• Outbound Auth - Transport

• Content-based Routing

• Conditional Routing

• Dynamic Routing

• Load Balancer Routing

• Outbound Auth - Message

• Custom Extension

  Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

In cases where the internal server is protected by a firewall, the endpoint in the routing policy that is applied should be configured as apigateway://registrationPort-aliasname/relative path of the API. Here the registration port alias name is the alias name configured for the external registration port to communicate with the internal port.

Straight Through Routing

When you select the Straight Through routing protocol, the API routes the requests directly to the native service endpoint you specify. If your entry protocol is HTTP or HTTPS, you can select the Straight Through routing policy.

The table lists the properties that you can specify for this policy:

Custom HTTP Header

You can use this policy to route requests based on the custom HTTP headers specified for the outgoing message to the native service.

The table lists the properties that you can specify for this policy:

You can add multiple entries for the Header key-value pair by clicking .

Outbound Auth - Transport

When the native API is protected and expects the authentication credentials to be passed through transport headers, you can use this policy to provide the credentials that will be added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as Basic Authentication, Kerberos, NTLM, and OAuth, at the transport-level.

The table lists the properties that you can specify for this policy:

When you configure an API with an inbound authentication policy, and a client sends a request with credentials, API Gateway uses the credentials for the inbound authentication. When sending the request to native server, API Gateway removes the already authenticated credentials when no outbound authentication policy is configured.

If as an API provider you want to use the same credentials for authentication at both API Gateway and native server, you should configure the outbound authentication policy to pass the incoming credentials to the native service. If you do not configure an outbound authentication policy, API Gateway removes the incoming credentials, as it is meant for API Gateway authentication only.

However, when both the inbound authentication policy and outbound authentication policy are not configured, API Gateway just acts as a proxy and forwards the credentials to the native service. Since the credentials are not meant for API Gateway (as no inbound auth policy is configured), API Gateway forwards the credentials to native service (unless there are different settings configured in outbound authentication policy, for example, custom credentials or Anonymous).

Content-based Routing

If you have a native API that is hosted at two or more endpoints, you can use the Content-based routing protocol to route specific types of messages to specific endpoints. You can route messages to different endpoints based on specific values that appear in the request message. You might use this capability, for example, to determine which operation the consuming application has requested, and route requests for complex operations to an endpoint on a fast machine. For example, if your entry protocol is HTTP or HTTPS, you can select the Content-based routing. The requests are routed according to the content-based routing rules you create. You may specify how to authenticate requests.

The table lists the properties that you can specify for this policy:

Conditional Routing

If you have a native API that is hosted at two or more endpoints, you can use the condition-based protocol to route specific types of messages to specific endpoints. The requests are routed according to the condition-based routing rules you create. For example, if your entry protocol is HTTP or HTTPS, you can select conditional routing specifying HTTP or HTTPS. A routing rule specifies where requests should be routed to, and the criteria to use to route. You may also specify how to authenticate requests.

The following table provides the existing options of routing till API Gateway version 10.5 and their corresponding variable syntax to choose the same option in API Gateway version 10.11.

The table lists the properties that you can specify for this policy:

Dynamic Routing

This policy enables API Gateway to support dynamic routing of virtual aliases based on policy configuration. The configured policies are enforced on the request sent to an API and these requests are forwarded to the dynamic endpoint based on specific criteria that you specify.

The table lists the properties that you can specify for this policy:

Load Balancer Routing

If you have an API that is hosted at two or more endpoints, you can use the load balancing option to distribute requests among the endpoints. Requests are distributed across multiple endpoints. The requests are routed based on the round-robin execution strategy. The load for a service is balanced by directing requests to two or more services in a pool, until the optimum level is achieved. The application routes requests to services in the pool sequentially, starting from the first to the last service without considering the individual performance of the services. After the requests have been forwarded to all the services in the pool, the first service is chosen for the next loop of forwarding.

If the entry protocol is HTTP or HTTPS, you can select the Load Balancer routing.

The table lists the properties that you can specify for this policy:

Failover behavior during load balancing

When an endpoint that is configured in Load balancer routing returns any of these exceptions - ConnectException, MalformedURLException, NoRouteToHostException, ProtocolException, SocketTimeoutException, UnknownHostException, UnknownServiceException - then API Gateway treats the endpoint to be inactive and routes to the next endpoint as per the round-robin strategy. In this case, the endpoint is suspended for the duration mentioned in the suspendDuration parameter (default is 30s), which indicates the duration to suspend the endpoint without repeatedly trying to reach it.
In this way API Gateway tries to invoke all the endpoints configured in the load balance routing. If all endpoints return downtime error, API Gateway returns a Service is down error.
If an endpoint returns an exception other than the Downtime exception then that exception is sent to the client and the remaining endpoints are not invoked.
You can control the behavior of considering Downtime exceptions only for load balancing through the extended property pg.lb.failoverOnDowntimeErrorOnly, which you can set through Administration > General > Extended settings page. The default value of this property is true. If you set the value to false all failures from the endpoint are treated as downtime and load balancing takes place.

Outbound Auth - Message

When the native API is protected and expects the authentication credentials to be passed through payload message, you can use this policy to provide the credentials that is added to the request and sent to the native API. API Gateway supports a wide range of authentication schemes, such as WSS Username, SAML, and Kerberos, in addition to signing and encryption at the message-level.

The table lists the properties that you can specify for this policy:

When you configure an API with an inbound authentication policy, and a client sends a request with credentials, API Gateway uses the credentials for the inbound authentication. When sending the request to native server, API Gateway removes the already authenticated credentials when no outbound authentication policy is configured.

If as an API provider you want to use the same credentials for authentication at both API Gateway and native server, you should configure the outbound authentication policy to pass the incoming credentials to the native service. If you do not configure an outbound authentication policy, API Gateway removes the incoming credentials, as it is meant for API Gateway authentication only.

However, when both the inbound authentication policy and outbound authentication policy are not configured, API Gateway just acts as a proxy and forwards the credentials to the native service. Since the credentials are not meant for API Gateway (as no inbound auth policy is configured), API Gateway forwards the credentials to native service (unless there are different settings configured in outbound authentication policy, for example, custom credentials or Anonymous).

Traffic Monitoring

The policies in this stage provide ways to enable logging request and response payload, enable monitoring run-time performance conditions for APIs and applications, enforce limits for the number of service invocations during a specified time interval and send alerts to a specified destination when the performance conditions are violated, and enable caching of the results of API invocations depending on the caching criteria defined. The policies included in this stage are:

• Log Invocation

• Traffic Optimization

• Service Result Cache

• Monitor Performance

• Monitor SLA

Log Invocation

This policy enables logging requests or responses to a specified destination. This action also logs other information about the requests or responses, such as the API name, operation name, the Integration Server user, a timestamp, and the response time.

The table lists the properties that you can specify for this policy:

Traffic Optimization

This policy limits the number of API invocations during a specified time interval, and sends alerts to a specified destination when the performance conditions are violated. You can use this policy to avoid overloading the back-end services and their infrastructure, to limit specific clients in terms of resource usage, and so on.

The Traffic optimization policy generates two types of events when the specified limit is breached:

• Policy violation event. Indicates the violations that occur for an API. If there are 100 violations, then 100 policy violation events are generated.
• Monitor event. Controlled by the alert frequency configuration specified in the policy.

The table lists the properties that you can specify for this policy:

Traffic Optimization Policy Enforcement Scenarios

You can enforce more than one Traffic Optimization policy for an API based on your requirement. This section lists a sample requirement scenario and the possible solution:

How do I?

• Allow 1000 invocation per minute for each registered consumer application.
• Allow 500 invocation for 15 minutes for all non-registered consumer applications.

Possible solution:

Create two Traffic Optimization policies with the following specifications

• Policy 1
  • value. 1000.
  • Alert Interval. 1.
  • Alert Frequency. minute.
  • Consumer Applications. Each registered consumer.
• Policy 2
  • value. 500.
  • Alert Interval. 15.
  • Alert Frequency. minute.
  • Consumer Applications. All non-registered consumers.

Service Result Cache

This policy enables caching of the results of API invocations depending on the caching criteria defined. You can define the elements for which the API responses are to be cached based on the criteria such as HTTP Header, XPath, Query parameters, and so on. You can also limit the values stored in the cache using an allowlist. For the elements that are stored in the cache, you can specify other parameters such as Time to Live and Maximum Response Payload Size.

Caching the results of an API request increases the throughput of the API call and improves the scalability of the API.

The cache criteria applicable for a SOAP-based API request are HTTP Header and XPATH. The cache criteria applicable for a REST-based API request are HTTP Header and Query parameters. The caching works only for GET methods for REST APIs.

The table lists the properties that you can specify for this policy:

Parameter	Description
Cache Criteria	Specifies the criteria that API Gateway uses to determine the request component, that is, the actual payload based on which the results of the API invocation are cached.
HTTP Header	Uses the HTTP header in the API request. You can use this criterion for APIs that accept payloads only in HTTP format. Header Name. Specifies the HTTP header name. Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match with those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking . Note: If this field is empty, all the values that satisfy the criterion are cached.
Query Parameters	You can use this criterion for REST-based API requests. Specifies the names and values of the query parameters to filter the incoming requests and cache the results based on the names and values specified. Parameter Name. Specifies the parameter name. Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking .
XPath	You can use this criterion for SOAP-based API requests whose payload is a SOAP envelope. Uses the XPath expression in the API request. Name Space. Specifies the namespace of the XPath expression. Prefix. Specifies the prefix for the namespace. URI. Specifies the namespace URI. You can add multiple entries by clicking . XPath Expression. Specifies the XPath expression in the API request. Cache responses only for these values. API Gateway caches the API responses only for requests whose cache criteria match those set for the action, and whose criteria evaluation results in any one of the values in this list. You can add multiple entries by clicking . Note: If this field is empty, all the values that satisfy the criteria are cached.
Time to Live (e.g., 5d 4h 1m)	Specifies the lifespan of the elements in the cache after which the elements are considered to be out-of-date. The time is specified in terms of days, hours, and minutes; for example, 5d 4h 1m. If you do not specify any value, the Time to Live is considered to be unlimited (does not expire). If you set the value to 0d 0h 0m, the API results are not cached. The default time format is minutes if the input is a number.
Maximum Response Payload Size (in KB)	Specifies the maximum payload size for the API in kilo bytes. The value -1 stands for unlimited payload size.

Example of enforcing caching criteria:

In the example, there are two HTTP headers and one query parameter as cache criteria. The HTTP Header Header2 has no values specified. Hence, all the incoming requests with the HTTP Header Header2 are cached.
When there are multiple cache criteria, the following behaviour is observed in the cache result:

• If the incoming request R1 matches criteria C1, then the result is cached. API Gateway responds to any further incoming request R1 that matches criteria C1 from the cache.
• If the incoming request R1 matches criteria C1 and C2, then the result is cached as a new request.
• If you configure multiple cache criteria, and if one or more cache criteria match, then the result is cached. The criteria are matched with the cached results while caching the request, and it follows the AND condition among the matched criteria.

Monitor Performance

This policy is similar to the Monitor Service Level Agreement policy and does monitor the same set of run-time performance conditions for an API, and sends alerts when the performance conditions are violated. However, this policy monitors run-time performance at the API level. Parameters like success count, fault count and total request count are immediate monitoring parameters and the evaluation happens immediately after the limit is breached. The rest of the parameters are Aggregated monitoring parameters whose evaluation happens once the configured interval is over. If there is a breach in any of the parameters, an event notification ( Monitor event) is sent to the configured destination. In a single policy, multiple action configurations behave as AND condition. The OR condition can be achieved by configuring multiple policies.

The table lists the properties that you can specify for this policy:

Monitor SLA

This policy monitors a set of run-time performance conditions for an API, and sends alerts to a specified destination when the performance conditions are violated. This policy enables you to monitor run-time performance for one or more specified applications. You can configure this policy to define a Service Level Agreement (SLA), which is a set of conditions that defines the level of performance that an application should expect from an API. You can use this policy to identify whether the API threshold rules are met or exceeded. For example, you might define an agreement with a particular application that sends an alert to the application if responses are not sent within a certain maximum response time. You can configure SLAs for each API or application combination.

Parameters like success count, fault count and total request count are immediate monitoring parameters and the evaluation happens immediately after the limit is breached. The rest of the parameters are Aggregated monitoring parameters whose evaluation happens once the configured interval is over. If there is a breach in any of the parameters, an event notification ( Monitor event) is sent to the configured destination. In a single policy, multiple action configurations behave as AND condition. The OR condition can be achieved by configuring multiple policies.

The table lists the properties that you can specify for this policy:

Response Processing

These policies are used to specify how the response message from the API has to be transformed or pre-processed and configure the masking criteria for the data to be masked before it is submitted to the application. This is required to protect the data and accommodate differences between the message content that an API is capable of submitting and the message content that an application expects. The policies included in this stage are:

• Validate API Specification

• Response Transformation

• CORS

• Data Masking

• Custom Extension

  Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

Validate API Specification

This policy validates the responses against API’s various specifications such as schema, content-types, and HTTP Headers referenced in their corresponding formats as follows:

• The schema is available as part of the API definition. The schema for SOAP API are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.

• The content- types are available as part of the API definition. FOR SOAP APIs these are imported through WSDL and for REST APIs it can be through swagger, RAML or can be uploaded by the user.

• The HTTP Headers are specified in the Validate API Specification policy page
  

The response sent to the API by an application must conform with the structure or format expected by the API. The responses from the native API are validated against the API specifications in this policy to conform to the structure or format expected by the API.

Various API specifications validated are:

• Schema:

  The responses from the native API are validated against the schema provided in the API definition. The schema defines the elements and attributes and specifies the data types of these elements to ensure that only appropriate data is allowed through to the API.

  For a REST API, the schema can be added inline or uploaded in the Technical Information section on the API Details page. The validation depends on the Content-type header in the request or Accept header in the response and the corresponding schema validation would be executed.

  The schema type for validation is selected based on:

  • The Content-Type header when the policy is added in the Request processing stage.
  • The Accept header when the policy is added in the Response processing stage.
    
    

  If the header or payload is missing the schema validation is skipped.

  The table lists the default Content type/Accept header and schema validation type mapping.

For a SOAP API, the WSDL and the referenced schema must be provided in a zip format. The JSON schema validation is supported for the operations that are exposed as REST.

• Content-types:
  The responses from the native API are validated against the content-types specified in the API definition.

• HTTP Headers:
  The responses from the native API are validated against the HTTP Headers specified in this policy to conform to the HTTP headers expected by the API.

The run-time invocations that fail the specification validation are considered as policy violations. Such policy violation events that are generated can be viewed in the dashboard.

The table lists the API specification properties, you can specify for this policy, to be validated:

Response Transformation

This policy specifies the properties required to transform response messages from native APIs into a format required by the client.

This policy enables you to configure several transformations on the response messages before it is sent to the client.

The table lists the properties that you can specify for this policy:

Parameter	Description
Condition	Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. Available values are: AND. API Gateway transforms the responses that comply with all the configured conditions OR. This is selected by default. API Gateway transforms the responses that comply at least one configured condition. Click Add Condition and provide the following information and click . Variable. Specifies the variable type with a syntax. Variable: Specifies the variable type with a syntax. Operator: Specifies the operator to use to relate variable and the value provided. You can select one of the following: Equals Equals ignore case Not equals Not equals ignore case Contains Not Contains Exists Not Exists Range Greater Than Less Than Value: Specifies a plain value or value with a syntax. For details about the variables available in API Gateway, see Variables available in API Gateway.
Transformation Configuration. Specifies various transformations to be configured.
Header Transformation	Specifies the Header, Query or path transformation to be configured for the responses received from the native API. You can add or modify header, query or path transformation parameters by providing the following information: Variable. Specifies the variable type with a syntax. Value: Specifies a plain value or value with a syntax. You can add multiple variables and corresponding values by clicking . You can remove any header, query, or path transformation parameters by typing the plain value or value with a syntax. Note: Software AG recommends you not to modify the headers ${response.headers.Content-Length} and ${response.headers.Content-Encoding} as API Gateway adds the right values for these headers before sending the response back to client. For details about the variables available in API Gateway, see Variables available in API Gateway. Note: Payload transformation does not happen automatically for content-type transformation. When you change the content type, ensure to do payload transformation. For example, if you change the content-type header from application/xml to application/json, you must also change the respective payload from application/xml to application/json.
Status transformation	Specifies the status transformation to be configured for the responses received from the native API. Provide the following information: Code. Specifies the status code that is sent in the response to the client. For example if you want to transform status code as 201, provide 201 in the Code field. Message. Specifies the Status message that is sent in the response to the client. As both these properties support variable framework, you can make use of the available variables to transform the response code and message. For example, You have submitted successfully can be used to transform the original OK status message. For details about the variables available in API Gateway, see Variables available in API Gateway.
Payload Transformation	Specifies the payload transformation to be configured for the responses received from the native API. Provide the following information: Payload Type. Specifies the content-type of payload, to which you want to transform. The Payload field renders the respective payload editor based on the selected content-type. Payload. Specifies the payload transformation that needs to be applied for the response. As this property supports variable framework, you can make use of the available variables to transform the response messages. For example, consider the client accepting two integer values value1 and value2, and you want to pass these two values from API Gateway to the client, you can configure the payload field as follows: {"value1" : 12,"value2" : 34} You can also configure the payload field using one or more variables by using variable framework. Let us see another syntax. For example, for the same native API seen in the previous example, if your native sends both the values through headers val1 and val2, and you want to add it to payload for the client to recognize the input, you can do so by configuring the payload field as follows: {"value1" :${request.headers.val1},"value2" :${request.headers.val2}} For details about the variables available in API Gateway, see Variables available in API Gateway. Note: If your payload content-type is different from the incoming payload's content-type, you need to transform the content-type of the header using Header Transformation. Click + Add xslt document to add an xslt document and provide the following information: XSLT file. Specifies the XSLT file used to transform the request messages as required. Click Browse to browse and select a file. Feature Name. Specifies the name of the XSLT feature. Feature value. Specifies the value of the XSLT feature. You can add more XSLT features and xslt documents by clicking . Note:API Gateway supports XSLT 1.0 and XSLT 2.0. Click + Add xslt transformation alias and provide the following information: XSLT Transformation alias. Specifies the XSLT transformation alias When the incoming request is in JSON, you can use a XSLT file similar to the below sample: <?xml version="1.0" ?> <xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output method="xml"/> <xsl:template match="/" > <xsl:element name="fakeroot"> <xsl:element name="fakenode"> <!-- Apply your transformation rules based on the response received from the native API> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet> When you receive the response in XML, you can use a XSLT file similar to the below sample: <?xml version="1.0" ?> <xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <xsl:output method="xml"/> <xsl:template match="/"> <xsl:element name="soapenv:Envelope"> <xsl:element name="soapenv:Body"> <!-- Apply your transformation rules based on the response received from the native API> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
Transformation Metadata. Specifies the metadata for transformation of the responses received from the native API. For example, the namespaces configured in this section can be used when you provide the syntax for XPath ${response.payload.xpath} For example: ${response.payload.xpath[//ns:emp/ns:empName]}
Namespace	Specifies the namespace information to be configured for transformation. Provide the following information: Namespace Prefix. The namespace prefix of the payload expression to be validated. For example, specify the namespace prefix as SOAP_ENV. Namespace URI. The namespace URI of the payload expression to be validated. For example, specify the namespace URI as http://schemas.xmlsoap.org/soap/envelope/. This declaration defines SOAP_ENV as an alias for the namespace: http://schemas.xmlsoap.org/soap/envelope/. Note: You can add multiple namespace prefix and URI by clicking .

Data Masking

Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

This policy is used to mask sensitive data at the application level. At the application level you must have an Identify and Access policy configured to identify the application for which the masking is applied. If no application is specified then it will be applied for all the other responses. Fields can be masked or filtered in the response messages to be sent. You can configure the masking criteria as required for the XPath, JSONPath, and Regex expressions based on the content-types. This policy can also be applied at the API scope level.

The table lists the content-type and masking criteria mapping.

The table lists the masking criteria properties that you can configure to mask the data in the response messages:

CORS

The Cross-Origin Resource Sharing (CORS) mechanism supports secure cross-domain requests and data transfers between browsers and web servers. The CORS standard works by adding new HTTP headers that allow servers to describe the set of origins that are permitted to read that information.

This policy provides CORS support that uses additional HTTP headers to let a client or an application gain permission to access selected resources. An application or a client makes a cross-origin HTTP request when it requests a resource from a different domain, protocol, or port than the one from which the current request originated.

If you want to apply this policy in API Gateway at API level, make sure you have set the watt.server.cors.enabled property to false.

This policy is applicable for REST, SOAP, and ODATA APIs.

The table lists the CORS response specifications, you can specify for this policy:

A corresponding HTTP header is set for all the values above as per the specification. For additional information, see https://www.w3.org/TR/cors/.

API Gateway handles CORS preflight request and CORS request differently. To know more about the work flow of CORS preflight and CORS request, refer the respective flowchart.

CORS Preflight Request

A CORS preflight request is a HTTP request that a browser sends before the original CORS request to check whether the API Gateway server will permit the actual CORS request. CORS preflight request uses OPTIONS method and includes these headers as part of the request sent from the browser to API Gateway:

1. Origin

2. Access-Control-Request-Method

3. Access-Control-Request-Headers

The following flow chart explains the flow of the CORS preflight request received in API Gateway:

The following table shows the various use cases of the CORS preflight request originating from browser and how API Gateway responds to each CORS preflight requests:

CORS Request

A CORS request is a HTTP request that includes an Origin header. When API Gateway receives the CORS request, the Origin header in the CORS request is verified against the Access-Control-Allow-Origin configured in the CORS policy, if it matches then API Gateway allows to access the resources.

The following flow chart explains the flow of the CORS request received in API Gateway:

The following table shows the various use cases of the CORS request originating from browser and how API Gateway responds to each CORS requests:

Error Handling

The policy in this stage enables you to specify the error conditions, lets you determine how these error conditions are to be processed. You can also mask the data while processing the error conditions. The policies included in this stage are:

• Conditional Error Processing

• Data Masking

• Custom Extension

  Custom Extension policies allow you to handle requirements that might not be provided by the out-of-the-box policies. You can add these custom extensions into API Gateway policy stages. To learn more about Custom Extension, see Custom Policy Extension.

Conditional Error Processing

Error Handling is the process of passing an exception message issued as a result of a run-time error to take any necessary actions. This policy returns a custom error message (and the native provider’s service fault content) to the application when the native provider returns a service fault. You can configure conditional error processing and use variables to create custom error messages.

The table lists the properties that you can specify for this policy:

Data Masking

Data masking is a technique whereby sensitive data is obscured in some way to render it safe and to protect the actual data while having a functional substitute for occasions when the real data is not required.

This policy is used to mask sensitive data in the custom error messages being processed and sent to the application. Fields can be masked or filtered in the error messages. You can configure the masking criteria as required for the XPath, JPath, and Regex expressions. This policy can also be applied at the API scope level.

The table lists the masking criteria properties that you can configure to mask the data in the request messages received:

Policy Validation and Dependencies

The following table shows:

• Policy dependencies (that is, whether a policy must be used in conjunction with another particular policy).

• Conflicting or incompatible policies.

• Whether a policy can be included multiple times in a single API. If a policy cannot be included multiple times in a single API, API Gateway selects one (depending on the precedence of the policy at the enforcement level) for the effective policy and processes at run-time.

Variable Framework

This figure depicts how the variable framework is used to access the variables in various policies across stages.

The following table summarizes the keywords that are used to define the variable syntaxes:

The following variable types are available in the request or response stages:

• ${paramStage.paramType}

  You can use this syntax to access the following string variables: path, statusCode, statusMessage, httpMethod.

  Examples: ${request.path}, ${response.statusCode}

• ${paramStage.paramType.paramName}

  You can use this syntax to access map types, such as query, headers, and path.

  Example: ${request.query.var1}, ${response.header.Content-Type}, ${request.path.name}.

• ${paramStage.paramType.queryType[queryValue]}

  You can use this syntax to access the payload. Examples:

  • ${request.payload.xpath[//ns:emp/ns:empName]}

    Where “//ns:emp/ns:empName” is the XPath to be applied on the payload if contentType is application/xml, text/xml, or text/html.

  • ${response.payload.jsonPath[$.cardDetails.number]}

    Where $.cardDetails.number is the jsonPath to be applied on payload if contentType is application/json or application/json/badgerfish.

  • ${request.payload.regex[[0-9]+]}

    Where [0-9]+ is the regular expression to be applied on the payload if contentType is text/plain.

  • ${request.isSoapToRest} or ${response.isSoapToRest}

    This variable returns True if the current invoke is REST invoke for a SOAP API. Else it returns False.

• ${paramStage[stepName].paramType.paramName]}

  You can use this syntax to access the header or payload in the request or response stage.

  Example:

  Variable: ${response.headers.id}

  Value: ${response[customExtension].payload.jsonPath[$.id]}

  This transformation adds a header to the response with the name id, and its value is derived from the JSON payload that is sent from the external callout as per the JSON path.

The following sections summarize the variables that are available in API Gateway as part of variable framework template in addition to the existing predefined system context and custom context variables:

Request Variables

Variables that allow you to extract and reuse values in the request processing stage.

Response variables

Variables that allow you to extract and reuse values in the response processing stage.

API Gateway evaluates and supports the array expressions in JSON path.

Example: Consider the following payload.

{
"firstName":"John",
"lastName":"doe",
"age":26,
"address":
{"streetAddress":"naist street","city":"Nara","postalCode":"630-0192"}
,
"phoneNumbers":[
{"type":"iPhone","number":"0123-4567-8888"}
,
{"type":"home","number":"0123-4567-8910"}
]
}

Following are the responses for the expressions after evaluating the array expressions in JSON path.

System Context Variables

API Gateway provides predefined system context variables and the values of these variables are extracted from the client request.

Enhancements to Variable Framework Support

Until API Gateway version 10.5, the variable framework was supported in API Mashup, Request Transformation, Response Transformation, Conditional Error Processing, and Custom Extension policies.

In API Gateway version 10.11 the existing variable framework is enhanced to support the following use cases:

• Simple aliases can be accessed across all stages using variable framework. For example: ${simpleAlias}.

• The existing custom and system context variables are now accessible using variable framework. As part of variable framework, the custom context variables that were defined using ctxVar IS service are merged into custom variables. The syntax for accessing the system context variables or custom context variables using variable framework is similar to the custom variables. Example : ${variableName}. For details on how the system and custom context variables were declared in API Gateway version 10.5, see Conditional Routing.

  Note

  As like the earlier versions of API Gateway, you can also define and access the custom-context variable or custom-variable using the ctxVar IS Service. For details, see The API for Context Variables.

• Both system context variables and custom variables (that includes custom context variables) are accessible across all policy parameters that support variables.

Custom Policy Extension

API Gateway provides a range of out-of-the-box policies to address common API management requirements like security, transformation, validation, error processing, and so on. In addition, API Gateway provides an option to add custom extensions or custom variables.

Custom Extensions

You can add these custom extensions into API Gateway policy stages to handle a requirement that might not be handled by any of the existing policies. You can use custom extensions in conjunction with the existing policies across stages. For example, if you want to invoke a third-party API or call an external endpoint during any stage of API processing, you can add custom logic in the corresponding policy stage and use it as required.

API Gateway supports the following custom extension types:

• External endpoint: Use this custom extension when you have an external endpoint exposed, which can be configured and invoked during any stage in API processing.

  For example, if a native API expects the request in a certain format and the client application sends the request in a different format, you can add a custom extension to modify the incoming request to the required format before sending it to the native API.

• AWS Lambda: Use this custom extension to invoke an Amazon Web Services (AWS) Lambda function and use the business logic built-in the Lambda function in any stage of API processing.

Custom extensions are applicable to the REST, SOAP and OData API types. Custom extensions are supported at all levels such as, API, Scope, Global and can be added in any or all policy enforcement stages except the transport policy and the traffic monitoring policy stages.

The figure depicts a sample workflow for custom extension support in the request and response processing stages in API Gateway:

Custom Variables

You can configure custom variables under custom extension policy. You can assign a value or a variable expression to a custom variable which can be used in other policy parameters. Custom variable also provides option to set custom field to the transactional events. To set the custom fields, you have to define customTransactionFields.FIELD_NAME custom variable. It also provides an option to configure namespaces for Xpath expressions. To configure the namespaces you have to define XpathNamespaces custom variable.

How Do I Invoke a Service through HTTP/HTTPS using Custom Extension?

This use case explains how to invoke a service through HTTP/HTTPS using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

To invoke a service through HTTP/HTTPS using custom extension

1. Ensure you have the external endpoint URL to be invoked during API processing using a custom extension.

2. Click APIs on the title navigation bar.

3. Click the required API.
   The API details page appears.

4. Click Edit.

5. Select Policies.

6. Click Required Policy stage > Custom Extension.
   This adds the custom extension policy where you can configure the required properties.

   

7. Click to open the policy properties section in a full page.

8. Provide the following information in the Conditions section, as required:

   Parameter

   Description

   Condition

   Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. . Available values are: AND. API Gateway executes this policy when all the configured conditions comply in the respective policy stage. OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies. Click Add Condition and provide the following information and click . Variable. Specifies the variable type with a syntax. Operator. Specifies the operator to use to relate variable and the value. You can select one of the following: Equal Equals ignore case Not equals Not equals ignore case Contains Exists Greater Than Less Than Value. Specifies a plain value or value with a syntax. For details about the variables available in API Gateway, see Variables Available in API Gateway.

9. Click Custom Action.

10. Select External endpoint in the custom extension Type field.

11. Provide the following information in the External Endpoint section, as required:

    Property	Description
    Endpoint URI	Provide the external endpoint URI that you want to invoke.
    Method	Specify the method exposed by the API. Available values are: PUT, POST, GET, DELETE, HEAD, CUSTOM. Note: If you select CUSTOM, the HTTP method in the incoming request is sent to the native API.
    SSL Configuration	Specifies the required SSL configuration details of the external endpoint. Provide the following information: Keystore Alias. Specifies the keystore alias. For details on Keystore configuration, see Keystore and Truststore. Key Alias. Specifies the alias for the private key, which must be stored in the keystore specified by the keystore alias. Truststore Alias. Specifies the alias for the truststore. For details on Truststore configuration, see Keystore and Truststore. HTTP Connection Timeout (seconds). Specifies the time interval (in seconds) after which a connection attempt to the external endpoint URL times out. Read Timeout (seconds). Specifies the time interval (in seconds) after which a socket read attempt times out.
    Path Parameters	Specifies the path parameter you want to configure to your custom extension. Provide the following information: Path Parameter Name. Species the name of the path parameter you want to configure in your custom extension. This path parameter name should be present in the endpoint URL enclosed with {} to be replaced at runtime. For example, define external URL as http://host/authors/{id}/books and provide id as path parameter name with the value you need to populate at runtime. Path Parameter Value. Specifies the value for the path parameter specified.

12. Configure the custom properties of the custom extension as required.
    For details about the custom extension properties and their descriptions, see Custom Extension Properties.

13. Click Save.
    The API is saved with the added custom extension.

14. Invoke the API.
    The applied custom extension invokes the mentioned HTTP/HTTPS endpoint and processes as configured.

How Do I Invoke an AWS Lambda Function using Custom Extension?

This use case explains how to invoke an AWS Lambda function using custom extension. The custom extension configured can be enforced in any of the policy stages and used during API processing.

The use case starts when you have an API that has to be enforced with a custom extension and ends when you successfully invoke the API with the custom extension enforced.

To invoke an AWS Lambda function using custom extension

1. Create a Lambda function and ensure it is active.
   For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html.

2. Configure AWS alias.
   For details on how to configure an AWS alias, see Configuring an AWS Alias.

3. Click APIs on the title navigation bar.

4. Click the required API.
   The API details page appears.

5. Click Edit.

6. Select Policies.

7. Click Required Policy stage > Custom Extension.
   This adds the custom extension policy where you can configure the required properties.

   

8. Click to open the policy properties section in a full page.

9. Provide the following information in the Conditions section, as required:

   Parameter

   Description

   Condition

   Conditions are used to specify when the policy has to be executed. We can add multiple conditions with logical operators. . Available values are: AND. API Gateway executes this policy when all the configured conditions comply in the respective policy stage. OR. This is selected by default. API Gateway executes this policy when any one of the configured conditions complies. Click Add Condition and provide the following information and click . Variable. Specifies the variable type with a syntax. Operator. Specifies the operator to use to relate variable and the value. You can select one of the following: Equal Equals ignore case Not equals Not equals ignore case Contains Exists Greater Than Less Than Value. Specifies a plain value or value with a syntax. For details about the variables available in API Gateway, see Variables Available in API Gateway.

10. Click Custom Action.

11. Select AWS Lambda in the custom extension Type field.

12. Provide the following information in the AWS Lambda section, as required:

    Property	Description
    Function Name	Provide the AWS Lambda function name you want to invoke. As this property supports variable framework, you can use the available Function Name variables. For details about the variables available in API Gateway, see Variables Available in API Gateway.
    Invocation Type	Specify the AWS invocation type, asynchronous or synchronous. Available options are: RequestResponse (synchronous type) Event (asynchronous type)
    AWS Alias	Provide the AWS alias configured for the AWS account.
    Client Configuration	Provide the following client configuration details and click . Name. Start typing the client property name and select the required property from the type-ahead search results displayed. API Gateway supports the following properties that you can configure: Socket timeout(ms), Connection timeout(ms), Request timeout(ms), Connection expiration timeout(ms), Maximum Coneection idle time(ms), Client execution timeout(ms), Server error retry count, Enable throttle retries, Maximum client retry count, TCP send buffer size hints, TCP receive buffer size hints, Enable gzip requests, Enable Expect-Continue, Enable host prefix injection, Enable Keep-alive, Enable, Response metadata caching, Response metadata cache size, and Signature Algorithm. Value. Provide a value for the client property specified. You can configure multiple properties. For details about the supported client properties, see the following AWS documents: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/section-client-configuration.html https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/ClientConfiguration.html

13. Configure the custom properties of the custom extension as required.
    For details about the custom extension properties and their descriptions, see Custom Extension Properties.

14. Click Save.
    The API is saved with the added custom extension.

15. Invoke the API.
    The applied custom extension invokes the AWS lambda function and processes as configured.