Administration

Various aspects of the way API Gateway functions can be configured:

  • General configuration for extended settings, service faults, approval settings, URL aliases.

  • Security configuration for keystores and trustore, SAML issuer, custom assertions, OAuth 2.0, Kerberos settings, JWT, and OpenID provider.

  • Destination configuration for targets to which the events and performance metrics data is sent.

  • External accounts to add and configure service registries.

You must have the API Gateway’s manage general administration configurations functional privilege assigned to perform the following configurations in the general configuration section of API Gateway:

  • Configure the extended settings which are advanced parameters required for your server to operate properly.

  • Configure API fault settings for errors being returned by the API Gateway to the applications.

  • Configure approval settings.

  • Configure URL aliases.

  • Configure the custom content-types.

  • Configure API callback request settings.

Tenant Management

Software AG provisions API Cloud in Software AG Cloud platform based on your geographical location. Software AG Cloud has its own Tenant Management System to authenticate users. Once a user registers with API Cloud, the corresponding Tenant Management System initiates the user registration process.

Supported Plans

When you sign up for a webMethods API Gateway trial tenant, the Free forever edition is assigned by default. You can then optionally upgrade to the paid plans like Basic, Advanced, or Enterprise based on your requirement. For more details, see the Pricing tab of webMethods.io API in SoftwareAG Cloud site.

Allowed IP Addresses

Overview

webMethods API Gateway connects with most third-party services easily and instantly. However, in some cases, you may have to connect to your servers from specific IP addresses, and access resources that lie behind a protective firewall. This can be achieved in webMethods API Gateway. SoftwareAG provides a set of static IP addresses that you have to to allow in your firewall. This allows webMethods API Gateway to make connections to your servers and run the required services successfully.

Software AG Cloud products are available in several geographical regions, operated by different infrastructure providers. Go to the Software AG Cloud Regions website for information on the available products and also the underlying infrastructure provider in each region.

Currently, webMethods API Gateway is available on Amazon Web Services (AWS) and Microsoft Azure. Based on the vendor and the associated region selected by you at the time of creating your tenant, you need to allow relevant IPs to establish the connectivity. Once you add the allowed IP addresses available on the Software AG Cloud page, you should be able to connect to your resources from webMethods API Gateway services. If not, contact Software AG Global Support with the required details.

Tenant URL and Software AG Cloud Region

The following table helps you to identify the cloud region based on a your tenant URL. Once you identify your cloud region, go to the Software AG Cloud page for information on the allowed IP addresses.

User Management

User Management in Software AG Cloud

You can manage users and teams information from the Administration page in Software AG Cloud.

Users: User personas who can access API Gateway and perform tasks. There are three user personas, Cloud-Tenant-Administrator, APIGateway-User, and APIPortal-User depending on the roles assigned to the users. Based on the roles, user can access the API Gateway and Developer Portal products.

Note

Only the Cloud-Tenant-Administrators can create, modify users, and delete users.

To remove a user from the system, you must first delete the user from SAG Cloud and then from API Gateway.

Teams: Users who share a common role or responsibility can be grouped as teams. When the Team feature is enabled, the members of teams can access the API Gateway assets of their teams and they can perform actions on these assets based on the functional privileges assigned to their teams.

Note
The APIGateway-User created in Software AG Cloud by Cloud-Tenant-Administrator are part of API-Gateway-Providers team in API Gateway. In API Gateway, the Cloud-Tenant-Administrator is known as API-Gateway-Administrator, who has necessary privileges to associate users to groups and teams from the User management section.

View User Details

You can view user details along with user groups.

To view user details

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Select Users.
    A list of users appears.

    Note
    The newly created users who have not logged into API Gateway do not appear in the list. But, if the API Gateway Administrator associates those newly created users to user groups in the Group tab, then those users are listed in the user list though they have not logged into Software AG Cloud.
  3. Click Login ID of the user that you want to view.
    The User details tab appears with basic information of the user along with user group details appears.

User Groups

API Gateway is shipped with the following predefined groups:

By default, API Gateway’s Administrator user, is part of Administrators and API-Gateway-Administrators group.

The table lists the privileges based on the user group.

Privileges API Gateway Administrator API Provider
Manage APIs Y Y
Manage aliases Y Y
Manage policy templates Y N
Activate/Deactivate APIs Y Y
Manage global policies Y N
Manage threat protection configurations Y N
Manage applications Y Y
Activate/Deactivate global policies Y N
Publish API to service registry Y Y
Manage packages and plans Y Y
Activate/Deactivate packages Y Y
Publish to Developer Portal Y Y
View administration configurations Y N
Execute service result cache APIs Y Y
Manage user administration Y N
Manage general administration configurations Y N
Manage destination configurations Y N
Manage promotions Y Y
Manage security configurations Y N
Manage system settings Y N
Manage service registeries Y N
Import assets Y Y
Export assets Y Y
Manage microgateways Y N
Manage Custom Dashboards Y N

Authentication and Authorization

API Gateway is primarily accessed using API Gateway user interface, which supports Basic authentication and SAML SSO.

You can also use REST APIs to manage API Gateway. To invoke the APIs, you must have the required functional privileges.

Note
You cannot delete predefined users, groups, and teams but you can delete the groups and teams that are created in API Gateway.

Adding a Group

You can add a user to a group. The group is associated to an access profile that contains functional privileges.

To add a group

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Select Groups.

  3. Click Add group.
    The Group details tab appears.

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

    Field Description
    Name Name of the user group.
    Description A description for the user group.
  5. Click Save to save the group details at this stage and provide the group information for the user at a later time.

  6. Click Continue to associate Users >.
    Alternatively, you can click Users to go to the Users section.

  7. Provide the user’s login ID in the Login ID field.
    You can search users based on the characters provided in user name and email id. Select the required user from the list displayed.

  8. Click Save.

Modifying a Group

You can modify details for a selected group. You can add users to a group or remove them if required.

To modify a group

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Click Groups.
    A list of groups appears.

  3. Select the group to be modified.
    The Group details tab appears.

  4. Click Edit.
    This opens the details of the selected group.

  5. Modify the basic information of the user.

  6. Modify the user details of the group.
    Edit or delete (by clicking the delete icon) the name of the existing user that appears.

  7. Click Save.

Deleting a Group

You can delete a group from the list that appears in the Groups section of the User Management page. Once a group is deleted, the user associated to the group is unable to perform the tasks associated with that group. Deleting a group does not delete the users associated with the group.

To delete a group

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Click Groups.
    A list of groups appears.

  3. Click the Delete icon for the group that has to be deleted.

    Note
    You cannot delete predefined groups.
  4. Click Yes in the confirmation dialog.

API Gateway Functional Privileges

The following table lists the functional privileges and their description:

Functional Privilege Description
Select all To select all the listed functional controls.
Manage APIs To create and manage APIs.
Activate/ Deactivate APIs To activate, deactivate and manage APIs.
Manage applications To create and manage applications and register applications with the APIs. You cannot modify or delete an application if you are not the owner of the application.
Manage aliases To create and manage aliases.
Manage global policies To apply a global policy to all APIs or the selected set of APIs.
Activate/Deactivate global policies To activate, deactivate, and manage global policies.
Manage policy templates To apply one or more policy templates to an API.
Manage threat protection configurations To prevent malicious attacks on applications that typically involve large, recursive payloads, and SQL injections.
Publish API to service registry To publish and unpublish APIs to service registry.
Manage packages and plans To create packages and plans, associate a plan with a package, and associate APIs with a package. In addition, you can view the list of packages, package details, APIs, and plans associated with the package.
Activate/ Deactivate packages To activate, deactivate, and manage packages.
Publish to Developer Portal To publish and unpublish assets to API Gateway.
View administration configurations To view administration configurations.
Manage general administration configurations To create and manage administration configurations.
Manage security configurations To create and manage security configurations.
Execute service result cache APIs To execute service result cache API.
Manage destination configurations To publish events and performance metrics data to the configured destinations.
Manage system settings To create and manage system settings.
Manage user administration To create and manage users.
Manage promotions To create stages and manage promotions.
Manage service registries To create and manage service registries
Change ownership/ teams To change ownership of an asset or teams.
Manage scope mapping To manage OAuth and OpenID scopes.
Import assets To import already exported APIs, application, policies, aliases, or other assets and configurations using the Import option in the user menu .
Export assets To export assets to your local system.
Manage purge and restore runtime event To purge and restore events from the API Gateway store by setting the required date or duration in the API Gateway.
Manage microgateways To manage the Microgateways connected to the API Gateway instance.
Manage Custom dashboards To manage custom dashboards in Global Analytics. You can not manage custom dashboards if you do not have this privilege.

Team Support

When users from multiple business units of an organization share the same API Gateway instance, by default, all users have access to all assets irrespective of their departments.

In a typical deployment scenario, all users have same level of access privileges to all API Gateway assets. However, there could be requirement for users from different business units to have different levels of access to specific assets; and they would not want interference from each other.

As a platform administrator, keeping in mind the various role-based access requirements, how do I

This is where the Team support feature of API Gateway is useful. In a shared environment, this feature enables you to provide different level of access to different users to access specific assets.

The Team support is disabled by default; and you must enable the feature to use it. For information about enabling the feature, see Enabling Team Support.

When to use Team support?

Team support can be used to group the users of a business unit or users with similar roles in your organization. Using this feature, you can assign assets for each team and specify the access level of team members based on the team members’ project requirements.

This feature is helpful for organizations that have multiple business units, who work on different projects. Users can access only the assets that are assigned to them. For example, consider an organization with different teams such as Development, Configuration Management, Product Analytics, and Quality Assurance. Each of these teams needs access to different assets at different levels. That is, developers would require APIs to develop applications and they require the necessary privileges to manage APIs and applications. Similarly, analysts would want the necessary privileges to view performance dashboards of assets. In such scenarios, you can group users based on their roles as a team and assign them the necessary privileges based on their responsibility.

Prior to the 10.5 version, users were given the necessary privileges using Access Profiles. Starting version 10.5, you can limit the access of your asset to the required team members and assign access privileges using the Team support feature.

What is a Team in API Gateway?

A team can be defined as a group of users with a set of defined responsibilities.

The assets supported by this feature are APIs, applications, packages, and plans.

This table lists the important points on API Gateway behavior with and without the Team support feature:

Without Team support With Teams support
All users can view all details for all assets. User can view only the assets that are assigned to the teams that they are a part of.
Users can add, modify, delete, activate and deactivate assets, publish and promote assets, export and import assets based on their functional privileges. Privileges are assigned through teams.
Users can perform actions based on their team’s functional privileges.

Users can manage assets based on the functional privileges assigned to the teams they belong to. For details on asset visibility and accessibility, see Team Support Considerations.

When not to use Team support?

You do not use the Team support feature when you require:

Teams management using API Gateway

You can create teams from the User Management section of the API Gateway UI by including the required user groups and assigning them the required functional privileges. You can also assign a Team administrator for each team, who can add or modify team members.

Users with the Manage user administration privilege can create teams. When creating a team, you can assign:

Teams - Asset Association

After you have created teams, you can assign assets to teams in one of the following ways:

If you already have assets in your API Gateway instance and when you enable the Teams support feature, all assets are assigned to the Default team. Every user is automatically assigned to this team. That means, by default, every asset (APIs, applications, packages and plans) are still visible to all users. Access rights are restricted only if the asset is explicitly assigned to one or more teams during its creation.

You must manually remove the Default team from the respective asset details page.

Software AG recommends that you read the Team support considerations section to see the impact of Team support on other features. For more information, see Team Support Considerations.

Enabling Team Support

When you enable the Team support feature, you can manage teams from the Teams tab under the User management section of API Gateway.

If you do not enable this feature, you can still create teams, as explained in Creating Teams, and assign functional privileges to users. However, you cannot assign required assets to a set of users and restrict the access of assets to other users.

If you have enabled this feature, created teams, and assigned assets to teams, and then disable this feature, then the team assignments that you had performed earlier become invalid. That is, the assets are available to users based on their functional privileges and not based on the assigned teams.

To enable teams

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

  2. Select General > Extended settings.

  3. Click Show and hide keys.

    All configurable parameters appear.

  4. Select the enableTeamWork from the parameter list.

    The enableTeamWork field appears in the Extended Settingssection.

  5. Type true in the enableTeamWork field.

    By default, the value of the setting is set as false.

The feature is enabled.

Creating Teams

This use case explains how to create teams by assigning the required functional privileges and users to them.

This use case begins when you have identified the list of users who must be given access to an asset or a particular set of assets and end when you have created a team including the identified users.

In this example, a team with developers called DevTeam is created with the Dev user group as the team members, User1 as the Team administrator, and all privileges under Manage API, Policies and Applications are assigned to the team. The user, User1, is also allowed to approve the pending requests of the applications that the team owns.

Before you begin

Ensure that you have:

To create teams

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Click Teams.

  3. Click Add Team.
    The Create Team page appears.

  4. Provide the name and description of the team in respective fields.

  5. In the Team Administrators section, provide any or both of the following:

    • Login ID of the user who want to assign as a team administrator in the Login ID field.

    • Name of the API Gateway user group or the LDAP group that you want to assign as team administrator in the Group name field.

    You can search users or user groups based on the characters provided in the above fields. Select the required user from the list displayed.

    For the example consider in this use case, the team is named as DevTeam and the User1 is specified as the team administrator.

  6. In the Approvers section, provide any or both of the following:

    • Users. Users who can view the pending requests of assets that the team is associated with. You can specify login Id of the required users.
    • Group name. User groups that can view pending requests of assets that the team is associated with. The users from the specified groups can approve the pending requests of applications that the team owns and approve them. You can specify names of the required API Gateway user groups or the LDAP groups.
      You can search users or user groups based on the characters provided in the above fields. Select the required user from the list displayed.
    For the example considered in this use case, the User1 is specified as the approver.

  7. Select the Include team administrators as approvers option.
    If selected, the users and user groups specified in the Team Administrators section can view the pending requests of the applications that the team is associated with and approve them.

  8. Click Continue to assign functional privileges >.
    The Functional privileges list appears.

  9. Select the functional privileges to be assigned to the team members. For information on the available functional privileges, see API Gateway Functional Privileges.

    In this use case, you need to assign all privileges required to manage the APIs and applications assigned to the team. So, all functional privileges under the APIs, Policies, and Applications section are selected.

  10. Click Continue to assign groups >.
    The Find groups section appears.

  11. In the Name field, provide the name of the user group that you want to add as team members.
    For this use case, the Dev user group that has all developers.

  12. Click Save.
    The DevTeam is created and appears in the list of teams.



    You can now assign assets to the team.

How do I Assign Teams during Asset Creation?

This use case explains how to assign teams for an API Gateway asset.

The use case starts when you have an asset that you want to allow access only to a set of users in your organization and ends when you have assigned team(s) to an asset.

In this example, let us see the steps to assign the asset, DevAPI that is being created to a team that has all developers as team members.

Before you begin

Ensure that you have:

To assign teams during asset creation

  1. Click APIs in the title navigation bar.
    The Manage APIs page appears.

  2. Click Create API. The Create API page appears.

  3. Click Import from an File.

  4. Click Browse to select the file using which you want to create the API.

  5. Provide DevAPI in the Name field.

  6. From the Team drop-down list, select the teams that you want to assign the asset to. For this use case, select the DevTeam.



    The assigned teams appear in the Team field of Basic Information section in the API details page. In this example, the DevAPI is assigned to DevTeam.

By default, all assets are assigned to the Administrators team in addition to the teams that you have assigned during asset creation.

How do I Assign Teams Using Team Assignment Rule?

This use case explains how to assign teams to API Gateway assets using Team assignment rules.

Team assignment rules are used to assign teams to existing assets and the ones you create. You can create rule by specifying a set of required conditions. Assets are validated against the given conditions and assigned to the configured teams. If you do not provide any conditions when for a rule, the rule is assigned to all assets in API Gateway when you activate the rule.

This section explains the steps to configure conditions and team names for creating a rule. Also, it lists the steps to activate rule to apply the rule to assets.

In this example, consider a team of users who must be enabled to view all assets. To achieve this, you can create a team called ViewAllAssets, and create a rule by selecting all assets and no conditions. When no conditions are specified, the rule is applied to all assets. When you activate this rule, all assets are assigned to the ViewAllAssets team.

The use case starts when you have a team and ends when you create a team assignment rule and activate the rule. All assets are assigned to the specified team and the team members can view all assets.

Before you begin

Ensure that you have:

To assign teams using team assignment rule

  1. Expand the menu options icon , in the title bar, and select User management.

  2. Click Global team assignments.

  3. Click Add global team assignment.
    The Team assignment rule page appears.

  4. Provide the name and description of the rule in corresponding fields.
    In this example, ViewRule is provided in the Name field.

  5. Click Continue to filters >.

  6. Select any or all assets in the Asset type field to apply the rule to the selected asset types.
    Available asset types are API, Application, Plan, and Packages.

  7. Select any one of the following from the Logical operator field:

    • AND. To apply the rule only if all conditions are satisfied by an asset.

    • OR. To apply the rule when any of the given condition is satisfied by an asset.

  8. To specify a condition based on the asset attributes, provide the following information, and click Add:

    Field Description
    Attribute Specifies the asset attribute.

    Available attributes: Name, Description, Tags.

    The global team assignment rule supports only API level tags.

    If you select multiple asset types, the tag filter is applicable to the API type alone and is not applicable for the for other asset types during filter evaluation.
    Operator Comparison operator to validate the attribute against the given value.
    Available operators:

    • Equals. Checks if the specified asset attribute is equal to the given value.

    • Contains. Checks if asset contains the given value as a part of its name, description, or tag.

    • Start with. Checks if asset name , description, or tag starts with the given value.

    • Ends with. Checks if asset name , description, or tag ends with the given value.
    Value Value of the attribute.

    For this use case, the rule has to be applied to all assets irrespective of their attributes. So, all asset types are selected and no condition is specified.

  9. Click Continue to assign teams >.

  10. Provide the required team names in the Name field.
    For our use case, the ViewAllAssets team is selected.

  11. Click Save.
    The rule appears in the Global team assignment page.

  12. Click the toggle button, adjacent to the rule.



    The rule is activated and applied across all existing assets. As per the rule, all assets are assigned to the ViewAllAssets team.

  13. Click APIs from the title bar and select DevAPI.
    The API details page for the API appears.
    Note that the API is assigned to the ViewAllAssets team as per the ViewAssetsRule.

How do I Modify Teams Assigned to an API?

This use case explains how to modify the list of teams associated with an API. You can configure an approval process for the modification teams assigned to an API, if required. You can only assign the API to the teams that you are part of. However, you cannot remove the Administrators team and the teams that are assigned to an API using global assignment rules.

The use case starts when you have an API that requires a modification in the list of teams assigned to it and ends when you successfully make the change.

In this example, an API API is assigned to the Administrator team (by default). The API has to be assigned to the API-Gateway-Providers team along with the existing team through an approval process.

Before you begin

To modify the teams of an API

  1. Log on to API Gateway as a user with the change ownership or team privilege.

  2. Click APIs on the title navigation bar.

  3. Click API.
    The API details page appears. The asset we have considered for example is not assigned to any team. So, the default team Administrators is displayed in the Team field of the Basic information section.

  4. Click change.

  5. Select the team that you want to assign and click . In this example, select the team API-Gateway-Providers.

    The change approval process is initiated.

    Note
    If the approval flow is not configured, the API-Gateway-Providers team is added and a success message appears. Skip to step 8.
  6. An approval request is sent to the approver.

  7. The approver approves the request that resides in the Pending Requests section of the API Gateway UI.

    Note
    The approver can click Reject to reject the request for ownership change if the request is invalid. A reject notification is sent to the requester and the team remains unchanged.
  8. Click Change ownership request details to view the request details. The Request details dialog box appears.
    The approval notification is sent to the requester.
    The API-Gateway-Providers team is added.

How do I Change the Ownership of Multiple Teams?

You can change the owners of multiple teams in a single step. This use case explains how to change the ownership of multiple teams by sending a REST request. You can configure an approval process, if required, for the change of ownership to take effect.

The use case starts when multiple teams require change of owner and ends when you successfully change the ownership of the teams.

To change the ownership of multiple teams

  1. Use the following REST request to change the asset ownership to a new user.

    POST http://hostname/rest/apigateway/assets/team
    Content-Type: application/json
    {
    	"assetType": "*", (API/APPLICATION)
    	"assetIds": ["*"],
    	"currentTeams": "team1",
    	"newTeams": ["team2"]
    }
    

    Provide the following information in the REST request:

    • assetType. Specifies the asset type for which you want to assign new teams. Available values are API, APPLICATION, or the wildcard *. The wildcard * specifies all the assets, APIs and applications owned by the user specified in currentTeams.

    • assetIds. Specifies the ID of the assets specified in assetType.

    Note
    This is optional. assetIds is not required if you specify currentOwner.
    • currentTeams. Specifies the current teams of the assets specified in the assetType field.
    Note
    If both currentTeams and assetIds are specified, both are validated. For example, consider user1 and user2 are owners of assetID1 and assetID2 respectively. In the request payload, if you include assetID1 and assetID2 in the assetIds field and user1 in the currentTeams field, then only assetID1 ownership changes.
    • newTeams. Specifies the teams to which you want to assign the specified assets.

    Example: If all APIs assigned to the DevTeam must be assigned to two other teams, Team2 and Team3, then send a REST request as follows:

    POST http://localhost:5555/rest/apigateway/assets/team
    Content-Type: application/json
    {
        "assetType": "*", (API/APPLICATION)
        "currentTeams": "DevTeam",
        "newTeams": ["Team2", "Team3"]
            
    }
    

    This request assigns the all APIs of DevTeam to Team2 and Team3. The change approval process is initiated.

  2. An approval request is sent to the approver.
    The approval request contains information of all the assets whose ownership needs to change and the new owners’ name.

  3. The approver approves the request in the Pending Requests section of the API Gateway UI.
    The approval notification is sent to the requester.

  4. All APIs that are assigned to the DevTeam is assigned to Team2 and Team3.

Team Support Considerations

This section lists the impact of the Team support feature on other API Gateway features.

As stated in previous sections, users can view only the assets that are assigned to their teams. Also, their accessibility depends on the functional privileges assigned to their team. Though this appears to be a simple behavior, there are some scenarios where it gets a little exceptional. Hence, as an administrator, read through the following scenarios carefully before you create team and assign functional privileges:

Visibility and Accessibility of Assets

You can use the Teams support feature to restrict the visibility and access of APIs, applications, packages, and plans. However, there are some scenarios where users from unassigned teams can view or access these assets. Also, note that the Teams support feature does not restrict the visibility and access of aliases, global policies, scopes, users, groups, and teams.

Scenarios that you must consider when using Team support

  1. When an API assigned to a team is associated with applications that are assigned to some other teams, then the team members, to whom the API is assigned can view the applications and remove them if required.

    For example, consider two teams Team_A and Team_B. The API API_1 and Application_1 are assigned to Team_A and the API API_2 and Application_2 are assigned to Team_B. If you associate Application_1 and Application_2 with API_1, then the Team_A members can view Application_2 and remove the application from API_1, if required.

  2. Users can view assets other than APIs, applications, packages, and plans based on their functional privileges. So, the Team support feature does not have an impact on assets like aliases, global policies, scopes, users, groups, and teams.

    For example, consider two APIs, API_1 and API_2 assigned to two different teams; API_1 assigned to Team_A and API_2 assigned to Team_B. Consider a global policy applied to both APIs and an endpoint alias used in both APIs. In this case, users from both teams can view the global policy and the endpoint alias used by these APIs and there is no way to restrict this behavior.

The following table helps you to quickly recall the points discussed earlier in this topic:

Asset type Visibility Accessibility
APIs Users can view the names, details, and versions of the APIs associated with their teams. Users can access APIs based on functional privileges assigned to their teams.
Users can view the names of applications that are associated with the APIs assigned to their teams. Users can remove the applications that are visible (from the API).
Applications Users can view the names, descriptions, versions of the applications associated with their teams. Users can access applications based on functional privileges assigned to their teams.
Users can view the names of APIs that are associated with the applications assigned to their teams. Users can remove the APIs that are visible (from the application).
Packages and plans. Users can view the names and details of the packages and plans assigned to their teams. Users can access packages and plans based on functional privileges assigned to their teams.
Global search field When users search for an asset using a keyword, the search returns only the assets that are assigned to your teams. Users can access assets based on functional privileges assigned to their teams.
Aliases, Global Policies, Users, Groups, Teams, and Scopes All users can view these assets, even if they have read-only access to API Gateway. User can access the assets based on the privilege assigned to the individual users, irrespective of their teams.
Importing and Exporting of Teams and Assets

Team members can import or export assets if they are assigned with the required functional privileges.

Promotion management

Users with Manage promotions privilege can see all associated APIs/Applications (visible and invisible) on the Assets and dependencies page for the Applications/APIs selected on the Search page of the Promotion Management wizard

By switching between the Search page and the Assets and dependencies page using the Back and Next buttons, they can even drill down and recursively see all dependent assets (visible and invisible)

Members of a team can promote assets from one source stage to one or more target stages if they have the required functional privileges.

Scope mapping

Users with Manage scope mapping privilege can see all APIs (including APIs otherwise invisible to them) on the scope mapping configuration page. They can even add them to a scope mapping, but they cannot remove them again

Scope mappings are visible to all users

Note that there will be a scope mapping for every API if pg_oauth2_createDefaultScopes is set to true, so every API is listed in the list of scope mappings - visible to all users

Global policies for APIs

Global policies are visible to all users

API mashup

Users can add APIs owned by you or assigned to your Team, but in an existing API Mashup, you can see the names, versions, selected resources and methods of all configured APIs - even those invisible to you.

API versioning

On the API details page (for a visible API version), the API Gateway displays all version numbers in the version drop-down list - for versions visible and invisible to the current user.

When the user selects an invisible version, API Gateway displays an error message.

Scenarios where you cannot use Teams support

This section explains the use cases that cannot be achieved using the Team support feature.

