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
No subtopics in this section
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.
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.
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
Expand the menu options icon , in the title bar, and select User management.
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.
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:
Administrators
API-Gateway-Administrators
API-Gateway-Providers
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
Expand the menu options icon , in the title bar, and select User management.
Select Groups.
Click Add group.
The Group details tab appears.
Provide the following information in the Basic information section:
Field
Description
Name
Name of the user group.
Description
A description for the user group.
Click Save to save the group details at this stage and provide the group information for the user at a later time.
Click Continue to associate Users >.
Alternatively, you can click Users to go to the Users section.
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.
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
Expand the menu options icon , in the title bar, and select User management.
Click Groups.
A list of groups appears.
Select the group to be modified.
The Group details tab appears.
Click Edit.
This opens the details of the selected group.
Modify the basic information of the user.
Modify the user details of the group.
Edit or delete (by clicking the delete icon) the name of the existing user that appears.
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
Expand the menu options icon , in the title bar, and select User management.
Click Groups.
A list of groups appears.
Click the Delete icon for the group that has to be deleted.
Note
You cannot delete predefined groups.
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
group users of a business unit or a project with similar roles and assign certain assets to these teams
assign different access privilege to different set of users to specific assets?
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:
Tenant isolation. If your requirement is to allow the access of assets by tenants, then you must have multiple tenants and isolate them from each other. The Team support feature does not address this requirement.
Full access management. Users gain access based on their team privileges. There is no role-based access for users to an asset.
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:
Team administrator. You can assign a user or a user group as team administrator. Team administrators can add or remove users from a team. When you assign a user group as team administrator, all users of the groups can modify team members. When team administrators, who do not have the Manage user administration functional privilege log on to API Gateway, they can view only the teams assigned to them in the Teams tab of the Administration page.
Functional privileges for the team members. The functional privileges assigned to a team determines the accessibility of assets to the respective team members. For example, if you assign all privileges under the APIs, Policies, and Applications sections, then the team members can manage APIs and applications assigned to their teams and perform operations related to policies.
Team members. You can assign users and user groups to the team. Team members can access the assets assigned to their teams and perform operations on the assets based on the functional privileges assigned to the team.
Teams - Asset Association
After you have created teams, you can assign assets to teams in one of the following ways:
Assign team during asset creation. When you create an asset, API Gateway provides an option to select the teams for the asset. You can select more than one team for an asset. You can modify the teams assigned by following the Change ownership process. For information about the process, see How do I Modify Teams Assigned to an API? and How do I Change the Ownership of Multiple Teams?
Using Global Team Assignment rule. This is a preferred method to assign teams when you already have assets to which you want to assign teams to. You can create global assignment rules that are applied to assets and assign teams to them. You can specify one or more conditions in a rule. When an asset satisfies the conditions specified in a rule, the asset is assigned to the teams specified in the rule. When you create and activate a rule, the rule is applied to the existing assets and teams are assigned accordingly.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Extended settings.
Click Show and hide keys.
All configurable parameters appear.
Select the enableTeamWork from the parameter list.
The enableTeamWork field appears in the Extended Settingssection.
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:
API Gateway Manage user administration privilege.
The user group, Dev is created. For information on how to create a user group, see Adding a Group.
To create teams
Expand the menu options icon , in the title bar, and select User management.
Click Teams.
Click Add Team.
The Create Team page appears.
Provide the name and description of the team in respective fields.
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.
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.
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.
Click Continue to assign functional privileges >.
The Functional privileges list appears.
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.
Click Continue to assign groups >.
The Find groups section appears.
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.
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:
API Gateway Manage user administration privilege.
The team support feature enabled. For information on enabling the feature, see Enabling Teams Support.
The team, DevTeam is created. For information on creating team, see Creating Teams.
To assign teams during asset creation
Click APIs in the title navigation bar.
The Manage APIs page appears.
Click Create API. The Create API page appears.
Click Import from an File.
Click Browse to select the file using which you want to create the API.
Provide DevAPI in the Name field.
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:
API Gateway administrator privileges.
The team support feature enabled. For information on enabling the feature, see Enabling Teams Support.
Ensure that the team, ViewAllAssets is created. For information on creating team, see Creating Teams.
To assign teams using team assignment rule
Expand the menu options icon , in the title bar, and select User management.
Click Global team assignments.
Click Add global team assignment.
The Team assignment rule page appears.
Provide the name and description of the rule in corresponding fields.
In this example, ViewRule is provided in the Name field.
Click Continue to filters >.
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.
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.
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.
Click Continue to assign teams >.
Provide the required team names in the Name field.
For our use case, the ViewAllAssets team is selected.
Click Save.
The rule appears in the Global team assignment page.
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.
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
Ensure that you have the change owner or team privilege.
Log on to API Gateway as a user with the change ownership or team privilege.
Click APIs on the title navigation bar.
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.
Click change.
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.
An approval request is sent to the approver.
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.
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
Use the following REST request to change the asset ownership to a new user.
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:
This request assigns the all APIs of DevTeam to Team2 and Team3.
The change approval process is initiated.
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.
The approver approves the request in the Pending Requests section of the API Gateway UI.
The approval notification is sent to the requester.
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
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.
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.
When assets are exported, the respective team details are exported along with the assets; members of the teams are not exported.
When assets are imported, the respective team is created if it is not present already; members of the teams cannot be imported.
When team is exported, the users and groups that are part of team can be selected for export if required.
When team is imported, the users and groups are imported along with the team.
An export archive of an API will include the details of all associated applications (if this option was selected when exporting) - “visible” and “invisible”
An export archive of an Application will always include the details of all associated APIs - “visible” and “invisible”
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.
When assets (all except teams) are promoted, they are promoted along with their team details; users are not promoted.
When teams are promoted, the users and groups of teams can be promoted if required.
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
API Gateway displays the names, descriptions, and versions for all associated APIs.
The API entries are not linked with the respective API details pages
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 Gateway displays names, descriptions, and versions for all associated APIs (by the policy’s filter conditions)
Only the entries for the visible APIs are linked with their API details pages
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:
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:
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.
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.
Share the number of domains to be configured for your account and the list of custom domains with Software AG.
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.
Send the SSL certificates and Certificate Key to Software AG in base64 format to configure the certificates on the custom domain load balancer.
Software AG sends you the CNAME in return.
Using the CNAME, configure your DNS to point to the custom domain load balancer.
After the configuration is completed, start using the custom domain to access webMethods API Gateway.
Checks for existing assets after configuring custom domains
External endpoints change after the custom domain is configured, so you have to inform your partners about the new domain. In case of a single domain, the old URL used by the tenant will not be functional for both Runtime and UI.
Verify all assets that expose endpoint URLs, for example, REST APIs, SOAP APIs, Services over HTTP, and so on.
A few assets, for example, SOAP APIs and REST APIs may not work after the custom domain change as the endpoints change after the custom domain is configured, so you should inform your customers to update the endpoints.
Upon request, customers can maintain their existing domain for the Runtime API while directing the user interface to a newly configured domain. This prevents any inconsistencies that impact customers utilizing the Runtime API.
Renewal of certificate for custom domain depends on licence terms, in most cases, it would be 1 year.
Configuring Extended Settings
No subtopics in this section
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Extended settings.
Click Show and hide keys.
This displays all the configurable parameters.
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:
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
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.
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:
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.
Click Save.
Configuring API Fault Settings
No subtopics in this section
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > API fault.
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.
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.
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:
Create application: To enforce approvals for creating an application in API Gateway.
Register application: To enforce approvals for associating an application with APIs.
Subscribe package: To enforce approvals in API Gateway to enable Developer Portal consumers for subscribing a package to a plan in Developer Portal.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Create application.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the access profile of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Register application.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the access profile of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Update application.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the access profile of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Subscribe package.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the access profile of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Click Cancel to revert to the last saved changes or to abandon all the changes if the values are not saved.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Update subscription.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the team of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Approval configuration > Delete subscription.
Set the Enable toggle button to the on position to enable approval configuration to take effect.
Select the team of approvers from the Approvers drop-down list.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
On the title bar, expand the menu options icon and select Administration.
Select General > Change owner/teams.
Set the Enable toggle button to the on position .
Select the team of approvers from the Approvers list.
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.
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.
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.
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.
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.
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.
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:
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
Expand the menu options icon , in the title bar, and select Pending Requests. The Pending requests page appears.
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.
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
Expand the menu options icon , in the title bar, and select Pending Requests.
Select My requests.
A list of requests appears with the detailed information of the request.
Click the Delete icon for the request that has to be deleted.
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:
A URL alias may be easier to type than full URL path names.
A URL alias is more secure than URL path names.
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:
An alias name must be unique across API Gateway.
You can associate a single URL alias with multiple resources by specifying port mappings. A port mapping correlates the alias with a different URL alias based on the port on which th request was received.
If you want to use URL alias with a REST resource you must enable partial matching of URL aliases.
If you enabled or intend to enable partial matching of URL aliases, do not define an alias that begins with another alias.
To create a URL alias
Expand the menu options icon , in the title bar, and select Administration.
Select General > URL aliases.
This displays a list of available URL aliases and the corresponding details.
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: # % ? ’ “ < |
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > URL aliases.
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.
Incorporate the required changes.
Click Save.
Deleting a URL Alias
Expand the menu options icon , in the title bar, and select Administration.
Select General > URL aliases.
In the URL Alias list, locate the row that contains the alias you want to delete, and click .
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:
http://test:2225/gateway/RESTCalcService/1.0
http://test:4000/gateway/RESTCalcService/1.0
http://test:4010/gateway/RESTCalcService/1.0
http://test:5555/gateway/RESTCalcService/1.0
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:
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:
Expand the menu options icon , in the title bar, and select Administration.
Select General > URL aliases.
Click Add URL alias and provide the following values:
Field
Value
Alias
calc
Default URL path
gateway/RESTCalcService/1.0/postCalc
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,
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Custom Content-types.
Provide the Content-type that has to be configured.
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.
Click .
You can configure multiple custom content-types by clicking Add.
Configuring API Callback Processor Settings
No subtopics in this section
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Callback processor settings.
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.
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.
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.
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.
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:
API Gateway
Developer Portal
CentraSite
API Control Plane
Elasticsearch
Email
Custom destinations
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select API Gateway to configure the event types for this destination.
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.
Select Report performance data to publish performance metrics data.
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.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select Developer Portal > Configuration to configure Developer Portal as the destination.
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.
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.
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.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select Developer Portal > Events to configure the event types for this destination.
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.
Select Report performance data to publish performance metrics data.
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.
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
Expand the menu options icon in the title bar, and select Administration.
Select Destinations.
Select API Control Plane > Configuration to configure API Control Plane agent.
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.
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
Provide the following information in the API Control Plane configuration section:
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.
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
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.
Enable the API Control Plane communication toggle button to establish communication between API Gateway and API Control Plane.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
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.
Select Send SNMP traps to CentraSite to publish data about the runtime events and metrics to the CentraSite SNMP server.
Select Force reset CentraSite communication and SNMP details, and click Reset to delete the current configuration and restore the system configuration.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select CentraSite > Events to configure the event types for this destination.
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.
Select Report performance data to publish performance metrics data.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select Elasticsearch > Configuration to configure Elasticsearch as the destination.
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.
Click Test.
This tests the communication channel between API Gateway and the configured Elasticsearch.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select Elasticsearch > Events to configure the event types for this destination.
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.
Select Report performance data to publish performance metrics data.
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.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select Email > Templates to configure the event templates.
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:
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:
Additionally, you can click to abandon the changes and revert to the default template. You can click 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:
External endpoint - Use this type to configure an external REST endpoint URL as a destination.
AWS Lambda - Use this type to configure an Amazon Web Services \(AWS\) Lambda function as a destination.
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
Expand the menu options icon , in the title bar, and select Administration.
Click Destinations.
Select Custom destinations from the left navigation pane.
Click + Add custom destination.
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.
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.
Select External endpoint in the Type field.
Provide the following information in the External Endpoint section, as required:
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.
Configure the custom properties of the custom extension as required.
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.
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
Click APIs on the title navigation bar.
Click the required API.
The API details page appears.
Click Edit.
Select Policies.
Click Traffic Monitoring and select a required policy.
Select the custom destination from the Destination section in the Policy Properties pane.
Select any other required details such as Alert interval, Unit, Alert frequency, Alert message and so on.
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.
Ensure you have configured AWS alias. For details on how to configure an AWS alias, see Configuring an AWS Alias.
To publish data to an AWS Lambda function
Click APIs on the title navigation bar.
Expand the menu options icon , in the title bar, and select Administration.
Click Destinations.
Select Custom destinations from the left navigation pane.
The Custom destination page appears.
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.
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.
Select AWS Lambda in the Type field.
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.
Configure the custom properties of the custom extension as required.
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.
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.
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:
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.
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:
API Gateway
Elasticsearch
The following auditable events can be configured to write to the API Gateway audit logs:
Access profile management events
Access profile management consists of the following events:
Creation, modification, and deletion of an Access profile object.
Alias management events
Alias management consists of the following events:
Creation, modification, and deletion of an Alias object.
Analytics management events
Analytics management consists of the following events:
Archiving, purging, and restoring of analytics data in the database.
API management events
API management consists of the following events:
Creation, modification, and deletion of an API object.
Activation and deactivation of an API.
Application management events
Application management consists of the following events:
Creation, modification, and deletion of an Application object.
Approval management events
Approval management consists of the following events:
Approval and rejection of a request to create, register, and modify an application.
Approval and rejection of a request to subscribe a package in Developer Portal.
Group management events
Group management consists of the following events:
Creation, modification, and deletion of a Group object.
Package management events
Package management consists of the following events:
Creation, modification, and deletion of a Package object.
Plan management events
Plan management consists of the following events:
Creation, modification, and deletion of a Plan object.
Policy management
Policy management consists of the following events:
Creation, modification, and deletion of a global Policy object.
Creation, modification, and deletion of an API level Policy object.
Activation and deactivation of a global policy.
Activation and deactivation of an API level policy.
Promotion management events
Promotion management consists of the following events:
Creation, modification, and deletion of a Stage object.
Promotion of an API stage.
Rollback operation of an API stage.
User management events
User management consists of the following events:
A user logs in or fails to log in to API Gateway.
A user logs out of API Gateway.
Creation, modification, and deletion of a User object.
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:
API Gateway
Elasticsearch
Custom Destination
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:
Access profile management
Alias management
Analytics management
API management
Application management
Approval management
Group management
Package management
Plan management
Policy management
Promotion management
User management
By default, all the auditable events are logged into the API Gateway destination.
To configure audit logs
Expand the menu options icon , in the title bar, and select Administration.
Select Destinations.
Select the required destination to log the auditable events.
In the Audit log data section, select the required management areas to monitor, audit, and report the data.
Click Save.
Viewing Audit Logs
You can use the audit log reports to view the data of auditable events.
To view audit logs
Expand the menu options icon , in the title bar, and select Analytics.
The dashboard displays the API Gateway-wide analytics based on the metrics monitored.
Select Audit logs.
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
If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.
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
Click + Add filter above the audit logs grid.
Logs that are filtered based on the given criteria appears.
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.
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
Expand the menu options icon in the title bar, and select Analytics. The dashboard displays the API Gateway-wide analytics based on the metrics monitored.
Select Audit logs.
In the drop-down list, choose the time interval in which you want to view the data of auditable events.
If you select Custom, type the From Date and To Date to specify the time interval that best suits your needs.
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.
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:
You can publish APIs defined in API Gateway to service registries. This enables other applications to use the service registry to dynamically locate an API Gateway instance that provides that API.
You can set an API Gateway route to a service registry endpoint. This enables API Gateway to use the service registry to dynamically locate an application instance and route the request to it.
Service Registries supported by API Gateway
API Gateway currently supports the following service registries:
Eureka: Eureka is a REST-based service for locating services for the purpose of load balancing and failover of middle-tier servers. It has been primarily designed for
applications in the AWS cloud.
Service Consul: Service Consul is a tool for discovering and configuring services in IT infrastructure.
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
Expand the menu options icon , in the title bar, and select Administration.
Click External accounts.
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:
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.
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.
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.
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:
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.
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.
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.
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.
Click Add.
The service registry is added to API Gateway.
Removing a Service Registry
You cannot remove a service registry if any API has been published to it.
You can remove only the non-default service registries that are not used by any API.
You must have the Manage service registries functional privilege assigned to perform this task.
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
Expand the menu options icon , in the title bar, and select Administration.
Click Service Registries.
Click in the row that has the service registry that you want to remove.
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
On the title bar, expand the menu options icon and select Administration.
Click External accounts > AWS configuration.
Click Add new AWS account.
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.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Click External accounts.
Click Integration servers.
The list of configured Integration server instances appears.
Click Add new Integration servers.
The options to add new Integration Server details appear.
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.
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.
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
Developer Portal
Audit Log
CentraSite
Elasticsearch
Email
Local Log
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"}
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
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"}
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"}
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"}
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
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"}
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"}
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"}
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
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:
Configure the keystores and truststores required for incoming message-level security and transport-level security.
Configure the SAML issuer to use in API Gateway outbound authentication to fetch the SAML token from the STS (Security Token Service).
Configure the custom assertions to use in inbound authentication of API Gateway.
Configure Kerberos settings.
Configure JSON web token (JWT), OAuth, and OpenID authorization servers and third-party providers.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of existing keystores and truststores and corresponding details are displayed.
In the Keystores section, click Add keystore.
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.
Click OK.
All the key aliases in the uploaded file are listed.
Type a password for the required key alias.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of keystores and truststores and corresponding details are displayed.
Click the keystore alias to be updated.
The update keystore section is displayed.
Modify the fields as required.
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.
Type a password for the alias to be configured.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of keystores and truststores and corresponding details are displayed.
Click in the action column of the keystore to be deleted.
Click Yes in the confirmation dialog.
The keystore is deleted from the list.
Configuring Truststore Information
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of existing keystores and truststores and corresponding details are displayed.
In the Truststores section, click Add truststore.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of keystores and truststores and corresponding details are displayed.
Click the truststore alias to be updated.
The update truststore section is displayed.
Modify the fields as required.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security.
A list of keystores and truststores and corresponding details are displayed.
Click in the action column of the truststore to be deleted.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security. A list of existing keystores and truststores loaded during startup and those created in API Gateway and corresponding details appears.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select General > Security. A list of existing keystores and truststores loaded during startup, and those created in API Gateway and the corresponding details appears.
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.
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 API Gateway fails to authenticate the client (or)
when API Gateway fails to identify the client and its respective application.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Global IP Access Settings.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
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.
Click Add SAML issuer.
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 .
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:
Enforce symmetric binding with an authentication mechanism that is not available by default in API Gateway.
Support signing and encryption at the desired level.
Modify the predefined encryption algorithm and security layout properties.
Enforce custom authentication tokens that are not available by default in API Gateway.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Custom assertions.
API Gateway displays a list of all the currently defined policy assertions.
Click Add assertion.
Select the assertion type.
The available options are:
Binding
Token
Policy
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.
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:
Binding Assertion
Custom Token Assertion
To enforce the custom policy assertion in an API, select the assertion and the corresponding SAML issuer in the appropriate fields:
Issuer Policy field of the Add SAML Issuer configuration page.
Authentication scheme field of the Outbound Authentication - Message policy.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Custom assertions.
A list of all available custom assertions appears.
You can delete a custom assertion by clicking its Delete icon.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Custom assertions.
A list of all available custom assertions appears.
Select the required custom assertion that you want to modify.
Modify the fields as required.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Custom assertions.
A list of all available custom assertions appears.
Click in the action column of the custom assertion to be deleted.
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.
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:
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:
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:
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:
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:
A working Key Distribution Center (KDC) is set up.
The KDC is configured as an LDAP directory, for authenticating incoming requests with Kerberos tickets.
The Kerberos client is registered with the principal database of the KDC.
The API that you want to access is registered with the KDC.
A valid Kerberos configuration file is available.
To configure API Gateway to use Kerberos
Expand the menu options icon , in the title bar, and select Administration.
Select Security > Kerberos.
Click Edit.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > OAuth/JWT/OpenID.
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.
The name field is pre-populated with the name of the internal authorization server, local, which is non-editable.
The description for the internal authorization server is pre-populated with the description available. You can modify the description as required.
Click JWT configuration to configure API Gateway as a JWT issuer. Alternatively you can expand or collapse a section, using the down arrow and the up arrow and that appear next to the section name.
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.
Click OAuth configuration to configure API Gateway as an OAuth authorization server. Alternatively you can expand or collapse a section, using the down arrow and the up arrow and that appear next to the section name.
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.
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.
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.
Type the scope that is registered in the authorization server and click +Add.
You can include multiple scopes.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID > Providers.
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.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > OAuth/JWT/OpenID.
The available and configured internal authorization servers and external authorization servers are listed in the respective sections.
Click Add authorization server in the External authorization servers section.
Type a name for the external authorization server.
Type a description for the external authorization server that is being configured.
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.
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.
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 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.
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.
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.
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.
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.
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
Expand the menu options icon , in the title bar, and select OAuth/OpenID scopes.
Click Map scope.
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.
Click API scopes.
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 , in the corresponding column, to delete an API scope from the list.
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
Expand the menu options 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 .
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
Expand the menu options icon , in the title bar, and select Administration.
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 in the Action column for the respective provider.
You can delete the required authorization server by clicking 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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID > Providers.
The Providers section displays a list of all the available providers in API Gateway.
Click the name of the partner provider you want to modify.
Modify the fields as required.
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
Expand the menu options icon , in the title bar, and select Administration.
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 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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID.
The Authorization servers section displays a list of all the internal and external authorization servers in API Gateway.
Click the name of the authorization server you want to modify.
Modify the fields as required.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID.
The Authorization servers section displays a list of available internal and external authorization servers in API Gateway.
Click in the action column of the authorization server to be deleted.
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
Expand the menu options icon , in the title bar, and select Administration.
Select Security > JWT/OAuth/OpenID.
The Providers section displays a list of available providers in API Gateway.
Click in the Action column of the provider to be deleted.
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
Expand the menu options icon , in the title bar, and select Administration.
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.
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.
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.
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:
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.
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.
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.
Global Denial of Service
Denial of Service by IP
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
Click Policies in the title navigation bar.
Select Threat protection > Global denial of service.
Set the Enable button to the On position to enable the policy.
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.
Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.
Type the maximum number of concurrent requests, in the Maximum requests in progress field, that API Gateway can process concurrently.
Specify the time in minutes, in the Block intervals (minutes) field, for which you want requests to be blocked.
Type the alert message text, in the Error message field, to be displayed when the policy is breached.
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 to add more than one IP address.
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
Click Policies in the title navigation bar.
Select Threat protection > Denial of service by IP.
Set the Enable button to the On position to enable the policy.
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.
Specify time in seconds, in the In (seconds) field, in which the maximum requests have to be processed.
Type the maximum number of requests, in the Maximum requests in progress field, that API Gateway can process concurrently from any single IP address.
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.
Type the alert message text, in the Error message field, to be displayed when the policy is breached.
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 to add more than one IP address.
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
Click Policies in the title navigation bar.
Select Threat protection > Denied IPs.
This displays a list of IP address that are denied from access.
Click 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
Click Policies in the title navigation bar.
Select Threat protection > Rules.
This displays a list of rules that are already configured.
Click Add rule.
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.
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.
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 .
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 .
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 .
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 .
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
Click Policies in the title navigation bar.
Select Global Policies > Mobile devices and apps.
Provide the mobile device type name and click .
You can add more entries by clicking . You can delete the added ones by clicking .
Provide the mobile application name and click .
You can add more entries by clicking . You can delete the added ones by clicking .
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:
Whether API Gateway issues an alert for a rule violation.
How often API Gateway issues the alert.
The method API Gateway uses to send the alert.
Whether a rule uses the default alert options or its own customized alert options.
To configure alert settings
Click Policies in the title navigation bar.
Select Global Policies > Alert settings.
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.
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.