Scenario 1

The functional privileges assigned to a team applies across all assets assigned to the team. You cannot assign different functional privileges to access different assets. That is, if you assign the Manage APIs functional privilege to a team, then the team members can perform all API-related transactions with the APIs assigned to the team. Similarly, if you assign the Manage applications privilege to a team, then all members of the team can manage the applications assigned to them.

For example, if you assign the Manage APIs privilege to Team_A and assign two APIs API_1 and API_2, then all users of the Team_A can manage both the APIs. If you do not assign the Manage APIs privilege to Team_B and assign two APIs API_1 and API_2, then the Team_B members can only view the APIs. They cannot manage them.

This image describes the flow that you can achieve:

In the same example, you cannot allow Team_B members to view API_1 and to manage API_2. You cannot assign different access level for different assets.

This image describes the flow that you cannot achieve:

Scenario 2

The functional privileges assigned to a team apply universally across all users within the team, affecting all assets assigned to that team and extending beyond the assets directly assigned to it. In other words, if a user has certain functional privileges through one of their teams, and when the user is assigned to another team that does not have a particular functional privilege, the user retains the functional privileges assigned through the first team. You cannot assign different privileges to different assets.

Consider User_2 is a part of Team_B that has the Manage APIs privilege assigned with API_2. In this case, User_2 can manage API_2. At the same time, if User_2 is assigned to Team_C that does not have the Manage APIs privilege. If API_2 is assigned to Team_C, then User_2 can still manage API_2.

This image explains the flow that cannot be achieved:

Custom Domains

A custom domain is a unique name that identifies your website. There are scenarios where you do not want to expose the default domain provided by webMethods API Gateway. In such cases, you can customize the default tenant URL or domain and access the tenant using your own domain.

Use custom domains if you want to make your application accessible on your own domain. Custom domains direct requests to your own URL.

How to configure Custom Domains?

You can request for a custom domain name for your tenant. For example, if your company domain is abc.com, you can have the domain name as https://subdomain.abc.com. Contact Software AG Global Support for details on how to enable and configure the custom domain capability.

Steps to configure custom domains:

Custom domains can be configured in the following two ways:

  1. Determine the number of domains to be configured for your account and the list of custom domains.
    The domain names are owned by you. You can configure multiple custom domains based on the request.

  2. Decide the SSL certificate required, which depends on whether you want to protect a single domain, multiple subdomains of a domain, or multiple domain names.

  3. Share the number of domains to be configured for your account and the list of custom domains with Software AG.

  4. Obtain the SSL certificates from a Certificate Authority (CA) and determine the number and type of domains you want to be protected by the certificates.

  5. Send the SSL certificates and Certificate Key to Software AG in base64 format to configure the certificates on the custom domain load balancer.

  6. Software AG sends you the CNAME in return.
    Using the CNAME, configure your DNS to point to the custom domain load balancer.

  7. After the configuration is completed, start using the custom domain to access webMethods API Gateway.

Checks for existing assets after configuring custom domains

Configuring Extended Settings

You must have the API Gateway’s manage user administration functional privilege assigned to configure the extended settings.

You can configure advanced parameter settings in the Extended settings section. These parameters affect the operation of your server. You must not change these settings unless requested to do so by Software AG Global Support. You can configure the watt parameter settings in this section.

To configure the extended settings

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

  2. Select General > Extended settings.

  3. Click Show and hide keys.
    This displays all the configurable parameters.

  4. You can configure any of the following parameters in the Extended keys section by providing the required values. The configured values are listed under Extended settings at the top of the page.

    Parameter and Description
    allowEGInvokeOnly Specifies whether the SOAP APIs with Transport policy set to http, can be invoked using the reverse invoke method when you set the external port as https, and the Registration and Internal ports as http. Ensure you enable this setting in the system where the SOAP API is created.
    Note: This setting affects only the behavior of SOAP APIs. You can invoke the REST APIs using the reverse invoke method, irrespective of this setting, given the above said conditions are true.
    Possible values:
    • true. You can invoke SOAP APIs using the reverse invoke method if the external port is set as https, and the Registration and Internal ports are set as http.
    • false. You cannot invoke SOAP APIs using the reverse invoke method.
    allowExceedMaxWindowSize Specifies whether the number of records retrieved by Elasticsearch in a single request exceeds the configured value or not.
    Possible values:
    • true. The number of records retrieved in a single request can exceed the maximum value configured in Elasticsearch. This is the default value.
    • false. Displays an error message when the number of records retrieved in a single request exceeds the configured value.
    allowedTracerCount Specifies whether the total number of tracer callsstored at a given point of time.
    Default value is 100 and the maximum value is 1000.
    apiDocumentsRestrictedExtension Specifies the list of restricted file extensions to prevent users from uploading files with those extensions as the input document for an API. For example, a file with the .exe file extension could contain executable code that run on demand when it is downloaded. If files with the .exe file extension are restricted, users cannot upload a file with the .exe extension in API Gateway.
    By default, several standard file extensions are blocked, including any file extensions that are treated as executable files by Windows Explorer. The file extensions blocked by default are:
    • .bat - Batch file
    • .bin - Binary file
    • .dll - Windows dynamic link library
    • .exe - Executable program
    You can remove any or all of the default file extensions.
    apiDocumentsUploadSizeLimitInMB Specifies the maximum document size, in MB, that can be uploaded as an input document for an API.
    Default value is 5.
    This prevents users from uploading huge files that might slow down the system.
    apig_MENConfiguration_tickInterval Specifies the time interval (in seconds) between each interval processor iteration.
    The value, you provide, must be an evenly divisible fraction of the smallest policy interval, which is one minute.
    Default value is 15.
    Note: Exercise caution when you modify this setting as this is a system level setting.
    apig_rest_service_redirect Provide the value true to redirect the incoming service requests to one of the following directives that API Gateway supports in addition to the /gateway directive:
    • /ws
    • /mediator
    The default value is false.
    apig_schemaValidationPoolSize Provide a value that specifies the schema validation pool size.
    The default value is 10.
    apiGroupingPossibleValues Specifies the names of API groups. You can organize your APIs by associating them to the relevant API groups. The groups provided, by default, are:
    • Finance Banking and Insurance
    • Sales and Ordering
    • Search
    • Transportation and Warehousing
    You can add, edit, or delete API groups based on your requirement.
    apiKeyExpirationPeriod Specifies the time for which an API Key is valid. You can provide the value in seconds, minutes, days, months, or years. For example, 8 seconds, 8s, 10 months, 10m, 15 minutes, 15min.
    The expiration date is computed as follows:
    • When a new application is created: Expiration date = The time when an application is created + The value specified in the apiKeyExpirationPeriod parameter.
    • When an API access key is regenerated: Expiration date = The time when the API key is regenerated + The value specified in the apiKeyExpirationPeriod parameter.
    If you do not specify a value, then the API key never expires.
    apiKeyHeader Specifies the HTTP header name from which API Gateway retrieves the API Key from incoming client requests.
    The default value is x-Gateway-APIKey.
    apiMaturityStatePossibleValues Specifies the API maturity state values that can be set for an API. You can search for APIs based on their maturity status.
    The default values provided are Beta, Deprecated, Experimental, Production, and Test.
    appMesh.microgateway.logLevel Specifies the log level of Microgateways that are deployed through API Gateway.
    The default value is ERROR.
    Possible values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
    clusterNotifierCacheStaleInterval Specifies the time interval after which data in the ClusterNotifierCache is considered stale and is removed from the cache.
    The default value is 900 seconds. If you provide a non-numeric value, API Gateway interprets the value as the default value of 900 seconds. If you provide a value less than 60 seconds, API Gateway interprets the value as the lower limit of 60 seconds.
    The ClusterNotifierCache maintains a data structure which has an entry for each active member in a cluster. This data structure is used to communicate changes on API definitions, applications, policies, and so on, between the cluster members. When a cluster member shuts down gracefully it removes its entry from the data structure. However, when a cluster member process is killed the entry remains, and other cluster members continue posting notifications to the entry. In order to avoid endless growing resulting in performance degradation the cluster data structure is monitored for absent cluster members. If a cluster member has not reacted within the configured clusterNotifierCacheStaleInterval it is regarded as stale, and its data is removed from the ClusterNotifierCache.
    decodeAllDelimitersInURI Specifies whether the encoded characters of URL in the incoming client requests must be decoded or not. The URLs are encoded as per the URI specs or user’s requirements.
    Possible values:
    • true. The encoded characters in the URL of incoming requests are decoded.
    • false. The encoded characters in the URL of the incoming client requests are not decoded. This is the default value.
    defaultSearchResultSize Specifies the default size in the search request for the events, and metrics data.
    The default value is 1000.
    If you provide a value -1 it displays all the search results.
    disableRemoteEntityReference Specifies whether remote entity references are resolved when creating a SOAP API.
    Possible values:
    • true. Disables the resolving of remote entity references when creating SOAP APIs.
    • false. Enables the resolving of remote entity references when creating SOAP APIs.
    enableHotdeploy Specifies whether the hot deploy functionality is enabled. When this feature is enabled, you can modify active APIs. The default value is ‘true’.
    Possible values:
    • true. Enables the hot deploy function. This is the default value.
    • false. Disables the hot deploy function.
    Note: Ensure to refresh your browser when you modify this setting to reflect the changes to the ongoing user sessions.
    enableImportBackup Provides an option to secure an API before overwriting it.
    Available values are:
    • true. If you set the value to true, the existing API is restored in the event of an error during the import. This is the default value.
    • false. If you set the value to false, the feature to secure an existing API before overwriting is disabled. If the overwrite fails due to an error during the import, the existing API has to be deleted.
    enableTeamWork Specifies whether the Team Support feature in API Gateway is enabled.
    Possible values:
    • true - enables the Team Support feature.
    • false - disables the Team Support featured. This is the default value.
    esScrollTimeout Specifies the time, in milliseconds, that the search results for each request must be kept active in Elasticsearch.
    When the allowExceedMaxWindowSize setting is enabled, the Scroll feature of the Elasticsearch is enabled to allow Elasticsearch to accept multiple search requests and return multiple results. That is, you can perform multiple search requests using the same query till you get the desired number of records from Elasticsearch.
    When you send a search request, Elasticsearch returns the result and keeps the result active for the time specified in the esScrollTimeOut setting. If a request exceeds the time specified in the esScrollTimeOut setting, then the subsequent search requests also fail with a Invalid Scroll ID error message. For more information on the Scroll feature, refer https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-scroll.
    eventsRefreshInterval Specifies the default refresh interval for the events indices in seconds.
    The default value is 10 seconds.
    forwardInternalAPIsRequest This parameter is required in the case of a paired gateway deployment scenario using an Advanced Edition license at DMZ.
    Specifies whether the incoming requests are forwarded to internal APIs that are deployed in the green zone.
    Possible values:
    • true. API Gateway forwards the incoming requests to the internal APIs that are deployed in the green zone
    • false. API Gateway does not forward the incoming requests. This is the default value.
    Following are the internal APIs and their URIs for which this parameter is required and its value must be set to true:
    • getOAuthToken - /pub/apigateway/oauth2/getAccessToken
    • OAuth Authorization - /pub/apigateway/oauth2/authorize
    • getOpenIdToken - /pub/apigateway/openid/getOpenIDToken
    • openIDCallbackService - /pub/apigateway/openid/openIDCallback
    • getJWTToken - /pub/apigateway/jwt/getJsonWebToken
    forwardQueryParams Specifies whether API Gateway should forward the query parameter sent by client and query parameters configured in Request Processing stage to the native service if the ${sys:resource_path} variable is not present in the Routing policy URL.
    • true. API Gateway forwards the query parameters sent by client and query parameters configured in Request Processing stage to the native service even if the ${sys:resource_path} is not present in the Routing policy URL.
    • false. API Gateway does not forward the query parameters to the native service if the ${sys:resource_path} is not available in the Routing policy. This is the default value.
    gatewayClientInvokingToken Specifies the value of the client token that can invoke the backend APIs in API Gateway.
    The default value is apigateway.
    maxAllowedZipFileSize Specifies the maximum size of the zip file that can be uploaded to create an API from the Create API screen.
    Default value is 100000000.
    maxRegexLengthInSearchQuery Specifies the maximum length of Regex parameter that you can use in Regex expression query.
    Default value is 37000.
    This value can be increased based on the requirement.
    maxWindowSize
    Specifies the maximum number of search results that Elasticsearch can return for a single search request.
    Using the index.max_result_window property in Elasticsearch, you can configure the maximum number of records to be retrieved in a single Elasticsearch request. To know more about the property, refer https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html.
    Default value is 10000.
    If the value configured in the index.max_result_window setting of Elasticsearch is different from that of the default value, then it is recommended that you provide the same value in this field.
    If you have a value greater than the configured value, then Elasticsearch displays an error message. Also, you must enable the allowExceedMaxWindowSize setting if the total number of results to be retrieved is more than the value specified here.
    For example, if you have specified 1000 in this setting and the total number of records to be retrieved is 20000, then API Gateway sends 20 requests to retrieve all records provided the allowExceedMaxWindowSize setting is enabled. In the above example, if the allowExceedMaxWindowSize setting is not enabled, an error message is displayed as the value is lesser than the default value.
    numberOfTokensToCacheLocally Specifies the number of tokens to be cached locally before accessing the cluster for more tokens to serve the next set of requests.
    When a node recieves a request, a locally cached token serves the request. Locally caching tokens avoids access to the cluster for each invocation.
    Specify a value greater than 0 tokens to cache locally. If you do not specify this value, the node has to access the cluster to get token for each invocation.
    API Gateway fetches a new set of tokens from the cluster, if:
    • All cached tokens are used.
    • The validity of tokens is over.
    The default value is 0.
    openAPIImporterValidation Specifies whether API Gateway validates OpenAPI files for syntax errors during the creation of a new API.
    Possible values:
    • true. API Gateway validates OpenAPI files during API creation. If a syntax error is detected, the API is not created, and an error message is displayed in the API Gateway UI.
    • false. API Gateway does not validate OpenAPI files for syntax errors. If a syntax error is present, the API is still created. This is the default value.
    paginationPossibleValues Specifies the list of possible values of the pagination size, that is, number of items listed per page.
    The default values displayed for pagination options are 10,20,30,40,50. For example, if you select 20, then 20 items are displayed per page.
    For example, if you change the values to 5,10,15,20,25 then pagination options displayed are 5, 10, 15, 20 and 25. So now when you select 15, the items displayed per page would be 15.
    On modifying the value, you have to logout and re-login for the changes to reflect.
    pg_Dataspace_GossipInterval Specifies how frequently each node should gossip with one another.
    By default, the value is set to 3 seconds.
    pg_Dataspace_TimeToFail Specifies the maximum permissible interval between two consecutive gossips.
    By default, the value is set to 30 seconds.
    pg_Dataspace_WarmupTime Specifies the maximum permissible rehashing interval from start-up or shut down of the server.
    By default, the value is set to 300 seconds.
    pg_JWT_isHTTPS Specifies whether the transport protocol over which the JSON Web Tokens (JWTs) are granted authorization.
    Possible values:
    • true. Sets the transport protocol HTTPS. This is set by default.
    • false. Sets the transport protocol HTTP.
    pg_oauth2_createDefaultScopes Specifies whether to create a default scope.
    Possible values:
    • true. When you set this to true and local authorization server is configured as the default authorization server, then API Gateway automatically creates a scope in Integration Server during API creation, and creates a scope mapping between the OAuth scope in the local authorization server and the API. This setting is useful in cases where a service is published from Centrasite.
    • false. When you set this to false, API Gateway does not create a scope automatically. Users must manually create and map scopes for the services published from Centrasite. This is the default value.
    pg_oauth2_isHTTPS Specifies the transport protocol over which the OAuth 2.0 access tokens are granted authorization.
    Possible values:
    • true. Sets the transport protocol HTTPS. This is set by default.
    • false. Sets the transport protocol HTTP.
    pg_OpenID_isHTTPS Specifies the transport protocol over which the OpenID (ID) tokens are granted authorization .
    Possible values:
    • true. Sets the transport protocol HTTPS. This is set by default.
    • false. Sets the transport protocol HTTP.
    pg_xslt_disableDoctypeDeclarations Disables the xslt doc type declarations.
    The default value is true.
    pg_xslt_enableDOM Provide the value true to enable DOM parsing.
    The value false disables the DOM parsing and enables other parsers
    pg_xslt_enableSecureProcessing Provide the value false to disable the use of extensions by default.
    The default value is true.
    pg.cs.snmpTarget.connTimeout Specify the number of milliseconds before an inactive connection to the SNMP target server is closed. If set to 0, the socket remains open indefinitely.
    pg.cs.snmpTarget.maxRequestSize Specify the maximum size (in bytes) for SNMP traps.
    The default value is 10485760.
    pg.cs.snmpTarget.retries Specifies the number of times to resend SNMP traps upon failure.
    Default value is 1.
    This parameter works with pg.cs.snmpTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries*sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.cs.snmpTarget.sendTimeOut Specify the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding.
    This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads. The default value is 500.
    This parameter works with pg.cs.snmpTarget.retries to determine the delay in resending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.default.enable.oldVersion Specifies whether the oldest version of an API has to be enabled when the version of an API is not specified.
    For example, when you have an API that is versioned, the client can specify the version number in the URL to invoke that specific version of the API, that is, API-NAME/Version-number. When the client does not specify the version number, API Gateway defaults to the latest version of the API and invokes it. You can use this parameter to change this behavior such that API Gateway defaults to the oldest version of API and invokes it.
    Available values are:
    • true. When you set this parameter as true and invoke an API without specifying the version number, then API Gateway defaults to the oldest version of the specified API and invokes it.
    • false. This is the default value. When you set this parameter as false and invoke an API without specifying the version number, then API Gateway defaults to the latest version of the specified API and invokes it.
    pg.endpoint.connectionTimeout Specifies the time interval (in seconds) after which an HTTP connection attempt times out.
    The default value is 30 seconds.
    This is a global property that applies to the endpoints of all APIs. If you prefer to specify a connection timeout for the endpoints of an API individually, set the HTTP Connection Timeout parameter in the API’s Routing Protocols processing step, which would then take precedence over pg.endpoint.connectionTimeout.
    The precedence of the Connection Timeout configuration is as follows:
    1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.
    4. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
    pg.endpoint.readTimeout Specifies the time interval (in seconds) after which a socket read attempt times out. Default value: 30 seconds.
    This is a global property that applies to all APIs. If you prefer to specify a read timeout for APIs individually, set the Read Timeout field in the API’s’s Routing Protocols processing step, which would then take precedence over pg.endpoint.readTimeout.
    The precedence of the Read Timeout configuration is as follows:
    1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.
    2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.
    3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property.
    4. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
    pg.lb.failoverOnDowntimeErrorOnly Specifies API Gateway’s behavior of endpoints in a load-balanced routing scenario.
    Possible values:
    • true. Load balancing does not happen when the service fault encountered in the response is a downtime error. This is the default value.
    For example, the following are some Downtime exceptions and for which fail overs happen: ConnectException, MalformedURLException, NoRouteToHostException, ProtocolException, SocketTimeoutException, UnknownHostException, UnknownServiceException, Web Service not available, The service cannot be found.
    • false. Load balancing happens whenever a service fault is encountered in the response coming from endpoint 1 and API Gateway immediately tries the next configured endpoint. There is no distinction on the type of fault present in the response from endpoint.
    pg.MTOMStreaming.cachedFiles.delete.interval Specifies the interval (in seconds) to delete the cached MTOM files.
    Default value is 3600 seconds. This property takes effect only when the pg.suppress.IS.lcm setting is set to true.
    pg.nativeServer.validatePrivateIPs Specifies whether to validate the native server endpoint against the private IP configuration during invocation of an API.
    Possible values:
    • true. If this is set to true, then the API invocation is not allowed if the native endpoint uses any private IPs other than the ones configured in /rest/apigateway/configurations/whiteListingIPs
    • false. If this is set to false, no private IP validation is done for the native endpoint.
    Default value is false for on-prem and true for cloud installations.
    pg.overwrite.users.withsameloginid Specifies whether API Gateway must validate and overwrite a user based on their login ID or UUID when importing or promoting the user or team from one stage to another, provided the logged-in credentials (login ID) of both instances are the same.
    Possible values:
    • true. API Gateway validates and overwrites the user with the user’s login ID, if the user is not matched with the UUID during import or promotion of a user or teams. The default value is true.
    • false. API Gateway validates and overwrites the user with the UUID.
    pg.removeSSNID Specifies whether to include the set-cookie header in the response header. The set-cookie header contains ssnid value sent from the native service.
    Possible values:
    • true. The client that invokes API Gateway API, does not receive the set-cookie header that contains ssnid value.
    • false. The client that invokes API Gateway API, receives the set-cookie header that contains ssnid value if the native service sends this in the response.
    pg.security.honourPortAccessModeSettings Specifies whether the access mode settings configured in the Administration > Security > Ports section must be enforced on the HTTP and HTTPS ports.
    In addition to the default port, you can add ports in API Gateway using which you can consume APIs. You can configure the access mode of the ports to determine whether a port can be used to access an API or not. You can either allow or deny the access of all APIs through a port. When you allow access of APIs using a port by default, you can specify a list of APIs that must be denied access over the port. Also, if you deny the access of APIs using a port, you can specify a list of APIs that an be allowed to access using the port.
    You can use the pg.security.honourPortAccessModeSettings setting to configure whether the access mode configured from the Ports section must be enforced on the HTTP and HTTPS ports or not. This configuration is applicable only for REST and OData APIs.
    Possible values:
    • true. Access to the HTTP and HTTPS ports is allowed or denied based on the settings in the Administration > Security > Ports section.
    • false. The access mode setting specified for the ports are not applied. This is the default value.
    pg.snmp.communityTarget.base64Encoded Specify whether to use a third-party SNMPv1 community-based connection.
    If set to true, the community name must be the Base64 value.
    The default value is false.
    pg.snmp.communityTarget.maxRequestSize Specifies the maximum size (in bytes) for SNMP traps.
    The default value is 65535.
    pg.snmp.communityTarget.retries Specifies the number of times to resend SNMP traps upon failure.
    Default value is 1.
    This parameter works with pg.snmp.communityTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.snmp.communityTarget.sendTimeOut Specifies the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding. This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads.
    The default value is 500.
    This parameter works with pg.snmp.communityTarget.retries to determine the delay in re-sending SNMP traps to non-responsive SNMP servers (that is, it retries *sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.snmp.customTarget.connTimeout Specify the number of milliseconds before an inactive connection to the third-party SNMP server is closed. If set to 0, the socket remains open indefinitely.
    pg.snmp.userTarget.maxRequestSize Specify the maximum size (in bytes) for SNMP traps.
    The default value is 65535.
    pg.snmp.userTarget.retries Specifies the number of times to resend SNMP traps upon failure.
    The default value is 1.
    This parameter works with pg.snmp.userTarget.sendTimeOut to determine the delay in re-sending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.snmp.userTarget.sendTimeOut Specifies the time (in milliseconds) to wait before the SNMP trap times out because the server destination is not responding. This value schedules a timer that resends an SNMP event that has not yet completed when it expires. You must set a timeout value that ensures that the trap is sent to the SNMP server within the time frame. This parameter does not abort an event that is in progress. Set this parameter higher than the default when sending traps with large payloads.
    The default value is 500.
    This parameter works with pg.snmp.userTarget.retries to determine the delay in resending SNMP traps to malfunctioning SNMP servers (that is, it retries *sendTimeOut).
    This means that if the retries parameter is set to 3, and the sendTimeOut parameter is set to 500 milliseconds, there is a 1.5 second delay before the thread sending the alert is available to send another event. Malfunctioning event destinations could delay the amount of time it takes API Gateway to report events, or it could cause discarded events when the queue reaches its maximum level.
    pg.soapToRest.typeConvertorEnabled Specifies whether the key values in a SOAP request must be converted to their primitive type when a SOAP API is transformed to REST API. For example, if the XML is 10, it is converted as “number” : 10.
    Possible values:
    • true. Values are converted to their primitive type. This is the default value.
    • false. Values are not converted to their primitive type.
    pg.suppress.IS.lcm Specifies whether to override IS lifecycle manager with API Gateway lifecycle manager.
    Possible values:
    • true. Set this to true to use theAPI Gateway lifecycle manager.
    • false. Set this to false to use the IS lifecycle manager By default, the value is false.
    API Gateway lifecycle manager provides options to specify the interval for deleting of cached MTOM files using the pg.MTOMStreaming.cachedFiles.delete.interval setting.
    pgmen.quotaSurvival.addLostIntervals Specifies whether the lost intervals from the recovered quota should be added.
    pgmen.quotaSurvival.interval Specifies the number of seconds that elapses before the quota survival processor task runs.
    promotionListSortByTime Specifies whether the list of promotions in the Promotions tab of the Promotion management page are sorted by the promotion time.
    Possible values:
    • true. Promotion list is sorted by promotion time with the latest on top.
    • false. Promotion list is sorted by promotion name. This is the default value.
    retainResponseStatus Specifies whether the native service status has to be modified before sending it to client.
    The default value is false, which specifies that if the outbound authentication-custom credentials or delegate incoming credentials are configured with incorrect credentials the native service status is changed before sending it to client.
    If this value is set to true, it specifies that the status received from the native service is sent without modifying it.
    return408ForConnectionTimeout Specifies the status code to be included in the response when a request to the native service times out.
    Possible values:
    • true. The response contains 408 error code uniformly when a request to the native service is timed out. This is the default value.
    • false. The response does not contain 408 error code.
    saveAuditlogsWithPayload Specifies whether the audit logs have to be saved along with payload.
    Possible values:
    • true. The audit logs have to be saved along with payload. This is the default value.
    • false. The audit logs are not saved along with payload.
    sendClientRequestURI Specifies whether the URI that is present in a request must be decoded before sending it to the native service.
    Possible values:
    • true. The URI is not decoded. The unicode characters in a request are encoded.
    • false. The URI is decoded without change in the path of the URL. This is the default value.
    startDayOfTheWeek Specifies the start day of a week for the unit of measurement of the Alert Interval configured, to monitor performance, before sending an alert.
    By default, the start day of the week is set to Monday.
    Note: If you modify this value, you must restart API Gateway for the modified value to take effect. Please contact Software AG Support team to restart the API Gateway server.
    setDefaultContentType Specifies that default content type to be included in the GET and DELETE methods, if the content type is missing in request.
    Possible values:
    • true. The default content type application/x-www-form-urlencoded is added, if content type is missing in request. This is the default value.
    • false -The default content type is not added. The content-type is sent as is.
    strictResourceMatching Specifies whether API Gateway must perform a strict matching of the resource path from runtime invocation with the API definition of resource paths.
    Possible values:
    • true. API Gateway uses the strict resource matching criteria and the matching fails if it encounters any other characters than that are specified. This is the default value.
    • false. API Gateway matches the best resource instead of using the strict resource matching criteria.

    This extended setting functions as follows:
    For example, consider a REST API with resource path /mypath

    The request http://host:port/servicename/mypath/anytext with strictResourceMatching=true returns an HTTP response 404 immediately.

    The request http://host:port/servicename/mypath/anytext with strictResourceMatching=false executes the request in an ordinary way.
    tagsTypeAheadSearchResultSize Specifies the number of existing tags to display during the type ahead search.
    This is available while adding a tag to an API, where you can type a search term. A list of existing API tags appears depending on the search term. The number of API tags displayed in this list is restricted as per the value provided in the tagsTypeAheadSearchResultSizeproperty.
    The default value is 10.
    The minimum value you can provide is 1. If you provide zero or an invalid value, the value of this property is set to the default value 10.
    transferEncodingChunked_handleAsStream Specifies whether the request payload should be handled as stream when the request contains Transfer-Encoding:chunked header.
    The default value is false.
    The behavior is as follows depending on the value provided for this setting:
    • If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as stream.
    • If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as false, the request payload would be handled as is (no streaming).
    • If Transfer-Encoding: chunked header is not sent in the request, the request payload is handled as is (no streaming).
    • If Transfer-Encoding: chunked header is not sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as is (no streaming).
    transformerPoolSize Specifies the maximum size for transform pool that consists XSLT transformers. To reduce performance impacts, you can reuse the transformers from the pool instead of creating them for every request.
    useTypeInIndexNameForESDestination Specifies the index format used when sending data from API Gateway to a configured Elasticsearch destination.
    The default value is true.
    Elasticsearch verison 7.2 supports data with dedicated index for each of the event types. So, API Gateway sends data in different indexes for different event types if the value of this property is set to true. The event type is concatenated with the Elasticsearch destination index name. That is, the index name will be in the following format: {IndexName}_{EventType}. For example, database_transactionalevents; where default is the index name and transactional events in the event type.
    If the value is set to false, the type name is not concatenated with the index name. In this case, the index created for each event is sub-indexed under a main index when data is sent to configured Elasticsearch destination. The value of this setting must be set to false, if the version of the destination Elasticsearch is 5.x or earlier.
    xmlToJSONConversion_keepString Specifies whether the data type of fields in a response payload, after XML to JSON conversion, must be string or a corresponding data type.
    The default value is true.
    Possible values:
    • true. The data type of the fields is retained as string.
    • false. The data type of the fields is changed to a corresponding data type.
    For example:
    Sample XML payload:
    <?xml version="1.0" encoding="UTF-8"?>
    <EmployeeDetail>
    <ID>12345</ID>
    <Name>John</Name>
    <Address>999 ABC Street</Address>
    </EmployeeDetail>
    • Sample response, if you set the extended setting to true:
      {
      "EmployeeDetail": {
      "ID": "12345",
      "Name": "John",
      "Address": "999 ABC Street"
      }
      }
      All fields in the response payload are retained as string.
    • Sample response, if you set the extended setting to false:
      {
      "EmployeeDetail": {
      "ID": 12345,
      "Name": "John",
      "Address": "999 ABC Street"
      }
      }
      The data type of the field ID is integer.
  5. You can configure the watt parameters in the Watt keys section by providing the required values.
    The configured watt keys are listed under Watt settings below the Extended keys at the top of the page. Only the following watt parameters get synchronized across nodes in a cluster setup:

    • watt.security.ssl.client.ignoreEmptyAuthoritiesList.
    • watt.security.ssl.ignoreExpiredChains.
    • watt.server.url.alias.partialMatching.
    • watt.server.oauth.authServer.alias
    • watt.server.oauth.requireHTTPS
    • watt.net.http401.throwException
    • watt.net.http501-599.throwException
    • watt.server.SOAP.MTOMStreaming.enable
    • watt.server.http.Strict-Transport-Security
    • watt.server.rest.removeInputVariablesFromResponse
    • watt.server.coder.responseAsXML
    • watt.security.ssl.cacheClientSessions
    • watt.server.enterprisegateway.ignoreXForwardedForHeader

    If you modify the other watt parameters in one API Gateway instance they do not get synchronized across other nodes in a cluster setup. You have to manually modify them in the other instances.

  6. Click Save.

Configuring API Fault Settings

You must have the API Gateway’s manage user administration functional privilege assigned to configure the API fault settings.

You can configure global error responses for all APIs to display the default error message.

To configure the service fault settings

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

  2. Select General > API fault.

  3. Select Send native provider fault to send the native API provider’s fault content, if available. API Gateway ignores the default error message and sends whatever content it receives from the native API provider. If you do not select this option then API Gateway sends the default error message.

  4. Specify the error message text in the Default error message text box that is sent out when the Send native provider fault is not selected.

  5. Click Save.

Approval Configuration

API Gateway allows you to configure an approval process to ensure that the requests are valid. If the requests are invalid, API Gateway enables approvers to reject the requests. API Gateway allows you to configure approvals for:

In API Gateway, you can create an application and associate (register) the application created with APIs. If you have the API Gateway’s manage general administration configurations functional privilege assigned, you can configure approvals for creating or registering an application. If you have configured approvers, and if a user wants to create and register an application in API Gateway, then the application is created and registered with an API only if any one approver from the approvers group approves the create application and the register application requests. Similarly, you can configure approvals for updating an application or subscribing a package.

You can configure a set of different approvers for creating or registering applications. For example, if you have configured an approvers group, group1 to approve or reject a create application request and an approvers group, group2 to approve or reject a register application request, then when a user creates and registers an application in API Gateway, then the create application request must be approved by any one approver in group1. When the application is created, the register application request is sent to the approvers in group2 and this register application request must be approved by any one approver in group2. When the request is approved, the application created is registered to an API. However, if any one user from group2 rejects the request, then the application gets created but is not register to an API.

API Gateway approvals can also be used when API Gateway is integrated with Developer Portal and an Developer Portal API consumer uses the API get access token to register an application to an API in API Gateway. In this scenario, Developer Portal implicitly sends a request to API Gateway to create an application. When the approvers approve the create application request, an application is created in API Gateway and then API Gateway initiates a register application request and the approvers approve the register application request. The application is registered to an API which is published to Developer Portal. The consumer is now able to view and manage the API in Developer Portal.

Similarly, you can configure approvals for subscribing a package in API Gateway, when an API consumer subscribes to a package in Developer Portal. API Gateway receives the package subscription request and the approvers in the approvers group approve or reject the request for subscribing a package. When the request is approved, the acknowledgement is sent to Developer Portal and the package is subscribed.

Configuring Approvals for Creating Application

You have to configure the approval settings, to enforce approval for creating an application in API Gateway.

To configure approvals for creating an application

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

  2. Select General > Approval configuration > Create application.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the access profile of approvers from the Approvers drop-down list.

  5. Select anyone from the Approved by drop-down list.
    This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

    Note
    If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.

  6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver, for approving the request of creating an application.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for creating an application.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID. For more infomration on supported variables see, Email templates variable.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for creating an application is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type. For more infomration on supported variables see, Email templates variable.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for creating an application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Create Application in the email sent, where Create Application is the event.type. For more infomration on supported variables see, Email templates variable.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Registering Application

You have to configure the approval settings, to enforce approval for associating an application with APIs in API Gateway. The Developer Portal API get access token request is considered as a create and registering application event in API Gateway.

To configure approvals for registering an application

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

  2. Select General > Approval configuration > Register application.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the access profile of approvers from the Approvers drop-down list.

  5. Select the anyone from the Approved by drop-down list.
    This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

    Note
    If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.
  6. Select the Team approvers option to allow the approvers of the team that owns the API being registered.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have
    the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver for associating an application with APIs.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approve section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for associating an application with APIs.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for associating an application with APIs is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requestersection:

    Field Description
    Send notification To send an email notification to the requester that the request for associating an application with APIs is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for registering an application is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for associating an application with APIs is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Register Application in the email sent, where Register Application is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Updating Application

You have to configure the approval settings, to enforce approval for modifying an existing application in API Gateway.

To configure approvals for updating an application

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

  2. Select General > Approval configuration > Update application.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the access profile of approvers from the Approvers drop-down list.

  5. Select anyone from the Approved by drop-down list.
    This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

    Note
    If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.
  6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver for approving the request of modifying an existing application.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for modifying an existing application.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing application is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update Application in the email sent, where Update Application is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Subscribing Package

You have to configure the approval settings in API Gateway, to enforce approval for subscribing a package to a plan in Developer Portal.

To configure approvals for subscribing a package

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

  2. Select General > Approval configuration > Subscribe package.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the access profile of approvers from the Approvers drop-down list.

  5. Select anyone from the Approved by drop-down list.
    This implies that, any one user of the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approvers group.

    Note
    If a user is associated with the selected team, then the user can approve or reject a pending request even if the user is not associated with the Approvers group.
  6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver for subscribing a package.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approve section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for subscribing a package.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for subscribing a package is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for registering an application is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Subscribe Package in the email sent, where Subscribe Package is the event.type.
  14. Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

  15. Click Save.

Configuring Approvals for Updating Subscription

You have to configure the approval settings, to enforce approval to modify an existing subscription in API Gateway. When you request an approval for subscription update, the existing package and plan are in use, until an approver approves your request. Once the approver approves the change of subscription request, the quota is reset.

To configure approvals for updating a subscription

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

  2. Select General > Approval configuration > Update subscription.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the team of approvers from the Approvers drop-down list.

  5. Select Anyone from the Approved by drop-down list.
    This implies that, any user associated with the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approver’s group.

    Note
    If a user is associated with the team, then the user can approve or reject a pending request.
  6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver for approving the request of modifying an existing subscription.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for modifying an existing subscription.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing subscription is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing subscription is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update subscription in the email sent, where Update subscription is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing subscription is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for modifying an existing subscription is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Update subscription in the email sent, where Update subscription is the event.type.
  14. Click Save.

Configuring Approvals for Deleting Subscription

You have to configure the approval settings, to enforce approval to delete an existing subscription in API Gateway. When you raise a deletion request, the application is suspended automatically. If an approver approves the deletion request, the subscription is deleted. However, if the approver rejects the request, subscription is enabled. When the application is suspended, if a user invokes the application, the quota usage for that application is continued to be calculated. This is a known issue and would be resolved in subsequent releases.

To configure approvals for deleting a subscription

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

  2. Select General > Approval configuration > Delete subscription.

  3. Set the Enable toggle button to the on position to enable approval configuration to take effect.

  4. Select the team of approvers from the Approvers drop-down list.

  5. Select Anyone from the Approved by drop-down list.
    This implies that, any user associated with the selected team can approve or reject the requests. The requester need not wait for the approval of each approver in the approver’s group.

    Note
    If a user is associated with the team, then the user can approve or reject a pending request.
  6. Select the Team approvers option to allow the team approvers to approve the pending requests of applications that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. Select Configure approval initiate request mail template to be sent to approver.
    This is to configure the email template to be sent to the approver for approving the request of deleting an existing subscription.

  9. Provide the following information in the Configure approval initiate request mail template to be sent to approver section:

    Field Description
    Send notification To send an email notification to the approver to approve the request for deleting an existing subscription.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.
    Note
    The email notifications are sent only to the local API Gateway users.
  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for deleting an existing subscription is approved.

  11. Provide the following information in the Configure request approved mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for deleting an existing subscription is approved by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Delete subscription in the email sent, where Delete subscription is the event.type.
  12. Select Configure rejection mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for deleting an existing subscription is rejected.

  13. Provide the following information in the Configure rejection mail template to be sent to requester section:

    Field Description
    Send notification To send an email notification to the requester that the request for deleting an existing subscription is rejected by the approver.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Approval of @event.type appears as Approval of Delete subscription in the email sent, where Delete subscription is the event.type.
  14. Click Save.

Email templates variable

Approval Email Variables

Subject Content
@application.name @approver.name
@application.name @approver.name
@event.type @application.name
@requestor.name @event.type
@requestor.email @requestor.name
@requestor.firstName @requestor.email
@requestor.lastName @requestor.firstName
- @requestor.lastName

Rejection Email Variables

Subject Content
@application.name @rejectionReason
@event.type @application.name
@requestor.name @event.type
@requestor.email @requestor.name
@requestor.firstName @requestor.email
@requestor.lastName @requestor.firstName
- @requestor.lastName

How Do I Configure the Approval Process for Ownership Change of Assets?

If you want to enforce an approval process, configure and enable the approval process for ownership change of assets. The approver can approve or reject the request.

Before you begin

Ensure that you have administrator privileges.

To configure the approval process for ownership changes of assets

  1. On the title bar, expand the menu options icon and select Administration.

  2. Select General > Change owner/teams.

  3. Set the Enable toggle button to the on position .

  4. Select the team of approvers from the Approvers list.

  5. Select Anyone in the Approved by list.
    This specifies that any user associated with the approvers’ access profile specified in the Approvers list can approve or reject the requests.

  6. Select the Team approvers option to allow team approvers to approve the ownership change requests of assets that the team is associated with.
    You can specify the users and user groups (Team approvers) in the Approvers section when creating or editing the team details. The Team approvers list will also include the users and user groups specified in the Team Administrators section, if the Include team administrators as approvers option is selected.

  7. Select the Disable auto-approval of the requestor option to specify that applications cannot be automatically approved when they are created by users who have the privilege to approve application creation requests.
    If you do not select this option, then the applications created by users who have the required privileges are automatically approved.

  8. In the Configure approval initiate request mail template to be sent to the approver section, provide the following information:

    • Select Send notification to send an email notification to the approver for the pending approval.
    • Provide the text to display in the subject line and the body of the email.

    Note
    The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers’ login ID.
  9. In the Configure request approved mail template to be sent to the requester section, provide the following information:

    • Select Send notification to send an email notification to the approval requester.

    • Provide the text to display in the subject line and the body of the email.

    Note
    The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Approval of @event.type appears as Approval of Change ownership in the email sent, where Change ownership is the event.type.
  10. In the Configure rejection mail template to be sent to the requester section, provide the following information:

    • Select Send notification to send an approval rejection notification to the requester.

    • Provide the text to display in the subject line and the body of the email.

    Note
    The at sign (@) character acts as a place holder and API Gateway automatically generates the values. For example, Rejection of @event.type appears as Rejection of change of ownership of an asset in the email.
  11. Click Save.

Approval Requests

You can manage your pending requests in the Pending Requests section. You can approve or reject a pending request or delete the requests approved by you.

The Pending Requests section displays the list of requests that you can approve. The following table lists the request types and the users who can view them:

Request types Users who can view and approve requests
Create application
Update application
Update subscription
Delete subscription
  • Team approvers. Approvers from the teams that the application is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the application is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.
Register application
  • Team approvers. Approvers from the teams that the API is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the API is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.
Subscribe package
  • Team approvers. Approvers from the teams that the package is associated with. You can specify the team members who can approve the pending requests in the Approvers section of the Basic information tab when creating or editing team details.
  • Team administrators. Administrators of the team that the package is associated with. This includes the list of the users and user groups specified in the Team Administrators section of the Basic information tab when creating or editing team details. The team administrators can approve the pending requests only when you have selected the Include team administrators as approvers option.

To approve or reject a pending request

  1. Expand the menu options icon icon, in the title bar, and select Pending Requests. The Pending requests page appears.

  2. Select Pending Requests.
    A list of pending requests appears with the following information:

    Field Description
    Requested by The name of the requestor.
    Requestor comments The additional information or comments added by the requestor.
    Event The type of event for which the request is pending.
    Request details The details of the type of event requested.
  3. Click the Approve or Reject icon to approve or reject requests.
    Alternatively, you can select multiple pending requests to be approved or rejected simultaneously by selecting the check boxes adjacent to the names of the requests. The request gets removed from the Pending requests page.

Deleting Requests

When you perform a task, for example, you create an application in API Gateway, then an approval request is generated if an approval is configured in API Gateway and this request that is waiting for approvers approval is listed in the Pending Request section. If you want to delete this request, you can delete it from the Pending Request section.

To delete a request

  1. Expand the menu options icon icon , in the title bar, and select Pending Requests.

  2. Select My requests.
    A list of requests appears with the detailed information of the request.

  3. Click the Delete icon for the request that has to be deleted.

  4. Click Yes in the confirmation dialog.

URL Aliases

A URL alias is an alias that you create to replace a portion of the URL to an API on API Gateway. The URL alias typically replaces the path portion of the URL which identifies the name and invocation endpoint of the API. For example, if the URL is http://test:2225/gateway/RESTCalcService/1.0, you can create a URL alias, calc for an API, then the name and invocation endpoint of the API on API Gateway is replaced with calc, for example, http://test:2225/calc. If the client sends a request that contains the matching alias, then the corresponding URL path is invoked.

In addition to associating a URL alias with a single resource, you can also map different resources for each port, therefore, based on the incoming port, the corresponding resource path is invoked. This makes it possible to define a single URL alias that resolves to different destinations based on the incoming port of the HTTP request.

URL aliases have several benefits:

The URL aliases page displays a list of available URL aliases with the corresponding details including the default URL path, port it is mapped to, and so on. You must have the Manage aliases functional privilege assigned to manage the alias information.

In the URL aliases page, with the Global gateway endpoint section, you can also define global gateway endpoint. For more information about global gateway endpoint, see How do I Define Global Gateway Endpoint?

API Gateway only supports modification of URL aliases for the WmAPIGateway package.

Creating URL Alias

When you create a URL alias, you create an association between an alias and an API on API Gateway.

Keep the following information in mind when creating a URL alias:

To create a URL alias

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

  2. Select General > URL aliases.
    This displays a list of available URL aliases and the corresponding details.

  3. Click Add URL alias and provide the following information:

    Field Description
    Alias The alias name of the proxy server.

    An alias name must be unique across API Gateway.

    The alias name cannot include a space, nor can it include the following characters: # % ? ‘ “ < \

    The alias name cannot begin with the string http:// or https://.
    Default URL path The URL path to the API on API Gateway.

    You must specify the default URL path if you do not define any port mappings for the URL alias. If the URL alias includes port mappings, the Default URL Path field is optional.

    The URL path cannot include a space or the following characters: # % ? ’ “ < |
  4. Click Save.

Enabling Partial Matching of URL Aliases

In some cases, URL requests include identifiers for a particular API. Because these identifiers vary for each instance of an API, URL requests might not exactly match any of the defined URL aliases for a particular API. To enable you to define URL aliases for such APIs, API Gateway can use partial matching to process URL requests. A partial match occurs when a request URL matches or begins with only part of a URL alias.

When partial matching is enabled and API Gateway receives a request URL, an alias is considered a match if the entire alias matches all or the beginning of the request URL, starting with the first character of the request URL’s path.

For example, if URL alias calc has a URL path of gateway/RESTCalcService/1.0 and API Gateway receives the following request URL:

https://MyHost:9072/calc/deleteCalc

The request URL matches the calc alias and resolves to the path: https://MyHost:9072/gateway/RESTCalcService/1.0/deleteCalc.

API Gateway retains the trailing characters of the request URL. In this case, API Gateway retains the /deleteCalc.

To enable API Gateway to use partial matching of URL requests, you must set the value of the parameter watt.server.url.alias.partialMatching to true in API Gateway, go to Administration > General > Extended settings. The default is false.

Modifying a URL Alias

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

  2. Select General > URL aliases.

  3. In the URL Alias list, select the URL alias that you want to edit.
    Alternatively, in the URL Alias list, locate the row that contains the alias you want to modify, and click the Edit icon.

  4. Incorporate the required changes.

  5. Click Save.

Deleting a URL Alias

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

  2. Select General > URL aliases.

  3. In the URL Alias list, locate the row that contains the alias you want to delete, and click icon.

  4. Click Yes in the confirmation dialog box.

Example - Usage Scenarios of URL Aliases

This section explains how an API consumer can invoke an API for which a URL alias is created. In this example, we use the RESTCalcService API. Suppose, the RESTCalcService API is activated in API Gateway and following are the gateway endpoints for this API:

Also, the RESTCalcService consists of the postCalc resource path that adds two numbers.

If this API is published to the API consumer then the invocation endpoint for the consumer may appear as:

https://test:5555/gateway/RESTCalcService/1.0/postCalc

If you do not want to expose the API name and path information or if you want to shorten the invocation endpoint as it is complex, then you can create a custom URL alias. To create a URL alias:

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

  2. Select General > URL aliases.

  3. Click Add URL alias and provide the following values:

    Field Value
    Alias calc
    Default URL path gateway/RESTCalcService/1.0/postCalc
  4. Click Save.

    Suppose, the URL alias name provided while creating a URL alias is calc. You can now expose the https://test:5555/calc invocation endpoint to the API consumer instead of https://test:5555/gateway/RESTCalcService/1.0/postCalc.

    With the default URL path specified in alias configuration, the API consumer can use this URL alias for any ports of gateway endpoint shown in the API details page, for example,

Custom Content-types

An API Provider can configure custom content-types based on how the payloads in the incoming or outgoing requests have to be processed. If the native API consumes some custom content-type, the API Provider can configure a mapping between this custom content-type and a base content-type so that the schema validation, and identification in the policies are performed based on the base type.

For example, a native API consumes application/xyz content-type. The API provider creates an API for this native API and enforces the Validate API Specification policy and the API definition has schema mapping for application/json. When the request reaches API Gateway and as there is no content-type schema mapping for application/xyz, the schema validation is skipped. In such scenarios, if the API provider creates a custom content-type mapping in the API Gateway UI with the content type as application/xyz and base type as JSON, then the payload in the incoming request is validated against the JSON schema.

The following table explains the different identifiers and payload validation criteria that can be used for various content types that you can use to configure your custom content-types.

Content-type Identifier Payload validation
  • application/xml
  • text/xml
  • text/html
  • multipart/form-data
  • multipart/mixed
XPath XML schema
  • application/json
  • application/json/badgerfish
JSONPath JSON schema
text/plain Regex Regex
Note
The custom content-type feature is not supported for the SOAP to REST transformed APIs.

Configure Custom Content-types

When you configure a custom content-type, you specify what base-type the content type while processing the content.

You must have the API Gateway’s manage general administration configurations functional privilege assigned to configure custom content-type.

To configure custom content-type

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

  2. Select General > Custom Content-types.

  3. Provide the Content-type that has to be configured.

  4. Select the Base type as one of the following:

    • JSON: Specifies that the base-type for the provided Content-type is set to JSON.

    • XML: Specifies that the base-type for the provided Content-type is set to XML.

    • Text: Specifies that the base-type for the provided Content-type is set to plain text.

  5. Click icon.
    You can configure multiple custom content-types by clicking Add.

Configuring API Callback Processor Settings

You can configure the API callback processor setting All API callback requests so that API Gateway accepts all the requests from the client that contain the callback request URL and wrap the requests with its own URL before routing them to the native API. This lets API Gateway track the requests that the client sends to the native API and the callback messages that are sent by the native API to the client. In addition, you can use the settings Allow HTTPS access only and Process only allowed IPs requests to avoid any external threats in case an unauthorized user tries to access the protected resource.

You must have manage general administration configurations functional privileges to configure callback processor settings.

To configure API callback processor settings

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

  2. Select General > Callback processor settings.

  3. Select All API callback requests.
    This enables API Gateway to accept all the API callback requests coming from the client and wraps these requests with its own URL before it routes these requests to the native API. This option is selected by default.

    When this setting is disabled, the request from the client reaches the native API, as is, without the API Gateway wrapping it with it own URL. So, when the native API sends out the callback request to the client it directly reaches the client and API Gateway is unable to track such events.

  4. Select Allow HTTPS access only.
    This allows API Gateway to receive only HTTPS callback requests from the native API and processes the requests before routing them to the client. If a HTTP callback request comes in, API Gateway sends out an Access denied message to the client. This option is selected by default.

    If this option is not selected then API Gateway accepts the HTTP callback requests and processes the requests before routing them to the client.

  5. Select Process only allowed IPs requests.
    This allows API Gateway to receive the callback requests only from the IP addresses specified in the Trusted IP addresses list. API Gateway allows callback requests only from the allowed IPs configured in Trusted IP address list. You can configure your native APIs machine IPs or the native API outbound proxy server IPs here, so API Gateway allows a request coming from the native API and would then be routed to the client.

    If there are no trusted IPs configured and this option is selected, then API Gateway does not allow any requests.

  6. Type the IP address in the Trusted IP address and Add.
    You can add multiple IP addresses. API Gateway allows only requests coming from these IP addresses when the option Process only allowed IPs requests is selected.

  7. Click Save.

Destination Configuration

API Gateway can publish events and performance metrics data to the configured destinations. Event type data provides information about activities or conditions that occur on API Gateway. The performance data provides information on average response time, total request count, fault count, and so on, for the APIs that it hosts.

You must have the API Gateway’s manage destination configurations functional privilege assigned to configure the following destinations to which the event types and performance metrics data is published:

Note:In addition to this list of destinations, you can configure custom destination to publish data to different components. For details on custom destinations, see Custom Destination.

Configuring Events for API Gateway Destination

You have to configure the API Gateway destination so that the events and performance metrics data can be published to API Gateway. By default, error events, lifecycle events, policy violation event, and performance data are published to API Gateway.

To configure events for API Gateway destination

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

  2. Select Destinations.

  3. Select API Gateway to configure the event types for this destination.

  4. In Event types, select the type of events to publish to API Gateway.

    The available event types are:

    • Error: Occurs each time an API invocation results in an error.

    • Lifecycle: Occurs each time API Gateway is started or shut down.

    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

  5. Select Report performance data to publish performance metrics data.

  6. In the Publish interval box, enter a time interval (in minutes) how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

  7. In the Audit log data section, select the required management areas for which the audit logs should be recorded in the API Gateway destination.

    Audit logs provide a record of system transactions, events, and occurrences in API Gateway. You can configure audit logging to show the following events:

    • API management

    • Application management

    • Team management

    • Group management

    • Package management

    • Promotion management

    • Approval management

    • Alias management

    • Analytics management

    • Policy management

    • Plan management

    • User management

    Note: By default, audit logging is enabled for all of the above-listed management areas in the API Gateway destination.

  8. Click Save.

Troubleshooting Tips: API Gateway Destination

I see that I am not able to parameterize custom indices for transaction events in API Gateway.

Custom indices can be configured for transaction events in API Gateway under Destinations > Elasticsearch > Configuration page. But parameterizing custom indices is not supported in API Gateway. For example, appending the current date to the index name. Consider an index name txnData and it must be appended with the current date, that is txnData_12_08_2020 and rolled up daily.

Resolution:

You can achieve this use case using the Elasticsearch aliases and rollover APIs of Elasticsearch.

A sample use case is as follows:

Create an alias in the Elasticsearch server, for example txnData and an index rollover like txnData_12_08_2020, txnData_12_08_2020. The alias txnData should point to all the indices txnData_12_08_2020, txnData_12_08_2020. One of the indices in the list is write-enabled and that are the latest and rest of the indices is read-only.

API Gateway sends the events to txnData alias and that alias defines the index that it should write the data to, based on the date.

Configuring Developer Portal Destination

You have to configure Developer Portal as a destination to establish communication channel between API Gateway and Developer Portal to exchange data.

To configure Developer Portal destination

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

  2. Select Destinations.

  3. Select Developer Portal > Configuration to configure Developer Portal as the destination.

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

    Field Description
    Name Name of the Developer Portal being configured. The name should be unique as it is referenced in the list of providers within Developer Portal. This uniqueness is important when multiple API Gateways are publishing APIs to the same Developer Portal.
    Version Version of the portal being configured.
  5. Provide the following information in the Portal configuration section for Gateway to send data to Developer Portal:

    Field Description
    Base URL URL of the Developer Portal instance in the format http://hostname.
    Tenant The tenant details of Developer Portal.

    By default, default tenant is considered if the tenant information is not provided.
    Username Username credential to access Developer Portal instance.
    Password Password credential to access Developer Portal instance.
  6. Provide the following information in the Gateway configuration section for Developer Portal to create applications, request or revoke access tokens, subscriptions, and so on:

    Field Description
    Base URL URL of the API Gateway instance. This is pre-populated.
    Note: When a load balancer URL is updated in API Gateway, the API Gateway base URL is be updated to same in this field.
    Username Username credential of the API Gateway Administrator to access API Gateway instance.
    Password Password credential to access API Gateway instance.
    Stage name Optional. The stage name of one of the stages in an API Gateway instance. The stage name included here is displayed in the API details, API tryout, Manage APIs, and Application details pages in the Developer Portal instance.
  7. Click Test to ensure the connection with the Developer Portal details is established. This connection with the given server is tested and a success message appears.

  8. Click Publish.
    This establishes a communication channel between API Gateway and Developer Portal.

Configuring Events for Developer Portal Destination

Pre-requisites:

You have to configure Developer Portal to communicate with API Gateway before you select the events and metrics for publishing to Developer Portal.

You have to configure the Developer Portal destination so that the events and performance metrics data can be published to Developer Portal.

To configure events for Developer Portal destination

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

  2. Select Destinations.

  3. Select Developer Portal > Events to configure the event types for this destination.

  4. In Event types, select the type of events that you want API Gateway to publish to Developer Portal.

    The available event types are:

    • Error: Occurs each time an API invocation results in an error.

    • Lifecycle: Occurs each time API Gateway is started or shut down.

    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

  5. Select Report performance data to publish performance metrics data.

  6. In the Publish interval box, enter a time interval (in minutes) how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

  7. Click Save.

Post-requisites:

After performing the event configurations, select Developer Portal as a Destination in the Policy Properties page for each policy, to receive the transaction event logs for the assigned policies.

Configuring API Control Plane

API Control Plane is a centralized control and monitoring system that oversees and manages the entire API management landscape deployed across multiple regions, including cloud and on-premise environments. Connecting API Gateway to API Control Plane enables you to control and manage the performance of API Gateway effectively through API Control Plane.

To connect API Gateway to API Control Plane, it is essential to configure API Control Plane agent within API Gateway to establish a communication channel with API Control Plane. The agent is responsible for establishing and maintaining communication with API Control Plane.

You can configure API Control Plane agent through API Gateway UI. To configure the API Control Plane agent through the API Gateway UI, ensure you are using API Gateway version, 10.15.0 Fix 11 or later.

Pre-requisite:

You must have API Gateway’s manage destination configurations functional privilege assigned to configure API Control Plane.

To configure API Control Plane agent through API Gateway UI

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

  2. Select Destinations.

  3. Select API Control Plane > Configuration to configure API Control Plane agent.

  4. Provide the following information in the API Gateway Basic information section:

    Field Description
    Runtime name * Name of the runtime (API Gateway instance).

    This field defines how you want to identify your API Gateway instance in API Control Plane.

    In the context of API Control Plane, a runtime refers to any product deployment within the API Management suite such as API Gateway, Developer Portal, and Microgateway.
    Description Optional. Specify a description for the runtime.
    Tags Optional. Tag of the runtime.

    Tags are used to categorize the runtimes.

    Example: test, local, dev.

    Note: A tag must not contain whitespaces.
  5. Provide the following information in the API Gateway deployment section:

    Field Description
    Deployment type API Gateway deployment type.

    Default value: SAG_SAAS

    This field can not be edited.
    Region Optional. Region name where API Gateway is deployed.
    Location Optional. Country name where API Gateway is deployed.
    Host Optional. Base URL of API Gateway in the format, http://hostname.
    Capacity Optional. The approximate estimate of the throughput that API Gateway can handle for the specified duration.

    You can configure the capacity value with any non-negative integer.
    Capacity units Optional. Choose the unit of duration in which the capacity must be defined. Possible values are as follows:
    • per second
    • per minute
    • per hour
    • per day
    • per week
    • per month
    • per year
  6. Provide the following information in the API Control Plane configuration section:

    Field Description
    Control Plane URL * Base URL of API Control Plane.

    Example: http://hostname
    Username * Username that is used to log on to API Control Plane.

    Note: Ensure that the user belongs to API platform provider user group.
    Password * Password of the corresponding user, which is used to log onto API Control Plane through basic authentication.
  7. Provide the following information in the synchronization configuration section to synchronize the data from API Gateway to API Control Plane:

    Field Description
    Metrics synchronization interval (in seconds) The duration in seconds in which API Gateway must send its metrics data to API Control Plane.

    Default value: 120
    Asset synchronization interval (in seconds) The duration in seconds in which API Gateway has to synchronize the changes made to the assets to API Control Plane.

    Default value: 180
    Retry max attempts The maximum number of retry attempts allowed for API Gateway to establish a connection with API Control Plane if it is lost.

    Default value: 5
    Retry time interval (in seconds) The duration in seconds in which API Gateway has to re-establish the connection with API Control Plane if it is lost.

    Default value: 60
  8. Click Test to test the connection between API Gateway and API Control Plane.

    The connection with API Control Plane is tested and a success message appears.

  9. Enable the API Control Plane communication toggle button to establish communication between API Gateway and API Control Plane.

  10. Click Save.

    Agent configuration is saved in Elasticsearch and a communication is established between API Gateway and API Control Plane.

Note: When you re-configure and save the following configurations:

  • Modifying runtime name field establishes a new communication channel, creating a new runtime in API Control Plane. The old runtime’s status turns red, indicating that the connection is lost.
  • Modifying any field except the runtime name stops the existing communication channel and re-establishes with the updated values. During this period, the runtime’s status appears red, indicating that the connection is lost.
  • If the connection is lost, the API Control Plane communication toggle button changes to a disabled state indicating that the connection is lost.

You can also manage API Control Plane agent configuration using REST APIs. For more details, see API Gateway Administration.

Configuring CentraSite Destination

You have to configure CentraSite as a destination to establish a communication channel between API Gateway and CentraSite to exchange data.

Once an API Gateway asset is published from CentraSite to API Gateway, the CentraSite communication and SNMP configuration details automatically appear in the CentraSite destination of API Gateway. If the same API Gateway asset is unpublished from the API Gateway instance at a later time, the CentraSite communication and SNMP configuration details are automatically removed from the CentraSite destination.

Note: If you have already configured CentraSite as a destination in API Gateway, then publishing another API Gateway asset from any CentraSite instance to API Gateway fails and displays an error. In API Gateway, only one CentraSite instance can be configured as a destination at a time. To reconfigure another CentraSite instance, you need to use the Force reset CentraSite communication and SNMP details option.

To configure CentraSite destination

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

  2. Select Destinations.

  3. Select CentraSite > Configuration to configure the CentraSite communication and SNMP details.

    The Communication section displays the following information:

    Field Description
    Protocol Specifies the communication protocol used to establish communication between API Gateway and CentraSite.
    Hostname Specifies the host name or IP address of the machine on which CentraSite Application Server Tier (CAST) is running.
    UDDI port Specifies the port on which CAST is listening. The default port number for CAST is 53307.
    Username Specifies the CentraSite user ID for authenticating CentraSite when API Gateway communicates with CentraSite. This implies the user ID of a user who has the CentraSite Administrator role or the API Gateway Administrator role in CentraSite.
    Target name Specifies the name of the API Gateway asset as defined in CentraSite.

    The SNMP section displays the following information:

    Field Description
    Transport Specifies the wire transport protocol that is used by the SNMP Listener. Supported values are: TCP and UDP.
    Hostname Specifies the CentraSite host name or IP address to which the SNMP listener binds.
    Port Specifies the port to which the SNMP listener binds. The default port number for CentraSite’s SNMP server is 8181.
    Username Specifies the SecurityName that is used by the SNMP Listener.
    Authorization protocol Specifies the authorization protocol that is used by the SNMP Listener for decoding the incoming trap. Supported values are: MD5 and SHA.
    Privacy protocol Specifies the privacy protocol that is used by the SNMP Listener for decoding the incoming trap. Supported values are: DES, AES128, AES, AES192, AES256, 3DES, and DESEDE.
  4. Select Send SNMP traps to CentraSite to publish data about the runtime events and metrics to the CentraSite SNMP server.

  5. Select Force reset CentraSite communication and SNMP details, and click Reset to delete the current configuration and restore the system configuration.

  6. Click Save. This establishes a communication channel between API Gateway and CentraSite.

Note: The transaction events are published from API Gateway to CentraSite using SNMP. The runtime metrics are published from API Gateway to CentraSite using a UDDI client.

Configuring Events for CentraSite Destination

Pre-requisites:

You have to configure CentraSite to communicate with API Gateway before you select the events for publishing to CentraSite.

You have to configure the CentraSite destination so that events and performance metrics data of APIs in API Gateway can be published to CentraSite. However, you will be able to publish the data to CentraSite destination only for APIs published from CentraSite to API Gateway.

To configure events for Centrasite destination

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

  2. Select Destinations.

  3. Select CentraSite > Events to configure the event types for this destination.

  4. In Event types, select the type of events that you want API Gateway to publish to CentraSite.

    The available event types are:

    • Error: Occurs each time an API invocation results in an error.

    • Lifecycle: Occurs each time API Gateway is started or shut down.

    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

  5. Select Report performance data to publish performance metrics data.

  6. In the Publish interval box, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

  7. Click Save.

Post-requisites:

After performing the event configurations, select CentraSite as a Destination in the Policy Properties page for each policy, to publish the transaction and monitoring event logs for the assigned policies. API Gateway sends these events to CentraSite through SNMP.

Important: As a best practice, Software AG recommends you not to use the CentraSite destination for transaction events with large data payloads. This is because, the SNMP server using which the events are published from API Gateway to CentraSite does not handle transaction events with large data payloads.

Configuring Elasticsearch Destination

You have to configure Elasticsearch as a destination to establish a communication channel between API Gateway and Elasticsearch to exchange data.

To configure Elasticsearch destination

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

  2. Select Destinations.

  3. Select Elasticsearch > Configuration to configure Elasticsearch as the destination.

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

    Field Description
    Protocol Specifies the communication protocol used to establish communication between API Gateway and Elasticsearch.
    Hostname Specifies the host name or IP address of the machine on which Elasticsearch is running.
    Port Specifies the port where Elasticsearch server runs. The default port number is 9240.
    Index name Specifies the index name for Elasticsearch, where the data is stored.
    Username Specifies the Elasticsearch user ID for authenticating Elasticsearch when API Gateway communicates with it.
    Password Specifies the password of the Elasticsearch instance to be used for establishing communication between API Gateway and Elasticsearch.

    Note: You can provide the username and password for the Elasticsearch instances having configured with Basic authentication. You can also provide HTTPS enabled Elasticsearch instance.

  5. Click Test.
    This tests the communication channel between API Gateway and the configured Elasticsearch.

  6. Click Save to save the specified email configuration value.
    You can click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.

Configuring Events for Elasticsearch Destination

Pre-requisites:

You have to configure Elasticsearch to communicate with API Gateway before you select Elasticsearch as a destination.

You have to configure Elasticsearch as a destination so that the event types and performance metrics data can be published to Elasticsearch.

To configure Elasticsearch destination

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

  2. Select Destinations.

  3. Select Elasticsearch > Events to configure the event types for this destination.

  4. In Event types, select the type of events that you want API Gateway to publish to Elasticsearch.

    The available event types are:

    • Error: Occurs each time an API invocation results in an error.

    • Lifecycle: Occurs each time API Gateway is started or shut down.

    • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

  5. Select Report performance data to publish performance metrics data.

  6. In the Publish interval box, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Enter a value from 1 through 60. The default is 60 minutes.

  7. In the Audit log data section, select the required management area for which the audit logs should be recorded in the Elasticsearch destination.

    Audit logs provide a record of system transactions, events, and occurrences in API Gateway. You can configure audit logging to show the following events:

    • API management

    • Application management

    • Team management

    • Group management

    • Package management

    • Promotion management

    • Approval management

    • Alias management

    • Analytics management

    • Policy management

    • Plan management

    • User management

    Note: By default, audit logging is disabled for all of the above-listed management areas in the Elasticsearch destination.

  8. Click Save.

Post-requisites:

After performing the event configurations, select Elasticsearch as a Destination in the Policy Properties page for each policy, to publish the transaction and monitoring event logs for the assigned policies.

Configuring Email Templates

API Gateway provides a default email template to send email alerts. You can compose and save the subject line as well as the email content for reuse. You can also customize the template to suit your needs.

To configure Email Templates

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

  2. Select Destinations.

  3. Select Email > Templates to configure the event templates.

  4. Specify the following for the Log Invocation, Monitor SLA, Monitor Performance, and Traffic Optimization events:

    • Subject: The subject line of the email to be sent.

    • Content: By default, the template appears. You can customize the email content.

    The template consists of the following default information for the Log Invocation event:

    Note: The @ character is a place holder and the values are automatically generated by the system. For example, Status: @status appears as Status: SUCCESS in the email. You can use the existing parameters multiple times, delete the parameter if the parameter is not required from the available parameters, or use the corresponding optional parameters in the template. However, you cannot add new parameters.

    The transaction event parameters from the API Gateway Metrics and Event Notification engine are:

    Runtime_Policy: @policy_action_name
    API: @api_name
    Version : @version
    Operation or Resource_Name: @operation_resource_name
    Native endpoint: @native_endpoint
    Event generation time: @description
    Consumer_Name: @consumer_name
    Consumer_ID: @consumer_ID
    Status: @status
    Coorelation_ID:@correlationID
    Error origin: @errorOrigin
    

    The optional parameters that you can include in the template for the Log Invocation event are:

    Native payload : @nativeResponsePayload
    nativeRequestHeaders:@nativeRequestHeaders
    nativeRequestPayload:@nativeRequestPayload
    nativeResponseHeaders:@nativeResponseHeaders
    nativeResponsePayload:@nativeResponsePayload
    nativeHttpMethod:@nativeHttpMethod
    nativeURL:@nativeURL
    externalCalls:@externalCalls
    sourceGatewayNode:@sourceGatewayNode
    

    The template consists of the following default information for the Monitor SLA, Monitor Performance, and Traffic Optimization events:

    Note: You can use the existing parameters multiple times or delete the parameter if the parameter is not required from the available parameters in the template. However, you cannot add new parameters. The monitor event parameters from the API Gateway Metrics and Event Notification engine are:

    Runtime_Policy: @policy_action_name
    API: @api_name
    Version : @version
    Operation or Resource_Name: @operation_resource_name
    Native endpoint: @native_endpoint
    Action type: @actionType
    Attribute: @attribute
    Consumer_Name: @consumer_name
    Consumer_ID: @consumer_ID
    Alert Message: @alertMessage
    

    Additionally, you can click icon to abandon the changes and revert to the default template. You can click icon to review the changes before adding the changes to the email content and click Save.

Custom Destination

You can configure custom destinations to publish events, performance metrics, and audit logs to a required destination.

You can configure the following four types of destinations using the custom destinations feature:

Why Custom Destination?

API Gateway provides a set of destinations to which you can publish events to various components. But sometimes customer might require the data to be published to a custom destination for further data processing and generating of various reports as per their business requirements. The custom destination feature offers solution to this requirement.

You can configure the custom destinations to publish either or all of the following:

  • Design time events such as audit logs of API Gateway modules.
  • Destination specific details such as error events and policy violation events of assets, and Performance metrics data.
  • Traffic monitoring payloads and alerts of an API
  • You can use custom destination feature to perform:

    Condition based publishing

    You can configure conditions based on which API Gateway filters events to publish to a configured destination. That is, only the events that satisfy your conditions are published to the given destination. For example, you can configure a condition to publish the error events of the assets that satisfy your condition. Since this allows you to filter the data for an asset, you can achieve use cases like publishing of an API level policy violation events to a REST endpoint, publishing of the performance metrics data of an API to a messaging queue and so on.

    To configure a condition, you can use variables available in the variable framework, and specify a matching value based on which the condition must be validated. You can specify multiple conditions and configure whether the data to be published must satisfy all or any of the given conditions. The use cases in this section explain the process of configuring conditions.

    Steps to configure a custom destination

    The following diagram outlines the steps involved in configuring a custom destination:

    You can configure any number of custom destinations.

    How Do I Publish Data to an External Endpoint using Custom Destination?

    This use case explains how to publish data to a REST endpoint using custom destination.

    The use case starts when you have data to be published and ends when you have successfully configured an REST endpoint URL as a destination to publish the data.

    Ensure you have the external endpoint URL to which the data has to be published.

    To publish data to an external endpoint

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

    2. Click Destinations.

    3. Select Custom destinations from the left navigation pane.

    4. Click + Add custom destination.

    5. Provide the name of the custom destination in the Name field.

      The name must be unique and must not be the name of any pre-defined API Gateway destinations such as Elasticsearch.

    6. To configure conditions that determine the data to be published in the specified destination, perform the following steps in the Conditions section:

      • Select one of the following options in the Condition type field:
        • And. To publish data that satisfies all your conditions.
        • Or. To publish data that satisfies one of your conditions.

      • Click + Add condition.

      • Provide the following details for your condition:

        • Variable. Name of the variable based on which you want to validate your condition. This field supports the variables that are available in the Variable framework. For details about the list of variables available, see Variable Framework.

        • Operator. The operator to use to relate variable and the value.

        • Value. The value of the variable that must be matched to satisfy the condition.

      • Click Add.

      The condition appears in the grid.

      Repeat this process to add the required number of conditions. Click on a condition to edit it and click next to a condition to delete it.

    7. Select External endpoint in the Type field.

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

      Property Description
      Endpoint URI Provide the REST endpoint of the destination to publish the specified events. For example, http://localhost:9292/rest_endpoint/.
      Method Specify the method exposed by the API. Available values are: GET, POST, PUT, DELETE, HEAD, and CUSTOM.
      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. Specifies 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.

    9. Configure the custom properties of the custom extension as required.

      For details about the custom extension properties and their descriptions, see Custom Extension Properties.

    10. From the Events section, select the data that you want to publish to the configured destination. The options available are:

      • Event types. Type of events to publish to the specified destination. The available event types are:
        • Error: Occurs each time an API invocation results in an error.
        • Lifecycle: Occurs each time API Gateway is started or shut down.
        • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

      • Performance metrics data. To publish to the specified destination.
      • In the Publish interval of performance metrics data field, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Provide a value from 1 through 60. The default is 60 minutes.

      • Events. API Gateway modules for which the audit logs to publish to the specified destination.

    11. Click Add.

      The custom destination is created successfully and appears in the Custom destinations page. The configured events are published in the specified destination.

      Note: To edit a custom destination, you can click the required custom destination, make changes and click Update. To delete a custom destination, click next to required custom destination. You cannot delete a custom destination that is associated with an API.

    How Do I Publish API-specific Traffic Monitoring Data to a Custom Destination?

    This use case explains how to publish traffic monitoring policy alerts to a custom destination of the external endpoint type.

    The use case starts when you have data to be an API for which you configure traffic monitoring policy and ends when you have successfully selected a custom destination to publish the logs.

    Ensure you have an API and a custom destination of the type external endpoint (with required REST Endpoint URL configured).

    To publish traffic monitoring logs to a custom destination

    1. Click APIs on the title navigation bar.

    2. Click the required API.

      The API details page appears.

    3. Click Edit.

    4. Select Policies.

    5. Click Traffic Monitoring and select a required policy.

    6. Select the custom destination from the Destination section in the Policy Properties pane.

    7. Select any other required details such as Alert interval, Unit, Alert frequency, Alert message and so on.

    8. Click Save.

      The policy logs are published to the REST endpoint specified in the selected custom destination.

    How Do I Publish Data to an AWS Lambda Function using Custom Destination?

    This use case explains how to publish data to an AWS Lambda function.

    The use case starts when you have data to be published and ends when you have successfully configured an AWS Lambda service as a destination to publish the data.

    To publish data to an AWS Lambda function

    1. Click APIs on the title navigation bar.

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

    3. Click Destinations.

    4. Select Custom destinations from the left navigation pane.

      The Custom destination page appears.

    5. Provide the name of the custom destination in the Name field.

      The name must be unique and must not be the name of any pre-defined API Gateway destinations such as Elasticsearch.

    6. To configure conditions that determine the data to be published in the specified destination, perform the following steps in the Conditions section:

      • Select one of the following options in the Condition type field:
        • And. To publish data that satisfies all your conditions.
        • Or. To publish data that satisfies one of your conditions.

      • Click + Add condition.

      • Provide the following details for your condition:

        • Variable. Name of the variable based on which you want to validate your condition. This field supports the variables that are available in the Variable framework. For details about the list of variables available, see Variable Framework.

        • Operator. The operator to use to relate variable and the value.

        • Value. The value of the variable that must be matched to satisfy the condition.

      • Click Add.

      The condition appears in the grid.

      Repeat this process to add the required number of conditions. Click on a condition to edit it and click next to a condition to delete it.

    7. Select AWS Lambda in the Type field.

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

      Property Description
      Function Name Provide the AWS Lambda function name to which you want to publish the configured data.
      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.

    9. Configure the custom properties of the custom extension as required.

      For details about the custom extension properties and their descriptions, see Custom Extension Properties.

    10. From the Events section, select the data that you want to publish to the configured destination. The options available are:

      • Event types. Type of events to publish to the specified destination. The available event types are:
        • Error: Occurs each time an API invocation results in an error.
        • Lifecycle: Occurs each time API Gateway is started or shut down.
        • Policy violation: Occurs each time an API invocation violates the policy enforcement that was set for the API.

      • Performance metrics data. To publish to the specified destination.
      • In the Publish interval of performance metrics data field, enter a time interval (in minutes) to specify how often API Gateway must publish performance metrics. Provide a value from 1 through 60. The default is 60 minutes.

      • Events. API Gateway modules for which the audit logs to publish to the specified destination.

    11. Click Add.

      The custom destination is created successfully and appears in the Custom destinations page. The configured events are published in the specified destination.

      Note: To edit a custom destination, you can click the required custom destination, make changes and click Update. To delete a custom destination, click next to required custom destination. You cannot delete a custom destination that is associated with an API.

    Troubleshooting Tips: API Gateway - Developer Portal Integration

    I see an obsolete Developer Portal destination reference in a published API.

    An old Developer Portal destination reference is associated to all APIs. This old reference is not available anymore, however, it is still associated to all APIs. Hence, all APIs have two associated Developer Portal destinations, one correct and the other obsolete.

    Remove the obsolete reference as follows:

    1.Retrieve API details using the following GET REST call:
    http://localhost:5555/rest/apigateway/apis/apiId

    2.Retrieve associated portal information using the following GET REST call:
    http://localhost:5555/rest/apigateway/portalGateways

    3.Retrieve the API Gateway to Developer Portal association using the following GET REST call:
    http://localhost:9240/gateway_default/deploymentmap/_search

    For every API, this displays two entries; one for the actual portal reference and another for the stale reference. You can delete the stale reference documents from the datastore.

    You can delete the stale reference by using the REST request as follows:

    DELETE http://localhost:9240/gateway_default/deploymentmap/id

    The id you provide here is the id corresponding to the stale reference details you see in the response for Step 3.


    I cannot publish an API to Developer Portal.

    If publishing APIs to Developer Portal fails, it might due to incorrect destination configuration for Developer Portal.

    Resolution: Go to User menu > Administration > Destinations > Developer Portal. Ensure that all the required destination configuration details are provided correctly. If you make any changes you must republish the configuration for the changes to take effect.



    I see stale applications in Developer Portal.

    When a consumer subscribes to a plan or a package, an application is created both in API Gateway and Developer Portal. By mistake, when you delete an application from Gateway, the application in Developer Portal becomes stale.

    To remove the stale applications from Developer Portal, unpublish the package associated with the application and republish it. This triggers the cleanup of the stale application in Developer Portal.

    Audit Logging

    The audit logging feature of API Gateway provides audit information for different categories of system transactions, events, and occurrences of specific events (for example, login attempts) over a period of time. You can use audit logs to view a detailed record of various auditable events that occurred on the API Gateway objects, user login and logout operations, and identify the users who are responsible for the changes. You can configure which audit events to log for a specific destination based on your auditing requirements.

    You can configure API Gateway to log the auditable events for following destinations:

    The following auditable events can be configured to write to the API Gateway audit logs:

    API Gateway writes the audit logging data to the Audit logs dashboard (in the API Gateway user interface, go to Analytics > Audit logs). You can view and download audit logs.

    Best Practices for API Gateway Audit Logging

    API Gateway’s audit logging feature has been implemented on an event-driven approach. By default, the API Gateway destination is enabled to log the auditable events for all areas of management, such as APIs, policies, users, and so on. As a best practice, Software AG recommends that you enable audit logging for the required management areas in other supported destinations: Database, Digital Events, and Elasticsearch. This practice is especially important when you want to provide the audit log data to external sources for analytics and anomaly detections.

    Configuring Audit Logs

    You have to configure which events you need to audit for a destination so that API Gateway logs the auditable events data to the specific destination. You can configure API Gateway to log the auditable events data to the following destinations:

    Note
    You can configure custom destination to publish data to different components. For details on custom destinations, see Custom Destination.

    The following events are available for audit log reports:

    By default, all the auditable events are logged into the API Gateway destination.

    To configure audit logs

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

    2. Select Destinations.

    3. Select the required destination to log the auditable events.

    4. In the Audit log data section, select the required management areas to monitor, audit, and report the data.

    5. Click Save.

    Viewing Audit Logs

    You can use the audit log reports to view the data of auditable events.

    To view audit logs

    1. Expand the menu options icon icon, in the title bar, and select Analytics.
      The dashboard displays the API Gateway-wide analytics based on the metrics monitored.

    2. Select Audit logs.

    3. In the drop-down list, choose the time interval in which you want to view the data of auditable events. The available options are:

      • Last 2 days

      • Last 7 days

      • Last 30 days

      • Last 60 days

      • Last 90 days

      • Custom

    4. If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.

    5. Click Apply filter to filter the analytics based on the time interval chosen.
      You can view logs for API Gateway auditable events in the Audit logs dashboard. You can also download the API Gateway audit log in a text file and view the auditable events data.

    Filtering Audit Log Results

    In general, the number of audit logs displayed as a result of Audit log filter is large. Hence, you can refine the results using the following steps to view the required records.

    You can filter the audit log results based on filters such creation date, event type, payload, and so on. For example, you filter audit logs for the last 90 days, and the number of audit logs for the filter is large, you can filter the log records for a given creation date, event type, or payload.

    To filter audit logs

    1. Click + Add filter above the audit logs grid.
      Logs that are filtered based on the given criteria appears.

    2. Provide the following:

      • Field - Field based on which the records must be filtered.

      • Operator - Conditional operator applied for the filters.

      • Value - Search keywords for the given filters.

    3. Click Save. Audit logs that match your filter criteria appear.

    Downloading Audit Logs

    You can download the audit log reports to examine the data of auditable events.

    To download audit logs

    1. Expand the menu options icon icon in the title bar, and select Analytics. The dashboard displays the API Gateway-wide analytics based on the metrics monitored.

    2. Select Audit logs.

    3. In the drop-down list, choose the time interval in which you want to view the data of auditable events.

    4. If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.

    5. Click Download to download and view the detailed report.
      API Gateway generates a compressed file of the audit logs and downloads it to the default download folder configured in your browser.

      The compressed file is named auditlogs_N.zip. The compressed file contains one or more simple text files, where each text file contains 10,000 audit log records.

      API Gateway audit log are listed below.

      Column Detail
      id Unique identifier of the event that produced the audit record.
      eventType Type of event (audit log) that produced the record.
      creationDate Date and time the event entry was written to the log.
      objectType Type of object (for example, User, API, Application, and so on) on which the event occurred.
      action Type of action (for example, Create, Update, Delete, and so on) that was performed on the object.
      object Unique identifier of the API Gateway object on which the action was performed.
      message Message that describes the event that occurred.
      user Name of a user on the API Gateway instance that triggered the event.
      sourceMachine The host name of the machine on which the API Gateway instance is running.
      clientIPAddress IP address of the machine on which the API Gateway instance is running.
      payload The request payload defined for the event.
      status Current status of the event (Success or Failure).

    Configuring External Accounts

    API Gateway provides capability to add and configure service registries and communicate these changes across nodes in the cluster. An API Gateway administrator can add and remove service registries.

    Service Registry

    A service registry is essentially a catalog of services. Applications that expose services can register their services with one or more service registries. Applications that need to consume a service look up a service registry and obtain the address of an application server that provides the service. Using service registries with API Gateway adds resilience, scalability, and security to the application stack.

    API Gateway uses service registries in the following ways:

    Service Registries supported by API Gateway

    API Gateway currently supports the following service registries:

    Adding a Service Registry

    You must have the Manage service registries functional privilege assigned to perform this task.

    You have to add and configure a service registry in API Gateway before you reference it in an API. In cluster deployments of API Gateway, you can add a service registry on any API Gateway instance—other API Gateway instances are synced automatically.

    To add and configure a service registry

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

    2. Click External accounts.

    3. Click Add service registry.

      Field Description
      Name Name used by API Gateway for the instance of service registry that you are adding.
      Description Description of the instance of service registry.
      Type Type of service registry. Available values are: SERVICE_CONSUL and EUREKA.
      Endpoint configuration
      Endpoint URI The base URI for the service registry. This should include the IP address or the FQDN and the port on which the service registry accepts requests.
      Service discovery path The relative path of the service registry discovery service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service discovery request for the service registry.

      Note: A service registry discovery service returns the address (IP address or FQDN) of an application instance for the requested service ID.
      Service registration path The relative path of the service registry registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service registration request for the service registry.

      Note: API Gateway uses this service to register (publish) a service with the service registry.
      Service de-registration path The relative path of the service registry de-registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service de-registration request for the service registry.

      Note: API Gateway uses this service to de-register (unpublish) a service with the service registry.
      Connection timeout (seconds) Specifies the time (in seconds) after which a connection attempt times out while communicating with the service registry.

      The precedence of the Connection Timeout configuration is as follows:

      1. If you specify a value for the Connection timeout field in routing endpoint alias, then the Connection timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.

      2. If you specify a value 0 for the Connection timeout field in routing endpoint alias, then API Gateway uses the value specified in the Connection timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.

      3. If you specify a value 0 or do not specify a value for the Connection timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.connectionTimeout property.

      4. If you do not specify any value for pg.endpoint.connectionTimeout, then API Gateway uses the default value of 30 seconds.
      Read timeout (seconds) Specifies the time (in seconds) after which a socket read attempt times out while communicating with the service registry.

      The precedence of the Read Timeout configuration is as follows:

      1. If you specify a value for the Read timeout field in routing endpoint alias, then the Read timeout value specified in the Endpoint alias section takes precedence over the timeout values defined at the API level and the global level.

      2. If you specify a value 0 for the Read timeout field in routing endpoint alias, then API Gateway uses the value specified in the Read Timeout field in the routing protocol processing step of an API. The Read Timeout value specified at an API level takes precedence over the global configuration.

      3. If you specify a value 0 or do not specify a value for the Read timeout field in the routing protocol processing step at the API level or specify a value 0 at an alias level, then API Gateway uses the value specified in this pg.endpoint.readTimeout property.

      4. If you do not specify any value for pg.endpoint.readTimeout, then API Gateway uses the default value of 30 seconds.
      SSL configuration
      Keystore alias List of keystores that are configured in API Gateway. This is used when the service registry is SSL enabled.

      Lists all available keystores.
      Key alias Lists all the private keys that are present in the selected keystore alias. This is used when the service registry is SSL enabled.
      Truststore alias A truststore contains the certificates that are trusted by API Gateway. If the service registry is SSL enabled its certificate should be added to the selected truststore.
      Basic authentication details
      Username

      The basic authentication user name.

      Password

      The basic authentication password.

      Other configuration
      Heartbeat interval (This setting is applicable only to Eureka service registries.) The interval at which the API Gateway sends a heartbeat message to the Eureka server to renew its leases. Eureka expects clients, such as API Gateway, to renew the lease by sending heartbeats as per the heartbeat interval configured in the Eureka server.
      Headers
      Key

      An HTTP header key that is included in all the HTTP requests sent to the service registry.

      Value

      A value for the given HTTP header key.

    4. Click Add. The service registry is added to API Gateway.

    Removing a Service Registry

    In cluster deployments of API Gateway, you can remove the service registry on any API Gateway instance—other API Gateway instances are synced automatically.

    To remove a service registry

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

    2. Click Service Registries.

    3. Click icon in the row that has the service registry that you want to remove.

    4. Click Yes to confirm.
      The service registry is removed from API Gateway.

    Configuring an AWS Alias

    Configure an AWS alias if you are using a custom extension that calls an AWS Lamdba function from within a runtime policy enforcement flow of API Gateway API.

    To configure an AWS alias

    1. On the title bar, expand the menu options icon and select Administration.

    2. Click External accounts > AWS configuration.

    3. Click Add new AWS account.

    4. In the Add AWS configuration section, provide the following information:

      a. Name: Provide the AWS alias name.

      b. Description: Optional. Provide a description for the alias.

      c. Region: Provide the AWS account region where the Lambda function is running or deployed. For details on how to create an AWS Lambda function, see https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html.

      d. Access key ID: Provide the access key ID of the AWS account where the Lambda function is running.

      e. Secret access key: Provide the secret access key of the AWS account where the Lambda function is running.

    5. Click Add. This creates the AWS alias and lists in the AWS configuration page.

    Configuring Integration Server Instance for API Implementation

    To implement an API to Integration Server, you must provide the details of the Integration Server instance(s) in API Gateway.

    To configure an Integration Server details

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

    2. Click External accounts.

    3. Click Integration servers. The list of configured Integration server instances appears.

    4. Click Add new Integration servers. The options to add new Integration Server details appear.

    5. Provide the following details:

      Field Description
      Name Name for the Integration Server instance being added.
      Description Description for the configuration.
      Integration Server URL URL of the Integration Server.
      User name User credentials required to access the Integration Server instance.
      Password Password required to access the Integration Server instance.
      Keystore alias The text identifier for the Integration Server keystore file. The keystore contains the private keys and certificates (including the associated public keys) of Integration Server.
      Key alias The The alias for a specific key in the specified keystore.

    6. To validate the connectivity of the specified Integration Server instance, click Test. The connection with the given server is tested and a success message appears.

    7. Click Add. The server details are saved.

    Runtime Events and Metrics Data Model

    API Gateway generates runtime events and Key Performance Indicator (KPI) metrics for the currently active APIs. The types of runtime events that API Gateway can generate are:

    Events Description
    Lifecycle A Lifecycle event is generated each time the API Gateway instance is started or shut down.
    Error An Error event is generated each time an invocation of API results in an error.
    Policy Violation A Policy Violation event is generated each time an invocation of API violates a policy that was configured for the API.
    Transaction A Transaction event is generated each time an API is invoked (successfully or unsuccessfully).
    Monitor A Monitor event is generated when a configured SLA parameter, such as the average response time, fault count, availability, and so on, is breached for the API.

    KPI metrics are used to monitor the run-time execution of APIs. Metrics include the maximum response time, average response time, fault count, availability of APIs, and so on. If you include runtime monitoring policies, the policies will monitor the KPI metrics for APIs, and can send alerts to various destinations when user-specified performance conditions for an API are violated. The KPI metrics that API Gateway can generate are:

    Metric Reports on…
    Availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. Only the time when the API is unavailable counts against this metric. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Average Response Time The average amount of time it took the API to complete all invocations in the current interval. This is measured from the moment API Gateway receives the request until the moment it returns the response to the client.
    Fault Count The number of failed invocations in the current interval.
    Maximum Response Time The maximum amount of time it took the API to complete an invocation in the current interval.
    Minimum Response Time The minimum amount of time it took the API to complete an invocation in the current interval.
    Successful Request Count The number of successful API invocations in the current interval.
    Total Request Count The total number of requests for each API running in API Gateway in the current interval.

    You can configure API Gateway to publish the runtime events and metrics data to different destinations. The following sections describe the runtime events and metrics data model for each of these destinations:

    API Gateway

    The runtime events and metrics payload is generated by API Gateway at run-time. The columns that make up the events and metrics data model for API Gateway are listed below:

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI1
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationIp IP address of the application associated with the API invocation.
    Example:10.20.248.33
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationName Name of the application associated with the API invocation.
    An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    callbackRequest Indicates whether the event is generated for a callback request.
    Possible values are:
    • true. This denotes that the event is generated for a callback request.
    • false. This denotes that the event is generated for a normal response.
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    errorOrigin The origin of error.
    Example: Nativeservice
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    gatewayTime Duration in milliseconds, to process a request by API Gateway. This does not include native service processing duration.
    gatewayTime = totalTime - providerTime
    Example: 20
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    reqPayload The API request payload data.
    Example: RequestPayload
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponseHeaders Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 100
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 120

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred.
    Example: Invocation for SampleAPI was rejected based on policy violation, response code: 503
    eventType The type of event that occurred.
    Example: Error Event
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    userAgent Name of the client used to invoke the API.
    Example: Postman

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertType The type of alert generated for the event.
    Possible values are: Monitor, sla
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Monitor Event
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.

    Lifecycle Events

    Column Description
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: LifeCycle
    gatewayStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Policy Violation Event
    httpMethod The HTTP method used to request the API access.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    userAgent Name of the client used to invoke the API.
    Example: Postman

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 135
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Performance Metrics Event
    faultCount The number of failed API invocations in the current interval.
    Example: 10
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 1526294632172
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 1526294632182
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 343
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 10
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    successCount The number of successful API invocations in the current interval.
    Example: 100
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 110

    Threat Protection Events

    Column Description
    id The unique identifier for an event.
    Example: 8e05267a-45c9-45f0-a3dd-8b2ee1e98ca2
    creationDate Date and time when the event was generated in API Gateway.
    Date and time when the event was generated in API Gateway.
    eventType The type of event that occurred.
    Example: Transactional
    alertAction A helpful action taken on the API for the alert.
    Example: DENY
    filterName Name of the threat protection filter.
    Example: DoSFilter
    message If the API invocation failed, message that describes the error that occurred.
    Example: Global Denial of Service limits were reached: Maximum requests limit of 2 in 120 seconds has been exceeded.
    requestHost Hostname of the machine from which the API access request was submitted.
    Example: 10.60.34.152
    requestTime Date and time the request was submitted.
    Example: 1501671101509
    requestType The type of request that was received for the API.
    Example: ALL
    resourcePath The relative URI path of a resource that was used for API invocation.
    Example: invoke/pub.date/getCurrentDate
    ruleName The API Gateway rule that triggered the event.
    Example: GlobalDoSRule
    serverHost The name or IP address of the machine on which the thread protection server is running.
    Example: 10.60.34.83
    serverPort The port number on which the thread protection server is configured to listen for incoming requests.
    Example: 8911

    Developer Portal

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Developer Portal destination. The columns that make up the events and metrics data model for Developer Portal are listed below:

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    <Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.1.1.211
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    errorOrigin The origin of error.
    Example: Nativeserivce
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":" These external calls can be to a native service or service registry. <br>Example:[{“externalCallType”:“SERVICE_REGISTRY_CALL”,“externalURL”:“http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": “200”},{“externalCallType”:“NATIVE_SERVICE_CALL”,“externalURL”:“https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]`
    gatewayTime Duration in milliseconds, to process a request by API Gateway. This does not include native service processing duration.
    gatewayTime = totalTime - providerTime
    Example: 20
    operationName Name of the API operation that is invoked. Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    providerTime Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 20
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    response The API response payload data.
    Example: <ResponsePayload>
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 100
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 120

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.20.248.33
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred. Service invocation for SampleAPI was rejected based on policy violation, response code: 503
    eventType The type of event that occurred.
    Example: Error Event
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 503
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: sla
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation.
    An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Monitor Event
    monitorAttr The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Lifecycle Events

    Column Description
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    eventType The type of event that occurred.
    Example: LifeCycle
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerIp IP address of the consumer associated with the API invocation.
    Example: 10.20.248.33
    consumerName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Policy Violation Event
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b1
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 135
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Performance Metrics Event
    faultCount The number of failed API invocations in the current interval.
    Example: 10
    includeFaults Includes failed API invocations.
    Possible values are: true, false
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 2015-08-26 04:13:35 PM
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 2015-08-26 04:13:45 PM
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 343
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 10
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts.
    successCount The number of successful API invocations in the current interval.
    Example: 100
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 110

    Audit Log

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Audit Log destination. The columns that make up the events and metrics data model for Audit Log are listed below:

    Transactional Events

    Column Description
    API_ID The unique identifier for the API.
    Example: ec1473cc-40a0-479e-9126-474a917c3c89
    API_NAME Name of the API in which the event occurred.
    Example: SampleAPI
    API_VERSION The system-assigned version identifier for the API.
    Example: 1.0
    AUDITTIMESTAMP Date and time when the event was written to the log.
    Example: 2017-08-07 07:22:22
    CONSUMER_IP IP address of the consumer associated with the API invocation.
    Example: 10.60.37.42
    CONSUMER_NAME Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    CONTEXTID The unique identifier for the current context information API Gateway uses to connect related entries from different logs. This column is currently not used. It appears as NULL or as an empty string.
    Example: 81546147-41a8-4998-8150-02ba67bb08c2
    CORRELATIONID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    CUSTOMFIELDS The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    ERROR_ORIGIN The origin of error.
    Example: Nativeservice
    EVENT_PK The primary key (PK) that uniquely identifies the event that occurred.
    Example: 1
    EXTERNAL_CALLS List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    INSERTTIMESTAMP Date and time when the event was generated in API Gateway.
    Example: 2017-08-07 07:22:22
    MSGID The ID assigned to the message by the API provider. This column is currently not used.
    Example: 361dc2f8-a60b-fc21-8545-9b07fce1a479
    NATIVE_ENDPOINT The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    NATIVE_HTTP_METHOD The HTTP method used to invoke the native service.
    Example: GET.
    NATIVE_REQUEST_HEADERS Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899","postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    NATIVE_REQ_PAYLOAD The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    NATIVE_RESPONSE_HEADERS Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    NATIVE_RES_PAYLOAD The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    NATIVE_URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    OPERATION_NAME Name of the API operation or resource that is invoked.
    Example: /pet/{petId}
    PROVIDER_TIME Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1336
    QUERY_PARAMETERS This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    REQUEST_HEADERS Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    RESPONSE_HEADERS Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    ROOTCONTEXTID The unique identifier for the root context information API Gateway uses to connect related entries from different logs. This column is currently not used. It appears as NULL or as an empty string.
    Example: 81546147-41a8-4998-8150-02ba67bb08c2
    SERVERID The API Gateway server on which the transaction event occurred. This column is currently not used. It appears as NULL or as an empty string.
    Example: *SampleHost:80
    SERVICE_NAME Name of the service in which the event occurred.
    Example: Swagger_Petstore
    SESSION_ID A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: 6dfcd849198c4a7e96b4ff89bc2deaf5
    SOURCE_GATEWAY_NODE Source API Gateway’s IP address.
    Example: 10.0.75.1
    STATUS Status of the API request.
    Possible values are: SUCCESS, FAILURE
    TOTAL_TIME Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1042

    CentraSite

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured CentraSite destination. The columns that make up the events and metrics data model for CentraSite are listed below:

    Transactional Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: be8b27d6-8f79-4c6e-b06c-a628d2ba30c3
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.20.169
    CorrelationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 01:27:45 AM
    CustomFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    ErrorOrigin The origin of error.
    Example: Nativeservice
    Event Type The type of event that occurred.
    Example: Transaction Event
    External Calls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    Native Request Headers Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    Native Req Payload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    Native Response Headers Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    Native Res Payload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    PartnerId The unique identifier for the partner that generated the audit record.
    Example: unknown
    Provider Round Trip Time Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1700
    queryParameters This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    RequestPayload The API request payload data.
    Example: <RequestPayload>
    responseHeaders Response header in the outgoing response.
    Example: `{“Server”:“Jetty(9.2.9.v20150224)”,“Access-Control-Allow-Origin”:”*“,“Access-Control-Allow-Methods”:“GET, POST, DELETE, PUT”,“Connection”:“close”,“Date”:“Fri, 30 Mar 2018 08:25:45 GMT”,“Access-Control-Allow-Headers”:“Content-Type, api_key, Authorization”,“Content-Type”
    ResponsePayload The API response payload data.
    Example: <ResponsePayload>
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    Total Round Trip time Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1707
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    Request Status Status of the API request. Possible values are: SUCCESS, FAILURE

    Error Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: be8b27d6-8f79-4c6e-b06c-a628d2ba30c3
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.20.169
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 08:24:04 AM
    Error Source The source where the error occurred.
    Example: e1cc3c7b-495d-11e7-a5a6-88cf17308ba4
    Error Description Message that describes the error that occurred.
    Example: Resource / not found
    Event Type The type of event that occurred.
    Example: Error Event
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Monitoring Events

    Column Description
    PolicyName Name of the policy that is enforced on the API.
    Example: Log Invocation
    Alert Description Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: MSLA_ALERT MESSAGE
    Alert Source Name of the API Gateway policy that generated the alert message.
    Example: Monitorpolicy, EnforcePolicy-HardLimit
    Alert Type The type of alert generated for the event.
    Possible values are: Monitor, Sla
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    apiName Name of the API in which the event occurred.
    Example: pet1
    apiName Name of the API in which the event occurred.
    Example: pet1
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation.
    An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    Monitored Attribute The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    native_endpoint The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    operationName Name of the API operation that is invoked.
    Example: Using a Calculator API, you can perform various operations such as addition, subtraction, multiplication, and division. When an addition operation is invoked in API Gateway, then the operation field name is populated as addInts
    sessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    targetName Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Policy Violation Events

    Column Description
    ApiUserVersion The system-assigned version identifier for the API.
    Example: 1.0
    Alert Source Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    Alert Type The type of alert generated for the event.
    Example: PolicyViolation
    Alert Description Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation of policy was detected : Unable to identify the application for the request
    Consumer Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: unknown
    ConsumerId The unique identifier for the consumer associated with the API invocation.
    Example: unknown
    Consumer IP Address IP address of the consumer associated with the API invocation.
    Example: 10.60.37.118
    Created Time Date and time when the event was generated in API Gateway.
    Example: 2017-08-09 08:25:52 AM
    Event Type The type of event that occurred.
    Example: Policy Violation Event
    Gateway Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance

    Lifecycle Events

    Column Description
    TimeStamp Date and time when the event was generated in API Gateway.
    Example: 2017-08-26 04:13:35 PM
    Target Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    LifeCycleStatus Status of the API Gateway instance.
    Possible values are: STARTED or STOPPED
    LifeCycleAlertDescription The alert notification message for the lifecycle event.
    Example: Alert_Message

    Performance Metrics

    Column Description
    AVG_RESP_TIME The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 1376
    FAULT_COUNT The number of failed API invocations in the current interval.
    Example: 1
    INCLUDE_FAULTS Includes failed API invocations.
    Possible values are: true, false
    INTERVAL_START The starting date and time from which you want to examine metrics.
    Example: 02 Aug 2017 10:51:31 GMT
    INTERVAL_STOP The ending date and time until which you want to examine metrics.
    Example: 02 Aug 2017 10:52:31 GMT
    MAX_RESP_TIME The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1401
    MIN_RESP_TIME The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1352
    OPERATION_NAME Name of the API operation that is invoked.
    Example: /pet/{petId}
    SERVICE_KEY The Universally Unique Identifier (UUID) for the service in which the event occurred.
    This column is currently not used by APIs created in API Gateway. It is used to support the APIs that are migrated from CentraSite or Mediator to API Gateway.
    SUCCESS_COUNT The number of successful API invocations in the current interval.,
    Example: 1
    TARGET_NAME Name of the API Gateway instance reporting the event.
    Example: API_Gateway_Instance
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example:2

    Elasticsearch

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Elasticsearch destination. The columns that make up the events and metrics data model for Elasticsearch are listed below:

    Transactional Events

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    cachedResponse Indicates whether the response is sent to the client from the cached data present in API Gateway through the Service result caching policy or the response is received from Native service and sent to client.
    Possible values are: Cached, Not-Cached
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    isCallbackRequest Indicates whether the event is generated for a callback request.
    Possible values are:
    • true. This denotes that the event is generated for a callback request.
    • false. This denotes that the event is generated for a normal response.
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    errorOrigin The origin of error.
    Example: Nativeservice
    eventType The type of event that occurred.
    Example: Transactional
    externalCalls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    messageType This is applicable only for WebSocket APIs. This indicates the type of a WebSocket message.
    Possible values are: binary, text
    nativeHttpMethod The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestHeaders Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    nativeReqPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponseHeaders Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    nativeResPayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    nativeURL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    origin This is applicable only for WebSocket APIs.The origin of the request.
    Possible values are: client, server
    packageId The unique identifier for the API package.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    packageName Name of the API package.
    Example: Travel Package
    planId The unique identifier for the API plan.
    Example: d0f84954-9732-11e5-b9f4-f159eafe47b2
    planName Name of the API plan.
    Example: Gold Plan
    providerTime Time in milliseconds required for API Gateway to invoke a native provider and receive a response. This time includes the overhead incurred by API Gateway. Overhead includes the time it takes for a provider to process a request and return a response, plus any network latency to or from the provider. Subtracting total time from provider time must give a rough indicator of the API Gateway overhead.
    Example: 1367
    queryParameteres This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    reqPayload The API request payload data.
    Example: <RequestPayload>
    requestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    resPayload The API response payload data.
    Example: <ResponsePayload>
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 404
    responseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    serverID The API Gateway server on which the transaction event occurred.
    This column is currently not used. It appears as NULL or as an empty string.
    Example: SampleHost:80
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    status Status of the API request.
    Possible values are: SUCCESS, FAILURE
    totalDataSize The total combined size of request and response payloads in bytes.
    Example: 51
    totalTime Time in milliseconds required to invoke the API provider. This time includes the overhead incurred by API Gateway. Overhead includes security overhead for encryption, decryption, and load-balance retries.
    Example: 1401

    Error Events

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    correlationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    errorDesc Message that describes the error that occurred.
    Example: Native service provider error. Code : 404
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Error
    httpMethod The HTTP method used to invoke the API.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 404
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.
    sourceGatewayNode Source API Gateway’s IP address.
    Example: 10.0.75.1
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Monitorpolicy
    alertType The type of alert generated for the event.
    Example: Monitor
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: Monitor
    httpMethod The HTTP method used to request the API access.
    Example: GET
    monitorAttr The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 200
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.

    Policy Violation Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: A violation was detected for policy (Unknown-Policyuser ): application could not be identified. Anonymous access is not allowed for this service!
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    alertType The type of alert generated for the event.
    Example: PolicyViolation
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationId The unique identifier for the application associated with the API invocation.
    Example: 9434e90d-65c3-4e37-8ccb-595b8df3e645
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    applicationName Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventSource The source where the event occurred.
    Example: API_Gateway_Instance
    eventType The type of event that occurred.
    Example: PolicyViolation
    httpMethod The HTTP method used to request the API access.
    Example: GET
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    responseCode The HTTP response status code that indicates success or failure of the requested operation.
    Example: 503
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.

    Performance Metrics

    Column Description
    apiId The unique identifier for the API.
    Example: af70b2de-c9c5-4f40-94be-7d8622743e42
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    availability The percentage of time that an API was available during the current interval. A value of 100 indicates that the API was always available. If invocations fail due to policy violations, this parameter could still be as high as 100.
    Example: 100.0
    avgResponseTime The average amount of time it took the API to complete each invocation in the current interval. Response time is measured from the moment API Gateway receives the request until the moment it returns the response to the caller.
    Example: 1376
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: PerformanceData
    faultCount The number of failed API invocations in the current interval.
    Example: 1
    includeFaults Includes failed API invocations.
    Possible values are: true, false
    intervalStart The starting date and time from which you want to examine metrics.
    Example: 02 Aug 2017 10:51:31 GMT
    intervalStop The ending date and time until which you want to examine metrics.
    Example: 02 Aug 2017 10:52:31 GMT
    maxResponseTime The maximum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1401
    minResponseTime The minimum amount of time (in milliseconds) it took for the API to complete an invocation in the current interval.
    Example: 1352
    sourceGatewayDetails Details of events generated only from Microgateway. The details include Microgateway Id, Source Gateway Host, Source Gateway Port, Source Gateway Version, Microgateway pool.
    sourceGateway Source of event generation.
    Possible values: APIGateway or Microgateway.
    operationName Name of the API operation that is invoked.
    Example: /pet/{petId}
    successCount The number of successful API invocations in the current interval.
    Example: 1
    totalCount The total number of API invocations (successful and unsuccessful) in the current interval.
    Example: 2

    Email

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Email destination. The columns that make up the events and metrics data model for Email are listed below:

    Transactional Events

    Column Description
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    consumerId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    consumerName Name of the consumer associated with the API invocation.
    A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a security policy that is configured for the API.
    Example: SampleApplication
    CorrelationID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    Description Message that describes the date and time the API was invoked and the application associated with the API invocation. Invoked at 4/24/18 1:50 PM Consumer Name: Unknown Consumer ID: Unknown
    ErrorOrigin The origin of error.
    Example: Nativeservice
    External Calls List the external calls from API Gateway. These external calls can be to a native service or service registry.
    Example: [{"externalCallType":"SERVICE_REGISTRY_CALL","externalURL":"http://service.registry.com","callDuration":49,"callStartTime":1562244570486,"callEndTime":1562244570535,"responseCode": "200"},{"externalCallType":"NATIVE_SERVICE_CALL","externalURL":"https://petstore.swagger.io/v2/store/inventory","callDuration":1285,"callStartTime":1562244569252,"callEndTime":1562244570537,"responseCode":"200"}]
    Native Endpoint The endpoint URL of the native API being invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    Native Request Headers Request header in the incoming request from the API Gateway to native service.
    Example: {"Authorization":"**************","Accept": "*/*","Authorization": "**************", "Accept":"*/*","Cache-Control": "no-cache","User-Agent": "PostmanRuntime/7.13.0","Postman-Token":"381424fa-e3b3-4058-8df9-4abf9d72c899", "postmanHeader": "hello","accept-encoding": "gzip, deflate", "Content-Type": "application/x-www-form-urlencoded"}
    Native Req Payload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    Native Response Headers Response header in the outgoing response from the native service to API Gateway.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods": "GET, POST, DELETE,PUT","Connection":"close","Date": "Fri, 07 Jun 2019 12:44:13 GMT","Access-Control-Allow-Headers": "Content-Type,api_key, Authorization","Content-Type": "application/json"}
    Native Res Payload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    Operation/Resource Name Name of the operation or resource that is being invoked on the API.
    Example: /pet/{petId}
    Policy Action Name Name of the runtime policy that is enforced on the API.
    Example: Log Invocation
    Source Gateway Node Source API Gateway’s IP address.
    Example: 10.0.75.1
    Status Status of the API invocation.
    Possible values are: SUCCESS, FAILURE
    Version The system-assigned version identifier for the API.
    Example: 1.0

    Monitoring Events

    Column Description
    apiname Name of the API in which the event occurred.
    Example: SampleAPI
    alertSource The type of alert generated for the event.
    Example: Monitor
    alertType Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: Test
    apiGWHostName Name of the host which serves the request.
    Example: SAG-HS09MG2
    monitorAttr The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    applicationId The unique identifier for the consumer associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationName Name of the consumer associated with the API invocation. A consumer name is populated as unknown when API Gateway is unable to identify the consumer using a policy that is configured for the API.
    Example: SampleApplication
    Native Endpoint The endpoint URL of the native API that is being invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0

    Local Log

    The runtime events and metrics payload generated by API Gateway at run-time is published to the configured Local Log destination. The columns that make up the events and metrics data model for Local Log are listed below:

    Transactional Events

    Column Description
    apiName Name of the API in which the event occurred.
    Example: SampleAPI
    ApiVersion The system-assigned version identifier for the API.
    Example: 1.0.0
    Application ID The unique identifier for the application associated with the API invocation.
    Example: 7908eb44-d107-4670-929d-89111fc9347c
    ApplicationIP IP address of the application associated with the API invocation.
    Example: 10.60.37.42
    Application Name Name of the application associated with the API invocation. An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    Correlation ID The unique identifier that is automatically generated for every request coming to API Gateway and can be used to query the log.
    Example: MED38e9cfa4-2348-408b-9462-124b2181c1a6:656
    customFields The custom fields an API Provider can provide to log a new field and value for a transaction event.
    Example: {“customfield”:“customvalue”}
    Error Origin The origin of error.
    Example: Nativeservice
    EventSource The source where the event occurred.
    Example: API_Gateway_Instance
    Native HTTP Method The HTTP method used to invoke the native service.
    Example: GET.
    nativeRequestPayload The native service request data.
    Example: {"param1" : "value1", "param2" : 10}
    nativeResponsePayload The native service response data.
    Example: {"id":2,"category":{ "id":2, "name":"string"},"name":"pysen","photoUrls":["string"],"tags":[{"id":0, name":"string"}],"status":"available"}
    Native URL URL of the native service.
    Example: http://petstore.swagger.io/v2/pet/2
    Operation/Resource name Name of the API operation or resource that is invoked.
    Example: /pet
    Partner ID The unique identifier for the partner that generated the audit record.
    Example: unknown
    queryParams This is applicable only for REST APIs. Query parameters present in the incoming REST request.
    Example: {“status”:“available”}
    RequestHeaders Request header in the incoming request from the client.
    Example: {"Cache-Control":"max-age=0","Accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8","Upgrade-Insecure-Requests":"1","Connection":"keep-alive","User-Agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36","Host":"mcdaso02:5555","Accept-Encoding":"gzip, deflate","Accept-Language":"en-US,en;q=0.9,ta;q=0.8","Content-Type":"application/x-www-form-urlencoded"}
    ResponseHeaders Response header in the outgoing response.
    Example: {"Server":"Jetty(9.2.9.v20150224)","Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, POST, DELETE, PUT","Connection":"close","Date":"Fri, 30 Mar 2018 08:25:45 GMT","Access-Control-Allow-Headers":"Content-Type, api_key, Authorization","Content-Type":"application/xml"}
    SessionId A string the API Gateway server generates to uniquely identify each session. This is either the IS session token or the automatically generated GUID if the token is missing from the message context.
    Example: 81439d366e874bc79d9f81490e30e6e0
    Source Gateway Node Source API Gateway’s IP address.
    Example: 10.0.75.1
    TargetEPR The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55

    Monitoring Events

    Column Description
    alertDesc Text of the alert message sent to a configured destination when the performance conditions are violated. The alert message is specified in the policy definition of an API.
    Example: EnforcePolicy-HardLimit
    alertSource Name of the API Gateway policy that generated the alert message.
    Example: Unknown-Policy
    apiName Name of the API in which the event occurred.Example:
    Example: SampleAPI
    apiVersion The system-assigned version identifier for the API.
    Example: 1.0
    applicationIdThe unique identifier for the application associated with the API invocation.
    Example: c0f84954-9732-11e5-b9f4-f159eafe47b2
    applicationIp IP address of the application associated with the API invocation.
    Example: 10.20.248.33
    applicationName Name of the application associated with the API invocation.
    An application name is populated as unknown when API Gateway is unable to identify the application using a security policy that is configured for the API.
    Example: SampleApplication
    creationDate Date and time when the event was generated in API Gateway.
    Example: 1501671101509
    eventType The type of event that occurred.
    Example: Policy Violation Event
    monitorAttr The monitored attribute which has breached the configured SLA.
    Example: AVGRESPONSETIME GT 1.0, SUCCESSCOUNT EQ 3, REQUESTCOUNT GT 10
    Native Endpoint The endpoint URL of the native API that is invoked.
    Example: http://petstore.swagger.io/v2/pet/55
    Operation/Resource name Name of the API operation or resource that is invoked.
    Example: /pet

    Security Configuration

    You must have the API Gateway’s manage security configurations functional privilege assigned to perform the following tasks in the security configuration section of API Gateway:

    Keystore and Truststore

    Keystores and truststores are secure files with industry-standard file formats. The keystore file stores the private keys and SSL certificates and the truststore file stores the trusted roots for the certificates.

    A keystore file contains one or more pairs of a private key and signed certificate for its corresponding public key. The keystore should be strongly protected with a password, and stored (either on the file system or elsewhere) so that it is accessible only to administrators.

    The truststore file functions as a database containing all the public keys for CAs within a specified trusted directory.

    To enable the two-way SSL for an API Gateway service, you must add a valid, authorized X.509 certificate along with the private key in a keystore file, and the certificate of the client or partner in the truststore file. These keystore and truststore files have to referred to in the HTTPs port that is used to access the API Gateway service.

    API Gateway has a sample keystore that contains self-signed certificates. Software AG recommends not to use them for configuring SSL communication with API Gateway in a production environment.

    Configuring Keystore Information

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

    2. Select General > Security.
      A list of existing keystores and truststores and corresponding details are displayed.

    3. In the Keystores section, click Add keystore.

    4. In the Create keystore section, provide the following information:

      Field Description
      Alias A text identifier for the keystore file.

      The alias name can contain only letters, numbers and underscores. It can not include a space, hyphen and special characters.

      The keystore contains the private keys and certificates (including the associated public keys) for an Integration Server, partner application, or Integration Server component.
      Select file Select a keystore file of the specified type using Browse. Select the required file and upload it.
      Password Password for the saved keystore file associated with this alias.
      Type The certificate file format of the keystore file, which by default is JKS for keystores. You can also use PKCS12 format for a keystore.
      Description Optional. A text description for the keystore alias.
    5. Click OK.
      All the key aliases in the uploaded file are listed.

    6. Type a password for the required key alias.

    7. Click Save.
      The keystore is configured and the alias listed in the keystore alias table.

      Note
      If a wrong password has been provided for the keystore or one of its aliases, API Gateway saves the keystore but it is not loaded. The keystore alias is displayed as the loaded icon with an X mark in the keystore listing.

    Modifying Keystore Information

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

    2. Select General > Security.
      A list of keystores and truststores and corresponding details are displayed.

    3. Click the keystore alias to be updated.
      The update keystore section is displayed.

    4. Modify the fields as required.

    5. Click Save.
      The set of available aliases is displayed.

      Note
      If the keystore file is not updated during the edit, then clicking Save closes the form. If a different keystore file is uploaded, then the list of aliases in the file is loaded and you are prompted to configure the passwords for the aliases.
    6. Type a password for the alias to be configured.

    7. Click Save.
      The keystore is updated.

    Deleting Keystore Information

    Be careful while deleting the keystore information. If the keystore and one of its key aliases is configured in the keystore settings and the keystore gets deleted, then the configuration would have issues.

    To delete keystore information

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

    2. Select General > Security.
      A list of keystores and truststores and corresponding details are displayed.

    3. Click icon in the action column of the keystore to be deleted.

    4. Click Yes in the confirmation dialog.
      The keystore is deleted from the list.

    Configuring Truststore Information

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

    2. Select General > Security.
      A list of existing keystores and truststores and corresponding details are displayed.

    3. In the Truststores section, click Add truststore.

    4. In the Create truststore section, provide the following information:

      Field Description
      Name A name for the truststore file.

      The alias name can contain only letters, numbers and underscores. It can not include a space, hyphen and special characters.

      The truststore contains the trusted CA certificates for an Integration Server, partner application, or Integration Server component.
      Upload truststore file Select a truststore file of the specified type using Browse. Select the required file and upload it.

      Note: Supports only JKS file format.
      Password Password that is used to protect the contents of the truststore.

      This password must have been defined at truststore creation time using a keystore utility.

      Make sure you have the truststore password available when managing its corresponding truststore alias.
      Description Optional. A text description for the truststore alias.
    5. Click Save.
      The truststore is configured and the alias listed in the truststore alias table.

      Note
      If a wrong password has been entered for the truststore, API Gateway saves the truststore but it is not loaded. The truststore alias is displayed as the loaded icon with an X mark in the truststore listing.

    Modifying Truststore Information

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

    2. Select General > Security.
      A list of keystores and truststores and corresponding details are displayed.

    3. Click the truststore alias to be updated.
      The update truststore section is displayed.

    4. Modify the fields as required.

    5. Click Save.
      The truststore is updated.

    Deleting Truststore Information

    Be careful while deleting the truststore information. If the truststore settings and the truststore gets deleted, then the configuration would have issues.

    To delete keystore information

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

    2. Select General > Security.
      A list of keystores and truststores and corresponding details are displayed.

    3. Click icon in the action column of the truststore to be deleted.

    4. Click Yes in the confirmation dialog.
      The truststore is deleted from the list.

    Configuring Keystore and Truststore Information for Inbound Messages

    API Gateway includes a list of SSL keystores and truststores.

    You might want to configure API Gateway to refer to a default keystore, truststore, or both, before deploying any SOAP message flows that require signature, encryption, X.509 authentication, and so on, as configured in the Inbound Authentication - Message policy. The default keystore and truststore are that you want API Gateway to use for the incoming secured messages.

    To configure Keystore and truststore settings for inbound messages

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

    2. Select General > Security. A list of existing keystores and truststores loaded during startup and those created in API Gateway and corresponding details appears.

    3. To configure API Gateway’s default keystore and truststore alias for incoming secured messages, provide the following information in the Configure keystore and truststore settings section:

      Field Description
      Keystore alias Select a keystore that API Gateway uses for incoming message-level security. Lists all available keystores. If you have not configured any keystore, the list is empty.
      Key alias (signing) Select the alias for the private key to sign the outgoing response from API Gateway to the original client. This alias value validates the inbound requests to API Gateway and signs the outgoing response from API Gateway to the original client. It is auto-populated based on the keystore selected. This field lists all the aliases available in the chosen keystore. If there are no configured keystores, this field is empty. This field is auto-populated based on the selected keystore alias. It lists all the aliases available in the chosen keystore. If there are no configured keystores, this field is empty.
      Truststore alias The alias for the truststore that contains the list of CA certificates that API Gateway uses to validate the trust relationship with the client.
    4. Click Save.

    Post-requisites: While securing the SOAP APIs using WS-Security policies, perform the following:

     a. Restart the server after configuring keystore and truststore information for the configuration to take effect.
    
     b. Deactivate the APIs that have Inbound Authentication - Message policy enforced.
    
     c. Update the keystore and truststore configuration.
    
     d. Activate the APIs that were deactivated.

    Configuring Keystore and Truststore Information for Outbound Connections

    You might want to configure API Gateway to refer to a default truststore that you want API Gateway to use for securing outgoing SSL connections. The keystore and key alias can be configured for outgoing two-way SSL connections. During the SSL handshake between API Gateway and the native API, the server certificate, which is sent by the native API, has to be validated against a truststore in API Gateway.

    To configure keystore and truststore settings for outbound secured connections

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

    2. Select General > Security. A list of existing keystores and truststores loaded during startup, and those created in API Gateway and the corresponding details appears.

    3. To configure API Gateway’s default keystore and truststore alias for outgoing secured connections, provide the following information in the Configure keystore and truststore settings for outbound connections section:

      Field Description
      Keystore alias Select a keystore that API Gateway uses for outgoing secured connections. Lists all available keystores. If you have not configured any keystore, the list is empty.
      Key alias Select the alias for the private key for an outbound connection from API Gateway to the native API. This field is auto-populated based on the selected keystore alias. It lists all the aliases available in the chosen keystore. If there are no configured keystores, this field is empty.
      Truststore alias The alias for the truststore that contains the list of CA certificates that API Gateway uses to validate the trust relationship with the native API.
      If you do not configure any truststore alias, it implies that API Gateway does not validate the certificates provided by native APIs.
    4. Click Save.

    Global IP Access Settings For Ports

    This section describes how to specify the global IP access setting for ports. Here you can restrict the client IP address based on the authentication failure in API Gateway.

    Configuring Restriction to IP Address based on Authentication

    You must have the Manage Security Configuration functional privilege to configure this restriction.

    You can configure the restriction to client IP address based on authentication failure in API Gateway to prevent malicious attack that occurs when a client floods a server with many requests in an attempt to interfere with server processing. This restriction prevents the malicious attack by blocking or denying the unauthenticated client from accessing the APIs, when API Gateway fails to authenticate the client. Using API Gateway, you can limit the number of times a client fails to authenticate the API in a specified time interval. The reason for authentication failure can be either of the following:

    When the above mentioned authentication failure occurs, API Gateway sends the 401 or 403 error message to the client.

    When API Gateway detects that the failed authentication limit has been exceeded, it blocks or denies that particular client IP address from accessing any of the APIs and sends the 403 Forbidden error to the client.

    Note
  • If an API is enforced with Identify and Access Application policy, and if the invocation fails due to non-preemptive authentication failure. API Gateway does not take such non-preemptive authentication failure into count and increase the failed authentication count.

  • When you use Load Balancer for configuring high availability between the API Gateway instances, API Gateway honours the X-Forwarded-For (XFF) header from the client. As the XFF header has the actual client IP address, API Gateway can block or deny the problematic client from accessing the protected API based on your configuration.
  • To configure restriction to IP address based on authentication

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

    2. Select Security > Global IP Access Settings.

    3. Click Authentication based restrictions - Block/Deny by IP address section and provide the following information.

      Field Description
      Enable Specifies whether restriction to IP address based on authentication is enabled. Click the toggle button to change the state to to enable IP address restriction.By default this option is disabled.
      Maximum failed authentication Specifies the maximum number of failed authentication that API Gateway can accept from a specific IP address in a given time interval.
      In (seconds) Specifies the time interval, in seconds, in which maximum authentication failure can be permitted.
      Action when limit exceeds Specifies the action to be performed when the number of failed authentication from an IP address exceeds the specified limits. Select one of the following:
      • Add IP address to deny list - Permanently denies the IP address from accessing any APIs.
      • Block the IP address - Temporarily blocks the IP address from accessing any APIs for specified time interval.
      • In (seconds). Specify the time interval for which you want to block the IP address.
      Denied IP list Specifies the list of IP addresses that are denied from access. Click in the Action column to remove an IP address from the denied list.
    4. Click Save. The configuration is saved.

    SAML Issuer

    If a native API is enforced with the SAML policy, API Gateway uses this configuration to communicate to STS (Security Token Service) to retrieve the SAML token.

    To add a SAML issuer

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

    2. Select Security > SAML issuer.
      The SAML issuer page lists all the issuers configured along with the Endpoint URI corresponding to each SAML issuer, if any.

    3. Click Add SAML issuer.

    4. In the Add SAML issuer section, provide the following information:

      Field Description
      Name Name of a SAML token issuer used by API Gateway.

      This value must match the value of the Issuer field in the SAML assertion.
      Normal client Selecting this sets the client that requests the SAML token.
      Act as delegation Selecting this delegates the SAML request to another user (delegator).

      The delegator uses a signature element to authenticate the SAML request.
      Issuer policy

      Specifies the name of an issuer policy to be used to communicate with SAML issuer.

      • If a value is specified for the Issuer policy field, then the selected issuer policy is applied to all APIs that are using the SAML authentication.

      • If a value is NOT specified for this field, then a default issuer policy based on the WSS Username or Kerberos communication mode is applied to all APIs.
      Communicate using. Specifies the mode of communication.
      WSS Username Specifies that WSS Username mode is used to obtain the SAML assertion to access the API. The WSS username token supplied in the header of the SOAP request that the consumer application submits to the API.
      Kerberos Specifies that Kerberos mode is used to obtain the SAML token and assertion to access the API. Transports the Kerberos token over the Transport Layer Security (TLS) protocol to provide additional security features.
      Authenticate using. Specify the type of authentication you want to use while communicating with the SAML issuer.
      For the Authentication type WSS Username, authenticate using the following:
      Custom credentials Specifies the values provided in the policy required to communicate the SAML issuer.

      Provide the following information:

      • Username. Specify a username.

      • Password. Specify a password.

      • Domain. Specify a domain.
      For the Authentication type Kerberos, authenticate using any of the following:
      Custom credentials Specifies the values provided in the policy required to communicate the SAML issuer.

      Provide the following information:

      • Client principal. A valid client LDAP user name.

      • Client password. A valid password of the client LDAP user.

      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.

      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:

        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.

        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Delegate incoming credentials Specifies the values provided in the policy required by the API providers to select whether to delegate the incoming Kerberos token or act as a normal client.

      Provide the following information:

      • Client principal. A valid client LDAP user name.

      • Client password. A valid password of the client LDAP user.

      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.

      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Select one of the following:

        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.

        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Incoming HTTP basic auth credentials Specifies the incoming HTTP basic authentication credentials in the transport header of the incoming request for client principal and client password.

      Provide the following information:

      • Service principal. A valid Service Principal Name (SPN). The specified value is used by the client to obtain a service ticket from the KDC server.

      • Service principal nameform. Specifies the format in which you want to specify the principal name of the service that is registered with the principal database. Available values are:

        • Username. Represents the principal name as a named user defined in LDAP used for authentication to the KDC.

        • Hostbased. Represents the principal name using the service name and the host name, where host name is the host computer.
      Endpoint URI Provide the endpoint URI of the STS.
      SAML version Specify the SAML version to be used for authentication.

      Available values are: SAML 1.1, SAML 2.0.
      WS-Trust version Specify the WS-Trust version that API Gateway must use to send the RST to the SAML issuer.

      Available values are: WS-Trust 1.0, WS-Trust 1.3.
      Applies to Specify the scope for which this security token is required.

      For example, the APIs to which this token is applied.
      Signing configurations
      Keystore alias Specify the keystore to be used by API Gateway while sending the request to the STS.

      A keystore is a repository of private keys and corresponding public certificates.
      Key alias (signing) Specify the key alias, a private key used to sign the request sent to STS.
      Encryption configurations
      Truststore alias Select the truststore that should be used by API Gateway while sending the STS request.

      Truststore is a repository that holds all the trusted public certificates.
      Certificate alias (Encryption) Select the certificate from the truststore used to encrypt the request that is sent to the STS.
      Request security token template parameters. Defines extensions to the <wst:RequestSecurityToken> element for requesting specific types of keys, algorithms, or key and algorithms, as specified by a given policy in the return token(s).
      Key Specifies the key type of the security token template.
      Value Specifies a value for the request token.

      You can add multiple key and values by clicking icon.
    5. Click Add.
      This adds the SAML issuer and it is listed in the SAML issuers list.

    Custom Assertions

    API Gateway uses WS-Security (WSS) to provide message-level security and protection for SOAP message requests from a client to an API, and SOAP message responses from an API to a client. By default, API Gateway supports the WSS policies like Username, X.509 certificate, Security Assertion Markup Language (SAML), Kerberos, Encryption, and so on, for the request or response SOAP messages, or both.

    API Gateway also provides an extension to define and use custom policy assertions. Custom assertions allow the API providers to extend and provide additional security policies that are not available by default in API Gateway.

    In WS-Security, custom assertions are used for expressing individual security requirements, constraints, or both. The individual policy assertions can be combined to create security policies that ensure secure and reliable exchanges of SOAP messages between a client and a SOAP API.

    API Gateway supports the following assertion types for enforcing a custom security policy:

    Binding Assertions

    These assertions specify the security mechanism that is to be used by the client or API such as the keys being used, algorithms, and so on. Common properties used by other assertions are also defined in the security binding assertion.

    API Gateway supports the following WS-SecurityPolicy binding assertions:

    Binding Assertion Description
    Transport Binding This assertion is used when the message is protected at the transport level. In this binding, messages are exchanged only through a defined medium, for example, HTTPS.

    Note: By default, API Gateway uses the transport binding for Kerberos authentication.
    Asymmetric Binding This assertion is used when both the initiator and the recipient possess security tokens. In this binding, initiator uses it’s private key to sign and the recipient’s public key to encrypt. Recipient uses it’s private key to decrypt and initiator’s public key to verify the signature.

    Note: By default, API Gateway uses the asymmetric binding for the security policies.
    Symmetric Binding This assertion is used when only the initiator or recipient has a security token. In this binding, both the signing and encrypting of messages is done using a single security token.

    Token Assertions

    These assertions specify the types of tokens to be used to authenticate and secure SOAP messages.

    API Gateway supports the following WS-SecurityPolicy token assertions:

    Token Assertion Description
    Username Token When using this assertion, the message-level security is implemented using a WSS username token. The assertion authenticates a client using the username and password in the SOAP request. If validation of the username token succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
    X509 Token When using this assertion, the message-level security is implemented using an X.509v3 certificate. The assertion authenticates a client using the X.509v3 certificate in the SOAP request. If validation of the X.509v3 certificate succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
    Kerberos Token When using this assertion, the message-level security is implemented using a Kerberos token. The assertion authenticates a client using the Kerberos token in the SOAP request. If validation of the Kerberos token succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.
    SAML Token When using this assertion, the message-level security is implemented using a SAML (Security Assertions Markup Language\ token. SAML is a standard data format for exchanging authentication and authorization data between the client and the SOAP API. If validation of the SAML token succeeds, then API Gateway passes the message to the API. If validation fails, then API Gateway returns a SOAP fault.

    Note: API Gateway supports both the SAML 1.1 and 2.0 standards.

    Policy Assertions

    API Gateway allows you to even define a complete custom policy assertion. For example, a policy assertion might specify a symmetric binding and the security token types that are used to digitally sign or encrypt SOAP messages between the client and API.

    Creating a Custom Assertion

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add a custom assertion.

    You might want to create a custom assertion when you want to:

    Important
    When creating a custom assertion, make sure that both the syntax and the semantics of the assertion element are valid and in compliance with the Web Services Security Policy specification.

    To create a custom assertion

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

    2. Select Security > Custom assertions.
      API Gateway displays a list of all the currently defined policy assertions.

    3. Click Add assertion.

    4. Select the assertion type.
      The available options are:

      • Binding

      • Token

      • Policy

    5. Provide the following information:

      Field Description
      Name Name of the custom assertion. For a binding or token assertion type, this is the display name of the assertion in the Binding Assertion field or Custom Token Assertion of the Inbound Authentication - Message policy.

      For a policy assertion type, this is the display name of the assertion in the Issuer Policy field of the Add SAML Issuer configuration page.
      Select file Click Browse and select the policy assertion file to be uploaded. The Assertion element text box displays the data from the assertion file.

      If you have uploaded the policy assertion file and want to replace it, click the Delete icon.
      Assertion element If you have not uploaded the policy assertion file, provide the XML representation of assertion.
    6. Click Add. The custom assertion is added. You can create as many custom assertions you require.

    Post-requisites:

    To enforce the custom binding or token assertion in an API, select the assertion in the appropriate fields of the Inbound Authentication - Message policy:

    To enforce the custom policy assertion in an API, select the assertion and the corresponding SAML issuer in the appropriate fields:

    Viewing Custom Assertion List and Assertion Configuration

    You can view the list of configured custom assertions in API Gateway. In addition, you can view and modify the configuration in the individual custom assertion details page.

    To view a list of custom assertions and assertion configuration

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.
      You can delete a custom assertion by clicking its Delete icon.

    3. Click any custom assertion to view the configuration details.
      The custom assertion details page displays the XML element.

    Modifying Custom Assertion

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to modify a policy assertion.

    You might want to modify a custom assertion to change the currently defined security settings, such as, authentication scheme, signing and encryption, algorithms and supporting tokens, of SOAP messages.

    To modify a custom assertion

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.

    3. Select the required custom assertion that you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The custom assertion is updated.

    Post-requisites:

    When you are ready to put the policy assertion into effect in an API, select it in the appropriate field of Inbound Authentication - Message policy.

    Deleting Custom Assertion

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to delete a policy assertion.

    You delete a policy assertion to remove it from API Gateway permanently.

    To delete a policy assertion

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.

    3. Click icon in the action column of the custom assertion to be deleted.

    4. Click Yes in the confirmation dialog.
      The custom assertion is deleted from API Gateway.

    Example - Custom Assertions

    API Gateway, by default, uses the asymmetric binding assertion with X.509v3 token for implementing SOAP message protection. If you would like to enforce any authentication (other than the predefined authentications shipped with API Gateway), include additional WSS custom assertions, sign and encrypt SOAP messages, and define custom properties, such as the algorithms and layout of security header, you can create custom assertions that would construct the custom policy file to suit your specific security requirements.

    Following is a policy file that API Gateway generates when a WSS username token is enforced by the Inbound Authentication Message policy for an API.

    
    <wsp:Policy wsu:Id="9dbda2fb-9cef-4ff9-bc70-115c942a3b76" 
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
         oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
            <wsp:All>
    (L01) <sp:AsymmetricBinding xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:InitiatorToken>
                <wsp:Policy>
                    <sp:X509Token sp:IncludeToken
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
                                                                /IncludeToken/Never">
        <wsp:Policy>
                    <sp:WssX509V3Token10 />
                </wsp:Policy>
            </sp:X509Token>
        </wsp:Policy>
        </sp:InitiatorToken>
        <sp:RecipientToken>
            <wsp:Policy>
                <sp:X509Token sp:IncludeToken=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy
                 /200702/IncludeToken/Never">
            <wsp:Policy>
                <sp:WssX509V3Token10 />
            </wsp:Policy>
                </sp:X509Token>
                    </wsp:Policy>
                        </sp:RecipientToken>
                        <sp:AlgorithmSuite>
                            <wsp:Policy>
                                <sp:TripleDesRsa15 />
                            </wsp:Policy>
                        </sp:AlgorithmSuite>
        <sp:Layout>
            <wsp:Policy>
            <sp:Strict />
            </wsp:Policy>
        </sp:Layout>
            <sp:ProtectTokens/>
            </wsp:Policy>
            </sp:AsymmetricBinding>
            <sp:SupportingTokens xmlns:sp=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
            <wsp:Policy>
                <sp:UsernameToken sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                 IncludeToken/AlwaysToRecipient"/>
                    </wsp:Policy>
                        </sp:SupportingTokens>
                    </wsp:All>
                </wsp:ExactlyOne>
        </wsp:Policy>
    
    

    You might have a requirement to change the policy assertion that is available by default in API Gateway. For example, you might want to generate the above security policy using a symmetric binding instead of the default asymmetric binding, and modify the username token that is defined by default as a supporting token to a signed supporting token. You could then create custom policy assertions to achieve these specific requirements.

    Important
    When adding a custom policy assertion, make sure that both the syntax and the semantics of the assertion are valid and in compliance with the Web Services Security Policy specification.

    Symmetric Binding Assertion

    You might want to use a symmetric binding (instead of the default asymmetric binding) when only API Gateway possess the X.509v3 token for authentication. You might also want to sign and encrypt the SOAP messages, modify the encryption algorithm, and include timestamp on the SOAP messages. You would then create a custom binding assertion with the specific property lines:

    
        
    <sp:SymmetricBinding
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsp:Policy>
    <sp:ProtectionToken>
    <wsp:Policy>
    <sp:X509Token sp:IncludeToken=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
     IncludeToken/AlwaysToRecipient">
        <wsp:Policy>
        <sp:WssX509V3Token10/>
        <sp:WssX509PkiPathV1Token10/>
        </wsp:Policy>
        </sp:X509Token>
        </wsp:Policy>
        </sp:ProtectionToken>
        <sp:AlgorithmSuite>
        <wsp:Policy>
        <sp:TripleDesRsa15/>
        </wsp:Policy>
        </sp:AlgorithmSuite>
        <sp:Layout>
        <wsp:Policy>
        <sp:Strict/>
        </wsp:Policy>
        </sp:Layout>
        <sp:IncludeTimestamp/>
        <sp:ProtectTokens/>
        <sp:OnlySignEntireHeadersAndBody/>
        <sp:SignBeforeEncrypting/>
        </wsp:Policy>
        </sp:SymmetricBinding>
        
    

    You could create custom assertions to include one or more of the following security requirements:

    Supporting Token Assertions

    You might want to sign the supporting token for example, WSS username token, and use SignedSupportingTokens assertion. You might also want to specify that the signed username token must always be included in the messages sent to the recipient. You would then create a custom token assertion with the specific property lines:

    
        
    <sp:SignedSupportingTokens xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
        <wsp:Policy>
            <sp:UsernameToken sp:IncludeToken=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                                             IncludeToken/AlwaysToRecipient"/>
                </wsp:Policy>
            </sp:SignedSupportingTokens>
        
    

    WSS Token Assertions

    You might want to include WSS10 and WSS11 assertions to provide additional SOAP message security. You would then create two separate custom token assertions with the specific property lines:

    Wss10 assertion:

    
    <sp:Wss10
            xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
    </sp:Wss10>
        
    

    Wss11 assertion:

    
        
    <sp:Wss11
        xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:MustSupportRefIssuerSerial/>
            <sp:MustSupportRefThumbprint/>
            <sp:RequireSignatureConfirmation/>
        </wsp:Policy>
    </sp:Wss11>
        
    

    After you have defined these custom assertions in API Gateway, execution of a policy that is configured with all of these custom assertions in the Inbound Authentication - Message policy, would construct the custom security policy file as follows:

    
        
    <wsp:Policy wsu:Id="1e747a18-b55d-4e99-ac67-80a8eafd76b3"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                 oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:SymmetricBinding xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
            <wsp:Policy>
                <sp:ProtectionToken>
            <wsp:Policy>
            <sp:X509Token sp:IncludeToken=
            "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
             IncludeToken/AlwaysToRecipient">
                        <wsp:Policy>
                            <sp:WssX509PkiPathV1Token10/>
                        </wsp:Policy>
            </sp:X509Token>
            </wsp:Policy>
        </sp:ProtectionToken>
        <sp:AlgorithmSuite>
                    <wsp:Policy>
                        <sp:TripleDesRsa15/>
                    </wsp:Policy>
        </sp:AlgorithmSuite>
        <sp:Layout>
        <wsp:Policy>
                <sp:Strict/>
        </wsp:Policy>
        </sp:Layout>
        <sp:OnlySignEntireHeadersAndBody/>
        </wsp:Policy>
        </sp:SymmetricBinding>
        <sp:SignedSupportingTokens xmlns:sp=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                    <wsp:Policy>
                        <sp:UsernameToken sp:IncludeToken=
                        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                     IncludeToken/AlwaysToRecipient"/>
                    </wsp:Policy>
        </sp:SignedSupportingTokens>
                    <sp:Wss11 xmlns:sp=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                    <wsp:Policy>
                    <sp:MustSupportRefIssuerSerial/>
                    <sp:MustSupportRefThumbprint/>
                    <sp:RequireSignatureConfirmation/>
        </wsp:Policy>
        </sp:Wss11>
                    <sp:Wss10 xmlns:sp=
                            "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                        <wsp:Policy>
                        <sp:MustSupportRefIssuerSerial/>
                        </wsp:Policy>
                    </sp:Wss10>
                    <sp:EncryptedParts xmlns:sp
                        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                        <sp:Body/> 
                    </sp:EncryptedParts>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    
    

    Kerberos Settings

    Kerberos is an authentication protocol that uses symmetric encryption and a trusted third party system to validate the identity of clients. The Kerberos protocol provides authentication over open and insecure networks in which communication between the hosts can be intercepted.

    You can use API Gateway to configure Kerberos authentication for API requests. API Gateway provides support for using Kerberos authentication for inbound and outbound HTTP and HTTPs requests at the transport and the message level.

    Kerberos authentication system consists of the a Kerberos client that needs to access and use Kerberos services, a trusted third-party system, specifically a Key Distribution Center (KDC) and a server that hosts APIs that are accessible using Kerberos authentication.

    Configuring API Gateway to Use Kerberos

    Before you configure API Gateway to use Kerberos authentication, ensure that:

    To configure API Gateway to use Kerberos

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

    2. Select Security > Kerberos.

    3. Click Edit.

    4. Provide or modify the following information as required:

      Field Description
      Realm Optional. The domain name of the Kerberos server, in uppercase letters.

      Note: A value specified for Realm overwrites the realm set in the KDC configuration file specified in Kerberos configuration file.
      Key distribution center Optional. The host name of the machine on which the KDC resides.

      A value specified for Key distribution center overwrites the default key distribution center set in the KDC configuration file specified in Configuration file.
      Configuration file The location of the Kerberos configuration file that contains the Kerberos configuration information, including the locations of KDCs, defaults for the realm and for Kerberos applications, and the host names and Kerberos realms mappings.
      Use subject credentials Specifies whether API Gateway requires a Kerberos V5 Generic Security Services (GSS) mechanism to obtain the necessary credentials from an existing subject set up by the JAAS authentication module. Here, subject represents the user or service being authenticated in the JAAS login context.
    5. Click OK.

    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.

    Configuring the Internal Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add an authorization server.

    You have to configure API Gateway with the required information to act as an internal authorization server for OAuth or JWT depending on what authentication protocol you want to use to identify and authorize a client application. You can also define the required scopes that provide a way to limit the amount of access that is granted to an access token.

    To configure an internal authorization server

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

    2. Select Security > OAuth/JWT/OpenID.

    3. In the Internal Authorization servers section, click local. This is the internal authorization server available that you can configure with required information to act as an internal authorization server for OAuth, JWT or OpenID authentication protocols.

    4. The name field is pre-populated with the name of the internal authorization server, local, which is non-editable.

    5. The description for the internal authorization server is pre-populated with the description available. You can modify the description as required.

    6. Click JWT configuration to configure API Gateway as a JWT issuer. Alternatively you can expand or collapse a section, using the down arrow icon and the up arrow icon and that appear next to the section name.

    7. Provide the following information as required:

      Field Description
      Token issuer Name of the JWT token issuer used by API Gateway.

      Note: The Token issuer value is case-sensitive.
      Algorithm The cryptographic algorithm to sign JSON Web Tokens (JWTs).

      Supported values are: RS256, RS384, and RS512.
      Expiry duration The duration (in minutes) for which the token is valid.

      For example, the value 60 denotes that the access token will expire in one hour from the time the token was generated.
      Audience Optional. The intended recipient of the token. The application that receives the token must verify that the audience value is correct and reject any tokens intended for a different audience.
      Keystore alias Alias of the keystore containing the private key that is used to sign JWTs.

      The Keystore alias field contains a list of the available keystore aliases in API Gateway. If there are no configured keystore aliases, this field displays the DEFAULT_IS_KEYSTORE.
      Key alias Alias of the private key used to sign JWTs.

      The Key alias field contains a list of the available aliases in the selected keystore. If there are no configured keystores, this field is empty.
    8. Click OAuth configuration to configure API Gateway as an OAuth authorization server. Alternatively you can expand or collapse a section, using the down arrow icon and the up arrow icon and that appear next to the section name.

    9. Provide the following information as required:

      • Authorization code expiration interval. Specifies the time (in seconds) during which the authorization code issued by the authorization server is valid. Valid values are between 1 and 2147483647. The default value is 600.

      • Access token expiration interval. Specifies the time (in seconds) for which the access tokens issued by the authorization server are valid. The default value is 3600. Value of -1 specifies that the access token does not expire.

    10. Click OAuth tokens.

      This lists the available OAuth tokens with the following details:

      • Client ID. Specifies the ID of the client application that requested the access token.

      • Owner ID. Specifies the ID of the owner who issues the access token.

      • Access token. Specifies the access token.

      • Refresh token. You can use to generate a new access token if the existing access token is expired.

      • Remaining refresh limit. Displays the remaining attempts for refreshing the access token.

      • Action. Revokes the access tokens, which means those tokens cannot be used to invoke the protected resource. For information about revoking access token using REST API, see Revoking OAuth Tokens.

      Note
      By default, API Gateway lists only 5 records and provides pagination to explore more tokens. You can also use the search and filter options to find the OAuth tokens.
    11. Click OAuth scopes.
      OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client application may be granted READ and WRITE access to the protected resources, or just the READ access. You can implement your APIs to enforce any scope or a combination of scopes as required. So, if a client receives a token that has READ scope, and it tries to invoke an API endpoint that requires WRITE access, the invocation fails.

      You can provide the meaning to the scope in OAuth/OpenID scopes management section.

    12. Type the scope that is registered in the authorization server and click +Add.
      You can include multiple scopes.

    13. Click Update.
      This updates the internal authorization server details with the required information and is listed in the table of Internal authorization server.

    Adding a Provider

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add a provider.

    The OAuth 2.0 configuration in API Gateway is split into two sections - Providers and Authorization servers.

    You have to add a provider and configure the authorization provider metadata information in this section for API Gateway to communicate with this provider during dynamic client registration only. If there is any deviation from the actual OAuth specification then the provider has to be configured for these deviations.

    To add a provider

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

    2. Select Security > JWT/OAuth/OpenID > Providers.

    3. Click Add provider and provide the following information:

      Field Description
      Name Name of a third-party provider. For example, Amazon.

      You can also use one of the following pre-configured third-party providers that is shipped with the API Gateway installation:

      • PingFederate

      • OKTA
      Client metadata field mapping. Specifies the mapping of dynamic client registration specification to that of the client implementation of the provider.

      The Client metadata field mapping fields are required when you are adding a third-party provider that is not shipped with API Gateway.
      Specification name The client metadata attributes in accordance with the dynamic client registration specification as defined in RFC 7591. The available values are:

      • redirect_uris. Redirection URL that the authorization server uses to redirect the authorization code once the authorization request is approved by end user.
        Note: If you do not specify this attribute, API Gateway automatically generates the URL.

      • token_endpoint_auth_method. The client authentication method at the token endpoint.

      • grant_types. The grant type of authorization flow to obtain authorization codes, ID tokens, and refresh tokens.

      • application_type

      • response_types. The type of response that the client application uses at the authorization endpoint.

      • client_name. Name of the client to use to represent the client application to the end user during authorization.

      • client_uri. URL of the client application.

      • logo_uri. URL of an image to use to represent the client application to the end user during authorization.
        Note: The logo_uri is currently not supported in API Gateway.

      • scope. List of user-authorized scopes that the client uses for requesting access tokens.
        Note: If you do not specify this attribute, the authorization server registers the client with a default set of scopes.

      • contacts. The means (for example, Email address) by which end users can contact the client for support requests.

      • tos_uri. URL of the service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client.
        Note: The tos_uri is currently not supported in API Gateway.

      • jwks_uri. URL of the JSON Web Key (JWK) Set document containing the client’s public keys.
        Note: The jwks_uri is currently not supported in API Gateway.

      • client_id. Identifier that is unique to the client application.

      • client_secret. The password or phrase for the client application to use to authorize communication with the end user.
      Implementation name The client metadata attributes that are used by the authorization server, but are not in accordance with the dynamic client registration specification.

      Example:

      • For the redirect_uris field, provide the value redirectUris.

      • For the grant_types field, provide the value grantTypes.

      • For the client_name field, provide the value name.

      • For the logo_uri field, provide the value logoUrl.

      • For the client_id field, provide the value clientId.

      • For the client_secret field, provide the value secret.
      Extended request parameters. Specifies the additional client metadata attributes that are specific to the authorization server, and are not specified in the dynamic client registration specification.

      In PingFederate (For example): forceSecretChange = true
      Type Specifies the client metadata attribute type. The available values are: Client read, Client registration, Client update, Client delete.
      Key The client metadata attribute key that is specific to the authorization server.
      Value A value for the client metadata attribute key. When sending requests to the authorization server, this value is appended to all requests.
      You can add multiple request parameters by clicking + Add.
      Application profile Specifies the application profile that is specific to the authorization server.
      Type Specifies custom application type other than web and native.
      By default, the web and native application is added.
      You can add multiple application type by clicking + Add. You can also modify and delete the added application type by clicking the respective Edit or Delete icon.
      You can add multiple request parameters by clicking + Add.

    4. Click Save.
      The provider is added and displayed in the list of providers.

    Adding an External Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add 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. To use an external authorization server, you must configure your third-party authorization server.

    To add an external authorization server

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

    2. Select Security > OAuth/JWT/OpenID.
      The available and configured internal authorization servers and external authorization servers are listed in the respective sections.

    3. Click Add authorization server in the External authorization servers section.

    4. Type a name for the external authorization server.

    5. Type a description for the external authorization server that is being configured.

    6. Provide the discovery endpoint in the Discovery URL field and click Discover.
      When you specify the discovery URL, API Gateway fetches data from the URL response and auto-populates the fields with the fetched data.

    7. Click Introspection and provide the following information to validate the incoming tokens.

      Field Description
      Local introspection. Provide the following information to validate the tokens locally.
      Issuer Name of the token issuer.
      JWKS URI Specifies JSON Web Key Signature endpoint to retrieve the corresponding public certificates for performing local introspection.
      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.
      Truststore alias Specify the alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.

      This is required if the JWKS URI is not available for the authorization server and you want to configure this certificate directly.
      Certificate alias Alias of the certificate used to validate the token.

      The Certificate alias field contains a list of the available aliases in the selected truststore. If there are no configured truststores, this field is empty.
      Remote introspection. Provide the following information to validate the tokens remotely if local introspection cannot be done.
      Introspection endpoint URL of the token introspection endpoint of a third-party OAuth 2.0 authorization server. API Gateway uses the introspection endpoint to check that access tokens used in client requests are currently active and are valid to invoke the protected resources.
      Gateway user The name of the Gateway user that API Gateway uses to invoke the token introspection endpoint.
      Client ID ID of the introspection client on the authorization server that API Gateway uses to introspect the access tokens.
      Client secret Password of the introspection client that API Gateway uses to introspect the access tokens.
    8. In the Dynamic client registration section, provide the following information if you want to dynamically create a client from API Gateway when required. You would use this configuration only if you do not intend to use any of the existing clients.

      Field Description
      Enabled Specifies whether dynamic client registration is enabled.

      Click the toggle button to change the state to icon to enable dynamic client registration.

      By default this option is disabled.
      Provider name Select the name of the third-party provider.
      Client registration URL Specifies the corresponding REST endpoint URLs for the client configuration of REST APIs.
      Authentication type Specifies the type of authentication scheme that API Gateway would use to communicate with the external authorization server for client management.

      Select one of the following authentication type:

      • Basic. Specifies the username and password information that would be passed in the authorization header of HTTP request for client authentication.

        • Username. The username to access the protected resources of REST APIs.

        • Password. A valid password associated with the username.

      • Token. Specifies the token information that would be added as a bearer token in the HTTP request for client authentication.

        • Token type. The type of token that would be contained in the HTTP request.

        • Token. The token that would be contained in the HTTP requests.
      • Refresh Token.The refresh token that you would get from the external authorization server for the registered client ID and client secret.

        • Client ID. The client ID that you want to specify from the external authorization server.

        • Client secret. A valid client secret associated with the client ID.
      • Client Credentials.Specifies the client information for which the application is created in the external authorization server.

        • Scope. The scope of the client application that you want to specify from the external authorization server.

        • Client ID. The client ID that you want to specify from the external authorization server.

        • Client secret. A valid client secret associated with the client ID.
      • None.Specifies that you could create the client dynamically in the external authorization server without using any type of authorization.
      Supported grant types Specifies the list of grant types that are supported by API Gateway.Basically, grant types are the ways to get an access token from the external authorization server. Provide the grant type, in the Supported grant types field and click +Add.You can add more than one grant by clicking +Add.
    9. In the SSL Configuration section, provide the following information for SSL configuration, if the authorization server wants the 2-way SSL for the requests.

      Field Description
      Keystore alias Alias of the keystore containing the private key that is used for a secured communication between API Gateway and the authorization server.

      You can view all the keystore aliases available in API Gateway. If there are no configured keystore aliases, the list box contains only the default keystore, DEFAULT_IS_KEYSTORE.
      Key alias Alias for the private key to use to validate the HTTP requests from the client.

      You can view all the aliases available in the selected keystore. If there are no configured keystores, this list box is empty.
      Truststore alias Alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.

      Note: You need to select a truststore alias only when all of the following are true:

      • The client account on the third-party authorization server is configured to use mutual (two-way) SSL, and

      • The authorization server’s Certificate Authority certificate is not in the set of well-known authorities trusted by the JVM in which API Gateway runs.
    10. In the Metadata section, provide the following information for the authorization server metadata, which is used for the communication to portal.

      Field Description
      Access token URL The endpoint URL on the authorization server through which the client application exchanges the authorization code, client ID, and client secret, for an access token.
      Authorize URL The endpoint URL on the authorization server through which the end user authenticates and grants authorization to the client application.
      Refresh token URL The endpoint URL on the authorization server through which the client application refreshes an expired access token.
    11. Click Scopes.
      OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client application may be granted READ and WRITE access to the protected resources, or just the READ access. You can implement your APIs to enforce any scope or a combination of scopes as required. So, if a client receives a token that has READ scope, and it tries to invoke an API endpoint that requires WRITE access, the invocation fails.

      You can provide the meaning to the scope in OAuth/OpenID scopes management section.

    12. Provide the scope, in the Scope field that is registered in the authorization server and click +Add.
      You can add more than one scope by clicking +Add.

    13. Click Save. The external authorization server is added.
      You can add as many authorization servers as required, but only one is the default at any given time.

    Mapping OAuth or OpenID Scopes

    You must have the API Gateway’s manage security configurations functional privilege assigned to manage scopes.

    You have to map the scope that you have defined in the authorization server with the APIs in API Gateway to authorize the access tokens to be used to access the protected resources. You can map either a complete API or parts (resources or methods) of an API to the scope.

    For example, if there is a scope you have defined for an external authorization server, such as readonly, then the access tokens which contain readonly as their scope, should access only the GET resources. So, you can create an API Scope for the GET resources in an API or for multiple APIs and then map this readonly scope to all those API Scopes. Now this access token can invoke only the GET resources. If it tries to invoke any POST or PUT resource it fails. As another example you can consider mapping a business scope such as, inventory, that you have defined in the authorization server; you can map all the resources required for the inventory business to this scope.

    To map a scope

    1. Expand the menu options icon icon, in the title bar, and select OAuth/OpenID scopes.

    2. Click Map scope.

    3. Provide the following information in the Authorization server scope section:

      Field Description
      Select authorization server scope Specifies the scope linked to the authorization server. Type a search word and select the required scope from the search list populated.
      Name Displays the name of the authorization server scope selected. This is populated by default and is non-editable.
      Description A brief description for the scope being mapped.
      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.
    4. Click API scopes.

    5. Specify an API scope that is to be linked to the authorization server.
      Alternatively, you can type a search word and select the required API scope from the search list populated.
      The API scopes added are listed in the Selected API scopes table. You can click the delete icon icon, in the corresponding column, to delete an API scope from the list.

    6. Click Save.

    This maps the authorization server scope to the selected API scopes and lists the authorization scope in the scopes list.

    Viewing Scope Mapping Details

    You must have the API Gateway’s manage security configurations functional privilege assigned to manage scopes.

    You can view the scope details and modify the scope details as required from the OAuth/OpenID scopes page.

    To view scope mapping details

    1. Expand the menu options icon icon, in the title bar, and select OAuth/OpenID scopes.
      A list of available scopes appears. Use the Show drop-down list at the bottom of the page to set the maximum number of scopes you want to display in a page. The details, such as, name and description of the scope is displayed in the form of a table. You can delete a scope by clicking the delete icon icon.

    2. Click a scope.
      The scope details page appears. This page displays the details such as the authorization server name, the server scope, the API scopes that are linked to the server scope and the API scope details such as the API to which the scope is associated, the description of the API and API version number.

      You can modify the scope by clicking the Edit button and modifying the required values.

    Viewing Provider List and Provider Configuration

    You can view the list of integrated third-party providers and their configuration details, modify the provider configuration, and delete a provider in the Providers section.

    To view a list of providers and provider configuration

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

    2. Select Security > JWT/OAuth/OpenID > Providers.
      The Providers section displays a list of all the defined third-party providers in API Gateway.

      You can also perform the following operations in the Authorization servers section:

      • You can view the configuration details of the provider by clicking the required provider. The provider details page displays the client metadata field mapping and extended request parameter configuration information of the selected provider.

      • You can edit the provider configuration by clicking the required authorization server and modifying the details as required.

      • You can reset the configuration to system default value by clicking icon in the Action column for the respective provider.

      • You can delete the required authorization server by clicking icon in the Action column for the respective provider.

    Modifying the Provider Configuration

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to modify a provider.

    You might want to modify a provider to change the currently defined configuration settings.

    To modify a provider configuration

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

    2. Select Security > JWT/OAuth/OpenID > Providers.
      The Providers section displays a list of all the available providers in API Gateway.

    3. Click the name of the partner provider you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The provider is updated.

    Viewing Authorization Server List and Server Configuration

    You can view the list of authorization servers and their configurations details, modify the server configuration, and delete an authorization server in the Authorization servers section.

    To view a list of authorization servers and server configuration

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

    2. Select Security > JWT/OAuth/OpenID.
      The Authorization servers section displays a list of all the internal and external authorization servers in API Gateway under respective sections.

      You can also perform the following operations in the Authorization servers section:

      • You can view the configuration details of the authorization server by clicking the required authorization server. The authorization server details page displays the client information, scope information, and token information of the selected authorization server.

      • You can edit the server configuration by clicking the required authorization server and modifying the details as required.

      • You can delete the required authorization server by clicking icon in the Action column for the respective authorization server.

    Modifying Authorization Server Configuration

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to modify an authorization server.

    You might want to modify an OAuth 2.0 authorization server to change the currently defined configuration settings.

    To modify the authorization server configuration

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

    2. Select Security > JWT/OAuth/OpenID.
      The Authorization servers section displays a list of all the internal and external authorization servers in API Gateway.

    3. Click the name of the authorization server you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The authorization server is updated.

    Deleting an Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to delete an authorization server.

    You delete an authorization server to remove it from API Gateway permanently.

    To delete an authorization server

    1. Expand the menu options icon 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 in API Gateway.

    3. Click icon in the action column of the authorization server to be deleted.

    4. Click Yes in the confirmation dialog.
      The authorization server is deleted from API Gateway.

    Deleting a Provider

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to delete a provider.

    You delete a provider to remove it from API Gateway permanently.

    Important
    You must not delete a provider if it is being used by an authorization server.

    To delete a provider

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

    2. Select Security > JWT/OAuth/OpenID.
      The Providers section displays a list of available providers in API Gateway.

    3. Click icon in the Action column of the provider to be deleted.

    4. Click Yes in the confirmation dialog.
      The provider is deleted from API Gateway.

    Configuring Communication Details for Microgateway

    When you want Microgateway to use API Gateway as an OAuth2 authorization server, the communication channel between Microgateway and API Gateway has to be set up. The access token is then introspected in the Microgateway using remote introspection. To enable this you have to configure communication details, such as the introspection endpoint, client ID and client secret, in API Gateway, which are then used by Microgateway to introspect the tokens in API Gateway.

    To configure the communication details for Microgateway

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

    2. Select Security > JWT/OAuth/OpenID > Microgateway.

    3. In the Introspection endpoint field, provide the URL of the introspection endpoint.

      Microgateway uses the introspection endpoint to check the access tokens used in the client requests are currently active and are valid to invoke the protected resources.

      The endpoint must use the HTTPS protocol. Considering the default HTTPS port is being used, the Integration Server introspection endpoint would be https://localhost:5543/invoke/pub.oauth/introspectToken.

    4. In the Client ID field, provide an ID, which specifies the ID of the introspection client on the authorization server that Microgateway uses to introspect the access tokens.

    5. In the Client secret field, provide the Client secret, which specifies the password of the introspection client that Microgateway uses to introspect the access tokens.

    6. In the JWKS URI field, provide the JSON Web Key Signature endpoint to retrieve the corresponding public certificates for performing local introspection.

      You can use the following endpoint to fetch the JWKS URI of API Gateway:

      GET/rest/pub/apigateway/jwt/certs

      For more information about the REST API, see https://github.com/SoftwareAG/webmethods-api-gateway/blob/10.15/apigatewayservices/APIGatewayPublicServices.json.

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

    7. Click Save.

      The information provided here is stored in the configuration properties file and provisioned as part of the asset provisioning during Microgateway startup.

    Removing Expired OAuth Tokens

    You can remove all the expired OAuth access tokens using the given API.

    You can also schedule the cleanup of the expired OAuth access tokens as required.

    To remove expired OAuth tokens

    1. Make a REST call to the following endpoint:

      GET hostname:port/invoke/pub.oauth/removeExpiredAccessTokens

    Revoking OAuth Tokens

    You can revoke the OAuth access token from an application using the given API.

    To revoke OAuth token from an application

    1. Make a REST call to the following endpoint with the corresponding client Id and secret of the application in Basic authentication header:

      POST hostname:port/invoke/pub.oauth/revokeToken

      Sample request

    
    
    
        POST http(s)://hostname/invoke/pub.oauth/revokeToken
        { "token":"3d77988d5020493c8edde78b12c347e2046ac8438a91405597e669ed714ba96a",
        "token_type_hint":"accessToken"}
    
        
    

    Managing Threat Protection Policies

    Threat protection policies prevent malicious attacks from client applications that typically involve large, recursive payloads, and SQL injections. You can limit the size of things, such as maximum message size, maximum number of requests, and maximum node depth and text node length, in the XML document. You can configure the global threat protection policies and rules for all the incoming requests that comes through the external port of API Gateway. These policies and rules are enforced by API Gateway based on your configuration.

    You must have the API Gateway’s manage threat protection functional privilege to configure the following policies and rules.

    In addition, the API Gateway administrator can configure the necessary mobile devices and applications for which you want to deny the access, configure and customize the deny and alert rules, and manage the denied IPs.

    Basically, when you configure the threat protection policy in a clustered setup, you specify the limitations (such as number of requests and concurrent request) that an API Gateway instance in the cluster can handle during a specified time interval. Hence, if you add X number of API Gateway instances, the limitations set in the configuration also increases by X times.

    For example, if you have two API Gateway instances and set the limitations as 100 requests per minute, then the API Gateway instances should be able to handle 200 requests per minute. When you add one more API Gateway instance, the processing capacity also increases to 300 requests per minute. Here, the API Gateway cluster used for Threat Protection does not act as a single unit.

    Note
    When you have configured a load balancer, the load balancer exposes the actual client IP address using the X-Forwarded-For (XFF) headers. The watt.server.enterprisegateway.ignoreXForwardedForHeaderproperty specifies whether API Gateway uses or ignores the IP address in the XFF headers. By default, API Gateway ignores the client IP address and so the watt.server.enterprisegateway.ignoreXForwardedForHeader property is set to true. If you want API Gateway to use the actual client IP address present in the XFF, then set the watt.server.enterprisegateway.ignoreXForwardedForHeader property to false.

    Configuring Global Denial of Service Policy

    You can configure this policy in API Gateway to prevent Denial of Service (DoS) attacks. One form of DoS attack occurs when a client floods a server with many requests in an attempt to interfere with server processing. Using API Gateway, you can limit the number of requests that API Gateway accepts within a specified time interval and the number of requests that it can process concurrently. By specifying these limits, you can protect API Gateway from DoS attacks.

    You can configure API Gateway to limit the total number of incoming requests from the external ports. For example, you might want to limit the total number of requests received to 1000 requests in 10 seconds, and limit the number of concurrent requests to 100 requests in 10 seconds. When API Gateway detects that a limit has been exceeded, it blocks the exceeding requests for a specific time interval and displays an error message to the client based on your configuration. You can also configure a list of trusted IP addresses so that the requests from these IP addresses are always allowed and not blocked.

    To configure global denial of service policy:

    To configure global denial of service policy

    1. Click Policies in the title navigation bar.

    2. Select Threat protection > Global denial of service.

    3. Set the Enable button to the On position to enable the policy.

    4. Type the maximum number of requests, in the Maximum requests field, that API Gateway can accept from any IP address in a given time interval.

    5. Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.

    6. Type the maximum number of concurrent requests, in the Maximum requests in progress field, that API Gateway can process concurrently.

    7. Specify the time in minutes, in the Block intervals (minutes) field, for which you want requests to be blocked.

    8. Type the alert message text, in the Error message field, to be displayed when the policy is breached.

    9. Add IP addresses, in the Trusted IP addresses field, that can be trusted and are always allowed.

      • API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.

      • You can specify a range of IP addresses using the classless inter-domain routing (CIDR) notation. To specify an IP address range, type the first IP address in the range followed by a forward slash (/) and a CIDR suffix.

        Example IPv4 address range:

        • 192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to 192.168.103.255
        • 148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3

        Example IPv6 address range:

        • f000::/1 represents the IPv6 addresses from f000:: to ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
        • 2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to 2001:db8:0:ffff:ffff:ffff:ffff:ffff.

      Click icon to add more than one IP address.

    10. Click Save.

    Configuring Denial of Service by IP Policy

    You can configure this policy in API Gateway to prevent Denial of Service (DoS) attacks. One form of DoS attack occurs when a particular client floods a server with many requests in an attempt to interfere with server processing and not letting other clients in accessing the server. Using Denial of Service (DoS) by IP policy, you can limit the number of requests that API Gateway accepts from a particular IP address within a specified time interval and the number of requests that it can process concurrently from any IP address. By specifying these limits, you can protect API Gateway from DoS attacks by a particular IP address. When API Gateway detects that a limit has been exceeded, it blocks or denies the requests from that particular IP address and displays an error message to the client based on your configuration. You can also configure a list of trusted IP addresses so that the requests from these IP addresses are always allowed and not denied.

    Note
    To configure the denial of service by IP policy, you have to set watt.server.enterprisegateway.ignoreXForwardedForHeader property to false. When this setting is configured, the incoming request header will have the XFF header and tracks actual client IP address, which in turn allows you to configure DoS by IP.

    To configure the denial of service by IP policy

    1. Click Policies in the title navigation bar.

    2. Select Threat protection > Denial of service by IP.

    3. Set the Enable button to the On position to enable the policy.

    4. Type the maximum number of requests, in the Maximum requests field, that API Gateway can accept from a specific IP address in a given time interval.

    5. Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.

    6. Type the maximum number of requests, in the Maximum requests in progress field, that API Gateway can process concurrently from any single IP address.

    7. Select one of the following actions to be taken when the number of requests from a non-trusted IP address exceeds the specified limits:

      • Add to deny list to permanently deny future requests from the IP address.

      • Block temporarily block requests from this IP address.

    8. Type the alert message text, in the Error message field, to be displayed when the policy is breached.

    9. Add IP addresses, in the Trusted IP Addresses field, that can be trusted and not blocked.

      • API Gateway supports IPv4 and IPv6 addresses in the trusted IP addresses lists.

      • You can specify a range of IP addresses using the classless inter-domain routing (CIDR) notation. To specify an IP address range, type the first IP address in the range followed by a forward slash (/) and a CIDR suffix.

        Example IPv4 address range:

        • 192.168.100.0/22 represents the IPv4 addresses from 192.168.100.0 to 192.168.103.255
        • 148.20.57.0/30 represents the IPv4 addresses from 148.20.57.0 to 148.20.57.3

        Example IPv6 address range:

        • f000::/1 represents the IPv6 addresses from f000:: to ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff.
        • 2001:db8::/48 represents the IPv6 addresses from 2001:db8:0:0:0:0:0:0 to 2001:db8:0:ffff:ffff:ffff:ffff:ffff.

      Click icon to add more than one IP address.

    10. Click Save.

    Managing Denied IP List

    The Denied IPs section has a list of client IPs that were denied access due to breach of denial of service by IP policy. You can delete the IP from the denial list and make it available on client’s request.

    To manage the denied IP list

    1. Click Policies in the title navigation bar.

    2. Select Threat protection > Denied IPs.
      This displays a list of IP address that are denied from access.

    3. Click icon in the Action column so that the specified IP can be made available.

    Configuring Rules

    You can configure rules to filter malicious requests based on message size, authentication requests, requests from specific mobile devices and applications that could be harmful, requests that could cause an SQL injection attack, requests on anti-virus scan, XML / JSON requests, or use custom filters to avoid malicious attacks.

    API Gateway applies rules in the order in which they are displayed on the Threat Protection > Rules screen. Because a violation of a denial rule stops API Gateway from processing a request, hence it is important to prioritize the rules based on the order in, which you want them to be executed. The API Gateway processes denial rules followed by the alert rules.

    To configure rules

    1. Click Policies in the title navigation bar.

    2. Select Threat protection > Rules.
      This displays a list of rules that are already configured.

    3. Click Add rule.

    4. In the Rule properties section provide the following information:

      a. Type a name for the rule in the Rule name field. Valid rule names:

      • Must be unique.

      • Must not be empty.

      • Must not contain spaces.

      • Must not contain the special characters - ? ~ ` ! @ # $ % ^ & * ( ) - + = { } | [ ] \\ : \” ; ‘ < > , /

      b. Type a description for the rule in the Description field.

      c. Select an action to be followed when the policy is violated:

      • Deny request and alert to deny the access and send an alert when the policy is violated.

      • Alert to allow the request and send an alert when the policy is violated.

      d. Type the alert message text, in the Error message field, to be displayed when the policy is violated.

      e. Select the required Request type to which you want to apply the rule and provide the additional information required.

      The available values are:

      • ALL: Applies the rule to all requests.

      • REST: Applies the rule to all REST requests.

      • SOAP: Applies the rule to all SOAP requests

      • INVOKE: Applies the rule to all INVOKE requests.

      • CUSTOM: Applies the rule to all requests specified by the custom directives. You can use this option if you want a single rule applied for multiple request types and custom directives.

      f. Provide the following information to filter the requests depending on the Request type selected:

      • Resource path: Specifies the Resource path to the resource for the selected Request type. You can add multiple resource paths using the Add button. You can also specify an asterisk wildcard character (*) in the resource path. The following table specifies the format for the listed request types:

        Request type Resource Path Format
        REST folder_name/service_name
        SOAP folder_name/service_name
        INVOKE folder_name/service_name
        CUSTOM service-name/api-version/resourcepath/*

        For example, if we configure the value petstore/* for the resource path, all requests starting with the resource path petstore will be blocked.

        If we specify petstore/1.0/pet/*, then only requests starting with petstore/1.0/pet/ will be blocked. However, threat protection policies will not block requests for endpoints such as petstore/1.0/store/1.
        Note
        Certain regular expressions cannot be used, as Integration Server considers some of them as reserved characters.
      • Custom directives: Custom directives are prefixes added to the request path to filter requests based on the type of API being accessed. You can define the custom directive based on the entire request path, starting with the service name, followed by the API version, and then the resource path. The syntax is as follows:

        Base URL/servicename/api-version/resource-path/*

        The asterisk * serves as a wildcard character to represent unspecified parts of a URL path.

        A sample custom directive is as follows: http://localhost:5555/gateway/Petstore/1.0/pet/findByStatus/*

        Here, the custom directive is gateway, and we need to configure the value gateway in the custom directive. When we configure the custom directive with the value gateway, the threat protection policies will be applied to all the API Gateway APIs.
        You can add multiple directives using the Add button.

    5. Configure the required filters as follows:

      • Alert settings. Select one of the following options:

        • Default: Sets the default alert settings to be used.

        • Custom: You can specify this option to use the custom alert settings and provide the required information.

          • Alert destination: Specify the alert destination. Values are Email and Flow service. If you select Email, provide the email ids to which the alert notification has to be sent. If you select Flow service, a flow service is invoked. Specify the name of the flow service. You can create a flow service using the pub.security.enterpriseGateway:alertSpec as the signature of the service and or use the pre-defined flow service, pub.apigateway.threatProtection:violationListener. When you use the pre-defined service, the alerts are saved in API Gateway Data Store and displayed in API Gateway Dashboard. For more information on the pub.security.enterpriseGateway:alertSpec specification, refer to the Integration Server Build-In Services Reference Guide.

          • Provide the user, who has permissions to execute the service, as the user type. For example, Administrator

        Send alert: Select a condition depending on when you want the alert to be sent. Available values are On rule violation which sends an alert every time a request violates a rule or Every and specify the time interval (in minutes), which send alerts at specified intervals.

      • Message size filter

        • Set the Enable button to the On position to enable the filter.

        • Type the maximum size allowed for HTTP and HTTPS requests in the Maximum message size (MB) field.
          If the request is larger than the size specified in this limit, the request violates the rule and API Gateway performs the configured action.

      • OAuth filter

        • Set the Enable button to the On position to enable the filter.

        • Set the Require OAuth credentials toggle button to the On position. This implies the request should contain the OAuth credentials else the request would be denied.

      • Mobile application protection filter

        You can configure this filter to disable access for certain mobile application versions on a predefined set of mobile platforms. By disabling access to these versions, you are ensuring that all users are using the latest versions of the applications and taking advantage of the latest security and functional updates.

        • Set the Enable button to the On position to enable the filter.

        • Select the device type.

        • Select the mobile application.

        • Select the operator condition =, >, <, >=, <= or <>.

        • Type the mobile application version.

        You can add multiple entries by clicking icon.

      • SQL injection protection filter

        You can use the SQL injection protection filter to block requests that could possibly cause an SQL injection attack. When this filter is enabled, API Gateway checks each request message for specific patterns of characters or keywords that are associated with potential SQL injection attacks. If a match is found in the request parameters or payload, API Gateway blocks the request from further processing.

        • Set the Enable button to the On position to enable the selected filter.

        • Select the required filters as follows:

          • Select Database-specific SQL injection protection and select a database against which specific parameters needs to be checked.

            When enabled, API Gateway checks the incoming payload based on the specified database and GET or POST request parameters. If no parameter is specified, all input parameters are checked for possible SQL injection attack.

          • Select Standard SQL injection protection and specify one or more GET or POST request parameters that could be present in the incoming requests. Parameters can contain only alphanumeric characters, dollar sign ($), and underscore (_).

            You can add multiple entries by clicking icon.

      • Anti virus scan filter

      • You can use the antivirus scan filter to configure API Gateway to interact with an Internet Content Adaptation Protocol (ICAP)-compliant server. An ICAP server is capable of hosting multiple services that you can use to implement features such as virus scanning or content filtering. Using the antivirus scan filter, API Gateway can leverage the ICAP protocol to scan all incoming HTTP requests and payloads for viruses.

        • Set the Enable button to the On position to enable the filter.

        • Type the antivirus ICAP engine name in the ICAP name field.

        • Type the host name or IP address of the machine on which the ICAP server is running in the ICAP host name or IP address field.

        • Type the port number on which the ICAP server is listening in the ICAP port number field.

        • Type the name of the service exposed by the ICAP server that you can use to scan your payload for viruses in the ICAP service name field.

      • JSON threat protection filter

        You can use this filter to block attacks through JSON payload that have infinitely long strings or deeply nested payloads. Software AG recommends that this protection should be combined with message size filter to identify infinite payloads.

        Set the Enable button to the On position to enable the filter.

        You can specify any of these parameters as filter criteria. If you do not specify a value, the system applies a default value of -1, which means an unlimited value.

        Field Description
        Container depth Specifies the maximum allowed containment depth, where the containers are objects or arrays.
        For example, an array containing an object which contains an object would result in a containment depth of 3.
        Object entry count Specifies the maximum number of entries allowed in an object.
        Object entry name length field Specifies the maximum string length allowed for a property name within an object.
        Array element count Specifies the maximum number of elements allowed in an array.
        String value length Specifies the maximum length allowed for a string value.
        Applicable content type Specify any other content types to be included in the filter.
        You can add more entries by clicking icon.
      • XML threat protection filter

        You can use this filter to block attacks through XML payload that have infinitely long strings or deeply nested payloads. Software AG recommends that this protection should be combined with message size filter to identify infinite payloads.

        Set the Enable button to the On position to enable the filter.

        You can specify any of these parameters as filter criteria. If you do not specify a value, the system applies a default value of -1, which the system equates to no limit.

        Field Description
        Namespace prefix length Specifies a limit on the maximum number of characters permitted in the namespace prefix in the XML document.
        Namespace URI length Specifies a character limit for any namespace URIs present in the XML document.
        Namespace count per element Specifies the maximum number of namespace definition allowed for any element.
        Child count Specifies the maximum number of child elements allowed for any element.
        Attribute name length Specifies a limit on the maximum number of characters permitted in any attribute name in the XML document.
        Attribute value length Specifies a limit on the maximum number of characters permitted in any attribute value in the XML document.
        Attribute count per element Specifies the maximum number of attributes allowed for any element.
        Element name length Specifies a limit on the maximum number of characters permitted in any element name in the XML document.
        Text length Specifies a character limit for any text node present in the XML document.
        Comment length Specifies a character limit for any comments present in the XML document.
        Processing instruction target length Specifies a limit on the maximum number of characters permitted in the target of any processing instructions in the XML document.
        Processing instruction data length Specifies a limit on the maximum number of characters permitted in the data value of any processing instructions in the XML document.
        Node depth Specifies the maximum node depth allowed in the XML.
        Applicable content types Specify any other content types to be included in the filter.
        You can add multiple values by clicking icon.
    6. Click Save.
      The new rule is created and appears in the list of rules in the Rules page.

    The rule is applied to requests only if the rule is enabled. You can enable the rule in the Rules page by selecting the enable icon for the required rule.

    Registering a Mobile Device or Application

    You can use API Gateway to disable access for certain mobile application versions on a predefined set of mobile platforms. By registering the required devices and applications and disabling access to these versions, you ensure that all users use the latest versions of the applications and take advantage of the latest security and functional updates.

    To register a mobile device or application

    1. Click Policies in the title navigation bar.

    2. Select Global Policies > Mobile devices and apps.

    3. Provide the mobile device type name and click icon.
      You can add more entries by clicking icon. You can delete the added ones by clicking icon.

    4. Provide the mobile application name and click icon.
      You can add more entries by clicking icon. You can delete the added ones by clicking icon.

    5. Click Save.

    Configuring Alert Settings

    You can configure the alert settings to control the following aspects of alerts that API Gateway sends when a request violates a rule:

    To configure alert settings

    1. Click Policies in the title navigation bar.

    2. Select Global Policies > Alert settings.

    3. Select one or both the alert destination types:

      • Email. This sends email alerts.

        • Type the email ids to which the email has to be sent.

      • Flow Service. This invokes a flow service to alert you of a rule violation. Specify the name of the flow service. You can create a flow service using the pub.security.enterpriseGateway:alertSpec specification as the signature of the service or use the pre-defined flow service, pub.apigateway.threatProtection:violationListener. When you use the predefined service, the alerts are saved in API Gateway Data Store and displayed API Gateway Dashboard. For more information on the pub.security.enterpriseGateway:alertSpec specification, refer to the Integration Server Build-In Services Reference Guide.

        • Provide the user, who has permissions to execute the service, as the user type. For example, Administrator.

    4. Select one of the following conditions depending on when you want the alert to be sent.

      • On rule violation to send an alert every time a request violates a rule.

      • Every and specify the time interval (in minutes) to send to send alerts at specified intervals.

    5. Click Save.