Administration

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

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

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

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

  • External accounts to add and configure service registries.

General Configuration

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:

Configuring Extended Settings

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

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

To configure the extended settings

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

  2. Select General > Extended settings.

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

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

    Parameter and Description
    allowEGInvokeOnly Specifies whether the SOAP APIs with Transport policy set to http, can be invoked using the reverse invoke method when you set the external port as https, and the Registration and Internal ports as http. Ensure you enable this setting in the system where the SOAP API is created.
    Note: This setting affects only the behavior of SOAP APIs. You can invoke the REST APIs using the reverse invoke method, irrespective of this setting, given the above said conditions are true.
    Possible values:
    • true. You can invoke SOAP APIs using the reverse invoke method if the external port is set as https, and the Registration and Internal ports are set as http.
    • false. You cannot invoke SOAP APIs using the reverse invoke method.
    allowExceedMaxWindowSize Specifies whether the number of records retrieved by Elasticsearch in a single request exceeds the configured value or not.
    Possible values:
    • true. The number of records retrieved in a single request can exceed the maximum value configured in Elasticsearch. This is the default value.
    • false. Displays an error message when the number of records retrieved in a single request exceeds the configured value.
    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.
    defaultEncoding Specifies the format for encoding the design time and run time invocation data.
    The default value is UTF-8.
    If you want to modify this value, Software AG recommends that you do it before starting API Gateway.
    You can change the value in the gateway-core.xml file located in the folder: SAGInstallDir\IntegrationServer\instances\instance-name\packages\WmAPIGateway\config\resources\beans.
    The property to be modified is: entry key=“defaultEncoding” value=“UTF-8”/.
    Note: Changing this value after starting API Gateway might make API Gateway non-functional. If API Gateway is clustered, then the same value should be updated in all nodes of API Gateway.
    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.
    For details on the feature, see Team Support.
    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.
    events.collectionPool.maxThreads Specifies the maximum number of threads to be used for the event data collection pool.
    Each thread in this pool is assigned a task of collecting the events like transactions, error and performance metrics, and processing them for sending to destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    Specifying more number of threads implies that the processing of events for sending to the desired destinations is faster. At the same time, it increases the usage of system resources, which could result in slower service execution.
    This value must be greater than or equal to the value of events.CollectionPool.minThreads.
    Default value is 8.
    events.collectionPool.minThreads Specifies the minimum number of threads to be used for the event data collection pool.
    Each thread in this pool is assigned a task of collecting the events like transaction, error and performance metrics and processing them for sending to the desired destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    Specifying less number of threads implies that processing of events for sending to the desired destinations is slower.
    Default value is 1.
    events.collectionQueue.size Specifies the size of the collection queue to be used during event data collection. This is used in connection with the events.collectionPool.minThreads and events.collectionPool.maxThreads settings.
    When events like transaction, error events and performance metrics are generated during API invocations, they will be put in the collection queue for further processing. Each thread in the collection pool is assigned a task of collecting these events and processing them for sending to the desired destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    If the queue capacity is reached, then any additional event data would be lost. Hence it is better to increase this size when there is an increase in incoming traffic.
    Specifying a large collection queue size and small collection thread pool size might cause delay in processing the events data but ensures all the data are processed.
    On the other hand, specifying a small collection queue size and large collection thread pool size might cause faster processing of the events data but keeps the CPUs busier and at the same time when the traffic increases there is a possibility of data loss when the collection queue size is full.
    Default value is 10000.
    events.reportingPool.maxThreads Specifies the maximum number of threads to be used for the event data reporting pool.
    Each thread in this pool is assigned a task of sending the events like transaction, error and performance metrics to the desired destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    Specifying more number of threads implies that sending of events to the desired destinations is faster. At the same time it increases the usage of system resources, which could result in slower service execution.
    This value must be greater than or equal to the value of events.ReportingPool.minThreads.
    Default value is 4.
    events.reportingPool.minThreads Specifies the minimum number of threads to be used for the event data reporting pool.
    Each thread in this pool is assigned a task of sending the events like transaction, error and performance metrics to the desired destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    Specifying less number of threads implies that sending of events to the desired destinations is slower.
    Default value is 2.
    events.reportingQueue.size Specifies the size of the reporting queue to be used during event data reporting. This is used in connection with the events.reportingPool.minThreads and events.reportingPool.maxThreads settings.
    When events like transaction, error events and performance metrics are generated during API invocations, they will be put in the collection queue for further processing. Each thread in the collection pool is assigned a task of collecting these events, processing them and put in the reporting queue for sending to the desired destinations such as API Gateway, Elasticsearch, API Portal, and so on.
    If the reporting queue capacity is reached, then any additional event data would be lost. Hence it is better to increase this size when there is an increase in incoming traffic.
    Specifying a large reporting queue size and small reporting thread pool size might cause delay in processing the events data but ensures all the data are processed.
    On the other hand, specifying a small reporting queue size and large reporting thread pool size might cause faster processing of the events data but keeps the CPUs busier and at the same time when the traffic increases there is a possibility of data loss when the collection queue size is full.
    Default value is 5000.
    eventsRefreshInterval Specifies the default refresh interval for the events indices in seconds.
    The default value is 10 seconds.
    forwardInternalAPIsRequest This parameter is required in the case of a paired gateway deployment scenario using an Advanced Edition license at DMZ.
    Specifies whether the incoming requests are forwarded to internal APIs that are deployed in the green zone.
    Possible values:
    • true. API Gateway forwards the incoming requests to the internal APIs that are deployed in the green zone
    • false. API Gateway does not forward the incoming requests. This is the default value.
    Following are the internal APIs and their URIs for which this parameter is required and its value must be set to true:
    • getOAuthToken - /pub/apigateway/oauth2/getAccessToken
    • OAuth Authorization - /pub/apigateway/oauth2/authorize
    • getOpenIdToken - /pub/apigateway/openid/getOpenIDToken
    • openIDCallbackService - /pub/apigateway/openid/openIDCallback
    • getJWTToken - /pub/apigateway/jwt/getJsonWebToken
    forwardQueryParams Specifies whether API Gateway should forward the query parameter sent by client and query parameters configured in Request Processing stage to the native service if the ${sys:resource_path} variable is not present in the Routing policy URL.
    • true. API Gateway forwards the query parameters sent by client and query parameters configured in Request Processing stage to the native service even if the ${sys:resource_path} is not present in the Routing policy URL.
    • false. API Gateway does not forward the query parameters to the native service if the ${sys:resource_path} is not available in the Routing policy. This is the default value.
    gatewayClientInvokingToken Specifies the value of the client token that can invoke the backend APIs in API Gateway.
    The default value is apigateway.
    maxAllowedZipFileSize Specifies the maximum size of the zip file that can be uploaded to create an API from the Create API screen.
    Default value is 100000000.
    maxRegexLengthInSearchQuery Specifies the maximum length of Regex parameter that you can use in Regex expression query.
    Default value is 37000.
    This value can be increased based on the requirement.
    maxWindowSize
    Specifies the maximum number of search results that Elasticsearch can return for a single search request.
    Using the index.max_result_window property in Elasticsearch, you can configure the maximum number of records to be retrieved in a single Elasticsearch request. To know more about the property, refer https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html.
    Default value is 10000.
    If the value configured in the index.max_result_window setting of Elasticsearch is different from that of the default value, then it is recommended that you provide the same value in this field.
    If you have a value greater than the configured value, then Elasticsearch displays an error message. Also, you must enable the allowExceedMaxWindowSize setting if the total number of results to be retrieved is more than the value specified here.
    For example, if you have specified 1000 in this setting and the total number of records to be retrieved is 20000, then API Gateway sends 20 requests to retrieve all records provided the allowExceedMaxWindowSize setting is enabled. In the above example, if the allowExceedMaxWindowSize setting is not enabled, an error message is displayed as the value is lesser than the default value.
    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.3pSnmpSender.sendDelay This is an internal parameter. Do not modify.
    pg.cs.snmpTarget.base64Encoded This is an internal parameter. Do not modify.
    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.
    pg.uddiClient.publish.maxThreads Specify the maximum allowed number of threads to publish the performance metrics data to CentraSite.
    The default value is 2.
    pg.uddiClient.uddiClientTimeout Specify the number of milliseconds that can elapse before not publishing performance metrics to an unavailable API Gateway instance.
    The default value is 5000.
    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.
    tagsTypeAheadSearchResultSize Specifies the number of existing tags to display during the type ahead search.
    This is available while adding a tag to an API, where you can type a search term. A list of existing API tags appears depending on the search term. The number of API tags displayed in this list is restricted as per the value provided in the tagsTypeAheadSearchResultSizeproperty.
    The default value is 10.
    The minimum value you can provide is 1. If you provide zero or an invalid value, the value of this property is set to the default value 10.
    transferEncodingChunked_handleAsStream Specifies whether the request payload should be handled as stream when the request contains Transfer-Encoding:chunked header.
    The default value is false.
    The behavior is as follows depending on the value provided for this setting:
    • If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as stream.
    • If Transfer-Encoding: chunked header is sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as false, the request payload would be handled as is (no streaming).
    • If Transfer-Encoding: chunked header is not sent in the request, the request payload is handled as is (no streaming).
    • If Transfer-Encoding: chunked header is not sent in the request and the extended setting transferEncodingChunked_handleAsStream is set as true, the request payload is handled as is (no streaming).
    transformerPoolSize Specifies the maximum size for transform pool that consists XSLT transformers. To reduce performance impacts, you can reuse the transformers from the pool instead of creating them for every request.
    useTypeInIndexNameForESDestination Specifies the index format used when sending data from API Gateway to a configured Elasticsearch destination.
    The default value is true.
    Elasticsearch verison 7.2 supports data with dedicated index for each of the event types. So, API Gateway sends data in different indexes for different event types if the value of this property is set to true. The event type is concatenated with the Elasticsearch destination index name. That is, the index name will be in the following format: {IndexName}_{EventType}. For example, database_transactionalevents; where default is the index name and transactional events in the event type.
    If the value is set to false, the type name is not concatenated with the index name. In this case, the index created for each event is sub-indexed under a main index when data is sent to configured Elasticsearch destination. The value of this setting must be set to false, if the version of the destination Elasticsearch is 5.x or earlier.
    xmlToJSONConversion_keepString Specifies whether the data type of fields in a response payload, after XML to JSON conversion, must be string or a corresponding data type.
    The default value is true.
    Possible values:
    • true. The data type of the fields is retained as string.
    • false. The data type of the fields is changed to a corresponding data type.
    For example:
    Sample XML payload:
    <?xml version="1.0" encoding="UTF-8"?>
    <EmployeeDetail>
    <ID>12345</ID>
    <Name>John</Name>
    <Address>999 ABC Street</Address>
    </EmployeeDetail>
    • Sample response, if you set the extended setting to true:
      {
      "EmployeeDetail": {
      "ID": "12345",
      "Name": "John",
      "Address": "999 ABC Street"
      }
      }
      All fields in the response payload are retained as string.
    • Sample response, if you set the extended setting to false:
      {
      "EmployeeDetail": {
      "ID": 12345,
      "Name": "John",
      "Address": "999 ABC Street"
      }
      }
      The data type of the field ID is integer.
  5. You can configure the watt parameters in the Watt keys section by providing the required values.
    The configured watt keys are listed under Watt settings below the Extended keys at the top of the page. Only the following watt parameters get synchronized across nodes in a cluster setup:

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

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

  6. Click Save.

Configuring API Fault Settings

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

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

To configure the service fault settings

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

  2. Select General > API fault.

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

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

  5. Click Save.

Approval Configuration

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

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

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

API Gateway approvals can also be used when API Gateway is integrated with API Portal and an API Portal API consumer uses the API get access token to register an application to an API in API Gateway. In this scenario, API 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 API Portal. The consumer is now able to view and manage the API in API Portal.

Similarly, you can configure approvals for subscribing a package in API Gateway, when an API consumer subscribes to a package in API 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 API Portal and the package is subscribed.

Configuring Approvals for Creating Application

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

To configure approvals for creating an application

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

  2. Select General > Approval configuration > Create application.

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

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

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

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

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

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

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

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

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

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for creating an application is approved.

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

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

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

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

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

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

  15. Click Save.

Configuring Approvals for Registering Application

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

To configure approvals for registering an application

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

  2. Select General > Approval configuration > Register application.

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

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

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

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

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

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

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

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

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

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for associating an application with APIs is approved.

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

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

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

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

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

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

  15. Click Save.

Configuring Approvals for Updating Application

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

To configure approvals for updating an application

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

  2. Select General > Approval configuration > Update application.

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

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

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

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

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

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

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

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

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

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing application is approved.

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

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

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

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

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

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

  15. Click Save.

Configuring Approvals for Subscribing Package

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

To configure approvals for subscribing a package

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

  2. Select General > Approval configuration > Subscribe package.

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

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

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

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

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

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

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

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

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

    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approvers login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for subscribing a package is approved.

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

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

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

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

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

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

  15. Click Save.

Configuring Approvals for Updating Subscription

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

To configure approvals for updating a subscription

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

  2. Select General > Approval configuration > Update subscription.

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

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

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

    Note: If a user is associated with the team, then the user can approve or reject a pending request.

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for modifying an existing subscription.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for modifying an existing subscription is approved.

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

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

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

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

Configuring Approvals for Deleting Subscription

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

To configure approvals for deleting a subscription

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

  2. Select General > Approval configuration > Delete subscription.

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

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

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

    Note: If a user is associated with the team, then the user can approve or reject a pending request.

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

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

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

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

    Field Description
    Send notification To send an email notification to the approver to approve the request for deleting an existing subscription.
    Subject The subject line of the email to be sent.
    Content By default, the template appears. You can customize the email content.
    Note: The @ character acts as a place holder and the values are automatically generated by the system. For example, Hello @approver.name appears as Hello Joe in the email sent, where Joe is the approver’s login ID.

    Note: The email notifications are sent only to the local API Gateway users.

  10. Select Configure request approved mail template to be sent to requester.
    This is to configure the email template to be sent to the requester to notify that the request for deleting an existing subscription is approved.

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

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

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

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

Managing Pending Requests

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

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

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

To approve or reject a pending request

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

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

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

Deleting Requests

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

To delete a request

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

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

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

  4. Click Yes in the confirmation dialog.

URL Aliases

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

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

URL aliases have several benefits:

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

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

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

Creating URL Alias

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

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

To create a URL alias

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

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

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

    Field Description
    Alias The alias name of the proxy server.

    An alias name must be unique across API Gateway.

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

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

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

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

Enabling Partial Matching of URL Aliases

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

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

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

https://MyHost:9072/calc/deleteCalc

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

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

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

Modifying a URL Alias

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

  2. Select General > URL aliases.

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

  4. Incorporate the required changes.

  5. Click Save.

Deleting a URL Alias

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

  2. Select General > URL aliases.

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

  4. Click Yes in the confirmation dialog box.

Example - Usage Scenarios of URL Aliases

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

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

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

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

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

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

  2. Select General > URL aliases.

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

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

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

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

Custom Content-types

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

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

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

Content-type Identifier Payload validation
  • application/xml
  • text/xml
  • text/html
  • multipart/form-data
  • multipart/mixed
XPath XML schema
  • application/json
  • application/json/badgerfish
JSONPath JSON schema
text/plain Regex Regex

Note: The custom content-type feature is not supported for the SOAP to REST transformed APIs.

Configure Custom Content-types

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

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

To configure custom content-type

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

  2. Select General > Custom Content-types.

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

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

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

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

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

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

Configuring API Callback Processor Settings

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

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

To configure API callback processor settings

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

  2. Select General > Callback processor settings.

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

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

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

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

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

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

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

  7. Click Save.

Security Configuration

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

Keystore and Truststore

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

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

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

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

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

Configuring Keystore Information

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

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

  3. In the Keystores section, click Add keystore.

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

    Field Description
    Alias A text identifier for the keystore file.

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

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

  6. Type a password for the required key alias.

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

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

Configuring Truststore Information

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

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

  3. In the Truststores section, click Add truststore.

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

    Field Description
    Name A name for the truststore file.

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

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

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

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

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

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

Configuring Keystore and Truststore Information for Inbound Messages

API Gateway includes a list of SSL keystores and truststores.

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

To configure Keystore and truststore settings for inbound messages

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

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

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

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

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

    a. Restart the server after configuring keystore and truststore information for the configuration to take effect.

    b. Deactivate the APIs that have Inbound Authentication - Message policy enforced.

    c. Update the keystore and truststore configuration.

    d. Activate the APIs that were deactivated.

Configuring Keystore and Truststore Information for Outbound Connections

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

To configure keystore and truststore settings for outbound secured connections

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

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

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

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

Modifying Keystore Information

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

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

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

  4. Modify the fields as required.

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

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

  6. Type a password for the alias to be configured.

  7. Click Save.
    The keystore is updated.

Deleting Keystore Information

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

To delete keystore information

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

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

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

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

Modifying Truststore Information

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

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

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

  4. Modify the fields as required.

  5. Click Save.
    The truststore is updated.

Deleting Truststore Information

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

To delete keystore information

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

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

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

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

Global IP Access Settings For Ports

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

Configuring Restriction to IP Address based on Authentication

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

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

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

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

Note:

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

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

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

    2. Select Security > Global IP Access Settings.

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

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

    SAML Issuer

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

    To add a SAML issuer

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

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

    3. Click Add SAML issuer.

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

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

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

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

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

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

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

      Provide the following information:

      • Username. Specify a username.

      • Password. Specify a password.

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

      Provide the following information:

      • Client principal. A valid client LDAP user name.

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

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

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

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

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

      Provide the following information:

      • Client principal. A valid client LDAP user name.

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

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

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

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

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

      Provide the following information:

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

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

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

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

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

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

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

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

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

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

    Custom Assertions

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

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

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

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

    Binding Assertions

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

    API Gateway supports the following WS-SecurityPolicy binding assertions:

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

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

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

    Token Assertions

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

    API Gateway supports the following WS-SecurityPolicy token assertions:

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

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

    Policy Assertions

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

    Creating a Custom Assertion

    Pre-requisites:

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

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

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

    To create a custom assertion

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

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

    3. Click Add assertion.

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

      • Binding

      • Token

      • Policy

    5. Provide the following information:

      Field Description
      Name Name of the custom assertion. For a binding or token assertion type, this is the display name of the assertion in the Binding Assertion field or Custom Token Assertion of the Inbound Authentication - Message policy.

      For a policy assertion type, this is the display name of the assertion in the Issuer Policy field of the Add SAML Issuer configuration page.
      Select file Click Browse and select the policy assertion file to be uploaded. The Assertion element text box displays the data from the assertion file.

      If you have uploaded the policy assertion file and want to replace it, click the Delete icon.
      Assertion element If you have not uploaded the policy assertion file, provide the XML representation of assertion.
    6. Click Add. The custom assertion is added. You can create as many custom assertions you require.

    Post-requisites:

    To enforce the custom binding or token assertion in an API, select the assertion in the appropriate fields of the Inbound Authentication - Message policy:

    To enforce the custom policy assertion in an API, select the assertion and the corresponding SAML issuer in the appropriate fields:

    Viewing Custom Assertion List and Assertion Configuration

    You can view the list of configured custom assertions in API Gateway. In addition, you can view and modify the configuration in the individual custom assertion details page.

    To view a list of custom assertions and assertion configuration

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.
      You can delete a custom assertion by clicking its Delete icon.

    3. Click any custom assertion to view the configuration details.
      The custom assertion details page displays the XML element.

    Modifying Custom Assertion

    Pre-requisites:

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

    You might want to modify a custom assertion to change the currently defined security settings, such as, authentication scheme, signing and encryption, algorithms and supporting tokens, of SOAP messages.

    To modify a custom assertion

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.

    3. Select the required custom assertion that you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The custom assertion is updated.

    Post-requisites:

    When you are ready to put the policy assertion into effect in an API, select it in the appropriate field of Inbound Authentication - Message policy.

    Deleting Custom Assertion

    Pre-requisites:

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

    You delete a policy assertion to remove it from API Gateway permanently.

    To delete a policy assertion

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

    2. Select Security > Custom assertions.
      A list of all available custom assertions appears.

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

    4. Click Yes in the confirmation dialog.
      The custom assertion is deleted from API Gateway.

    Example - Custom Assertions

    API Gateway, by default, uses the asymmetric binding assertion with X.509v3 token for implementing SOAP message protection. If you would like to enforce any authentication (other than the predefined authentications shipped with API Gateway), include additional WSS custom assertions, sign and encrypt SOAP messages, and define custom properties, such as the algorithms and layout of security header, you can create custom assertions that would construct the custom policy file to suit your specific security requirements.

    Following is a policy file that API Gateway generates when a WSS username token is enforced by the Inbound Authentication Message policy for an API.

    
    <wsp:Policy wsu:Id="9dbda2fb-9cef-4ff9-bc70-115c942a3b76" 
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
         oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <wsp:ExactlyOne>
            <wsp:All>
    (L01) <sp:AsymmetricBinding xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:InitiatorToken>
                <wsp:Policy>
                    <sp:X509Token sp:IncludeToken
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
                                                                /IncludeToken/Never">
        <wsp:Policy>
                    <sp:WssX509V3Token10 />
                </wsp:Policy>
            </sp:X509Token>
        </wsp:Policy>
        </sp:InitiatorToken>
        <sp:RecipientToken>
            <wsp:Policy>
                <sp:X509Token sp:IncludeToken=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy
                 /200702/IncludeToken/Never">
            <wsp:Policy>
                <sp:WssX509V3Token10 />
            </wsp:Policy>
                </sp:X509Token>
                    </wsp:Policy>
                        </sp:RecipientToken>
                        <sp:AlgorithmSuite>
                            <wsp:Policy>
                                <sp:TripleDesRsa15 />
                            </wsp:Policy>
                        </sp:AlgorithmSuite>
        <sp:Layout>
            <wsp:Policy>
            <sp:Strict />
            </wsp:Policy>
        </sp:Layout>
            <sp:ProtectTokens/>
            </wsp:Policy>
            </sp:AsymmetricBinding>
            <sp:SupportingTokens xmlns:sp=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
            <wsp:Policy>
                <sp:UsernameToken sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                 IncludeToken/AlwaysToRecipient"/>
                    </wsp:Policy>
                        </sp:SupportingTokens>
                    </wsp:All>
                </wsp:ExactlyOne>
        </wsp:Policy>
    
    

    You might have a requirement to change the policy assertion that is available by default in API Gateway. For example, you might want to generate the above security policy using a symmetric binding instead of the default asymmetric binding, and modify the username token that is defined by default as a supporting token to a signed supporting token. You could then create custom policy assertions to achieve these specific requirements.

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

    Symmetric Binding Assertion

    You might want to use a symmetric binding (instead of the default asymmetric binding) when only API Gateway possess the X.509v3 token for authentication. You might also want to sign and encrypt the SOAP messages, modify the encryption algorithm, and include timestamp on the SOAP messages. You would then create a custom binding assertion with the specific property lines:

    
        
    <sp:SymmetricBinding
    xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
    xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsp:Policy>
    <sp:ProtectionToken>
    <wsp:Policy>
    <sp:X509Token sp:IncludeToken=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
     IncludeToken/AlwaysToRecipient">
        <wsp:Policy>
        <sp:WssX509V3Token10/>
        <sp:WssX509PkiPathV1Token10/>
        </wsp:Policy>
        </sp:X509Token>
        </wsp:Policy>
        </sp:ProtectionToken>
        <sp:AlgorithmSuite>
        <wsp:Policy>
        <sp:TripleDesRsa15/>
        </wsp:Policy>
        </sp:AlgorithmSuite>
        <sp:Layout>
        <wsp:Policy>
        <sp:Strict/>
        </wsp:Policy>
        </sp:Layout>
        <sp:IncludeTimestamp/>
        <sp:ProtectTokens/>
        <sp:OnlySignEntireHeadersAndBody/>
        <sp:SignBeforeEncrypting/>
        </wsp:Policy>
        </sp:SymmetricBinding>
        
    

    You could create custom assertions to include one or more of the following security requirements:

    Supporting Token Assertions

    You might want to sign the supporting token for example, WSS username token, and use SignedSupportingTokens assertion. You might also want to specify that the signed username token must always be included in the messages sent to the recipient. You would then create a custom token assertion with the specific property lines:

    
        
    <sp:SignedSupportingTokens xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
        <wsp:Policy>
            <sp:UsernameToken sp:IncludeToken=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                                             IncludeToken/AlwaysToRecipient"/>
                </wsp:Policy>
            </sp:SignedSupportingTokens>
        
    

    WSS Token Assertions

    You might want to include WSS10 and WSS11 assertions to provide additional SOAP message security. You would then create two separate custom token assertions with the specific property lines:

    Wss10 assertion:

    
    <sp:Wss10
            xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:MustSupportRefIssuerSerial/>
        </wsp:Policy>
    </sp:Wss10>
        
    

    Wss11 assertion:

    
        
    <sp:Wss11
        xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
        <wsp:Policy>
            <sp:MustSupportRefIssuerSerial/>
            <sp:MustSupportRefThumbprint/>
            <sp:RequireSignatureConfirmation/>
        </wsp:Policy>
    </sp:Wss11>
        
    

    After you have defined these custom assertions in API Gateway, execution of a policy that is configured with all of these custom assertions in the Inbound Authentication - Message policy, would construct the custom security policy file as follows:

    
        
    <wsp:Policy wsu:Id="1e747a18-b55d-4e99-ac67-80a8eafd76b3"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                 oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsp:ExactlyOne>
        <wsp:All>
            <sp:SymmetricBinding xmlns:sp=
        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
            <wsp:Policy>
                <sp:ProtectionToken>
            <wsp:Policy>
            <sp:X509Token sp:IncludeToken=
            "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
             IncludeToken/AlwaysToRecipient">
                        <wsp:Policy>
                            <sp:WssX509PkiPathV1Token10/>
                        </wsp:Policy>
            </sp:X509Token>
            </wsp:Policy>
        </sp:ProtectionToken>
        <sp:AlgorithmSuite>
                    <wsp:Policy>
                        <sp:TripleDesRsa15/>
                    </wsp:Policy>
        </sp:AlgorithmSuite>
        <sp:Layout>
        <wsp:Policy>
                <sp:Strict/>
        </wsp:Policy>
        </sp:Layout>
        <sp:OnlySignEntireHeadersAndBody/>
        </wsp:Policy>
        </sp:SymmetricBinding>
        <sp:SignedSupportingTokens xmlns:sp=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                    <wsp:Policy>
                        <sp:UsernameToken sp:IncludeToken=
                        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/
                     IncludeToken/AlwaysToRecipient"/>
                    </wsp:Policy>
        </sp:SignedSupportingTokens>
                    <sp:Wss11 xmlns:sp=
                    "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                    <wsp:Policy>
                    <sp:MustSupportRefIssuerSerial/>
                    <sp:MustSupportRefThumbprint/>
                    <sp:RequireSignatureConfirmation/>
        </wsp:Policy>
        </sp:Wss11>
                    <sp:Wss10 xmlns:sp=
                            "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                        <wsp:Policy>
                        <sp:MustSupportRefIssuerSerial/>
                        </wsp:Policy>
                    </sp:Wss10>
                    <sp:EncryptedParts xmlns:sp
                        "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
                        <sp:Body/> 
                    </sp:EncryptedParts>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    
    

    Kerberos Settings

    Kerberos is an authentication protocol that uses symmetric encryption and a trusted third party system to validate the identity of clients. The Kerberos protocol provides authentication over open and insecure networks in which communication between the hosts can be intercepted.

    You can use API Gateway to configure Kerberos authentication for API requests. API Gateway provides support for using Kerberos authentication for inbound and outbound HTTP and HTTPs requests at the transport and the message level.

    Kerberos authentication system consists of the a Kerberos client that needs to access and use Kerberos services, a trusted third-party system, specifically a Key Distribution Center (KDC) and a server that hosts APIs that are accessible using Kerberos authentication.

    Configuring API Gateway to Use Kerberos

    Before you configure API Gateway to use Kerberos authentication, ensure that:

    To configure API Gateway to use Kerberos

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

    2. Select Security > Kerberos.

    3. Click Edit.

    4. Provide or modify the following information as required:

      Field Description
      Realm Optional. The domain name of the Kerberos server, in uppercase letters.

      Note: A value specified for Realm overwrites the realm set in the KDC configuration file specified in Kerberos configuration file.
      Key distribution center Optional. The host name of the machine on which the KDC resides.

      A value specified for Key distribution center overwrites the default key distribution center set in the KDC configuration file specified in Configuration file.
      Configuration file The location of the Kerberos configuration file that contains the Kerberos configuration information, including the locations of KDCs, defaults for the realm and for Kerberos applications, and the host names and Kerberos realms mappings.
      Use subject credentials Specifies whether API Gateway requires a Kerberos V5 Generic Security Services (GSS) mechanism to obtain the necessary credentials from an existing subject set up by the JAAS authentication module. Here, subject represents the user or service being authenticated in the JAAS login context.
    5. Click OK.

    OAuth, JWT, and OpenID Configuration

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

    OAuth Authentication Use Case and Workflow

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

    The OAuth authorization framework includes the following terms:

    Roles

    Authorization Grant Types

    Clients

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

    API Gateway as a Resource Server

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

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

    API Gateway as an Authorization Server

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

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

    Using API Gateway with an External Authorization Server

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

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

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

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

    Authorizations for applications created from API Portal

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

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

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

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

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

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

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

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

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

    6. Get access token through the following URLS:

      invoke/pub.apigateway.oauth2/authorize

      invoke/pub.apigateway.oauth2/getAccessToken

    7. Use the access token to invoke the API.

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

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

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

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

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

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

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

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

    7. Get the access token from the authorization server.

    8. Use the access token to invoke the API.

    OAuth Authorization Workflow

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

    icon

    The OAuth authorization workflow is as follows:

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

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

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

    4. API Gateway then performs the following:

      a. Identifies the application using the client ID.

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

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

      d. Checks the audience.

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

    JWT Authentication Use Case and Workflow

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

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

    Note: JWT authentication is supported for both REST and SOAP APIs.

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

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

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

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

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

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

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

      getJsonWebtoken

      Used for user authentication without custom claims

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

      • Method: GET

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

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

      Used for application authentication with custom claims.

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

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

      • Method: POST

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

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

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

    Use case 2: API Gateway with an external JWT issuer

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

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

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

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

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

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

    JWT Authorization Workflow

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

    icon

    The JWT authorization workflow is as follows:

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

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

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

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

      Note: If API Gateway has generated the JSON token, it validates the signature using a public certificate that was specified in the JWT configuration. Else, if the HTTP request is sent from a third-party JWT issuer, API Gateway validates the token using a public certificate or the JWKS URI of the issuer.

    OpenID Authentication Use Case and Workflow

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

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

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

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

    exchangeIDToken

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

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

    Note: The getOpenIDtoken call is deprecated and is no more available from the API Gateway release 10.3 onwards.

    Use case 1: OpenID authentication using OpenID Connect Provider

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

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

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

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

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

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

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

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

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

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

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

        exchangeIDToken

        • Method: POST

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

        • Payload:

          {
          "gatewayScopes": ["OktaTenant1:inventory"],
          "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQwYzZiMDliNDQ5NjczNDUzYzNkYTY"
          "expiry": 3000
          }
          
      • The user presents the ID token as a JWT directly to API Gateway (if the user has configured the JWT option in step 4), and on validation accesses the protected resource.

    OpenID Authorization Worklow

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

    OpenID authorization workflow using the OpenID Connect Provider

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

    icon

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

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

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

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

    4. API Gateway then performs the following:

      a. Identifies the application using the client ID.

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

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

      d. Checks the audience.

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

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

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

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

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

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

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

      exchangeIDToken

      • Method: POST

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

      • Payload:

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

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

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

    6. API Gateway then performs the following:

      a. Identifies the application using the client ID.

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

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

      d. Checks the audience.

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

      Note: The user can present the ID token directly as a JWT to access the protected resources in case the ID token is provided on configuring the JWT property in the Identify and authorize application policy enforced on the API.

    Configuring the Internal Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add an authorization server.

    You have to configure API Gateway with the required information to act as an internal authorization server for OAuth or JWT depending on what authentication protocol you want to use to identify and authorize a client application. You can also define the required scopes that provide a way to limit the amount of access that is granted to an access token.

    To configure an internal authorization server

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

    2. Select Security > OAuth/JWT/OpenID.

    3. In the Internal Authorization servers section, click local. This is the internal authorization server available that you can configure with required information to act as an internal authorization server for OAuth, JWT or OpenID authentication protocols.

    4. The name field is pre-populated with the name of the internal authorization server, local, which is non-editable.

    5. The description for the internal authorization server is pre-populated with the description available. You can modify the description as required.

    6. Click JWT configuration to configure API Gateway as a JWT issuer. Alternatively you can expand or collapse a section, using the down arrow icon and the up arrow icon and that appear next to the section name.

    7. Provide the following information as required:

      Field Description
      Token issuer Name of the JWT token issuer used by API Gateway.

      Note: The Token issuer value is case-sensitive.
      Algorithm The cryptographic algorithm to sign JSON Web Tokens (JWTs).

      Supported values are: RS256, RS384, and RS512.
      Expiry duration The duration (in minutes) for which the token is valid.

      For example, the value 60 denotes that the access token will expire in one hour from the time the token was generated.
      Audience Optional. The intended recipient of the token. The application that receives the token must verify that the audience value is correct and reject any tokens intended for a different audience.
      Keystore alias Alias of the keystore containing the private key that is used to sign JWTs.

      The Keystore alias field contains a list of the available keystore aliases in API Gateway. If there are no configured keystore aliases, this field displays the DEFAULT_IS_KEYSTORE.
      Key alias Alias of the private key used to sign JWTs.

      The Key alias field contains a list of the available aliases in the selected keystore. If there are no configured keystores, this field is empty.
    8. Click OAuth configuration to configure API Gateway as an OAuth authorization server. Alternatively you can expand or collapse a section, using the down arrow icon and the up arrow icon and that appear next to the section name.

    9. Provide the following information as required:

      • Authorization code expiration interval. Specifies the time (in seconds) during which the authorization code issued by the authorization server is valid. Valid values are between 1 and 2147483647. The default value is 600.

      • Access token expiration interval. Specifies the time (in seconds) for which the access tokens issued by the authorization server are valid. The default value is 3600. Value of -1 specifies that the access token does not expire.

    10. Click OAuth tokens.

      This lists the available OAuth tokens with the following details:

      • Client ID. Specifies the ID of the client application that requested the access token.

      • Owner ID. Specifies the ID of the owner who issues the access token.

      • Access token. Specifies the access token.

      • Refresh token. You can use to generate a new access token if the existing access token is expired.

      • Remaining refresh limit. Displays the remaining attempts for refreshing the access token.

      • Action. Revokes the access tokens, which means those tokens cannot be used to invoke the protected resource. For information about revoking access token using REST API, see Revoking OAuth Tokens.

      Note By default, API Gateway lists only 5 records and provides pagination to explore more tokens. You can also use the search and filter options to find the OAuth tokens.

    11. Click OAuth scopes.
      OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client application may be granted READ and WRITE access to the protected resources, or just the READ access. You can implement your APIs to enforce any scope or a combination of scopes as required. So, if a client receives a token that has READ scope, and it tries to invoke an API endpoint that requires WRITE access, the invocation fails.

      You can provide the meaning to the scope in OAuth/OpenID scopes management section.

    12. Type the scope that is registered in the authorization server and click +Add.
      You can include multiple scopes.

    13. Click Update.
      This updates the internal authorization server details with the required information and is listed in the table of Internal authorization server.

    Adding a Provider

    Pre-requisites:

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

    The OAuth 2.0 configuration in API Gateway is split into two sections - Providers and Authorization servers.

    You have to add a provider and configure the authorization provider metadata information in this section for API Gateway to communicate with this provider during dynamic client registration only. If there is any deviation from the actual OAuth specification then the provider has to be configured for these deviations.

    To add a provider

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

    2. Select Security > JWT/OAuth/OpenID > Providers.

    3. Click Add provider and provide the following information:

      Field Description
      Name Name of a third-party provider. For example, Amazon.

      You can also use one of the following pre-configured third-party providers that is shipped with the API Gateway installation:

      • PingFederate

      • OKTA
      Client metadata field mapping. Specifies the mapping of dynamic client registration specification to that of the client implementation of the provider.

      The Client metadata field mapping fields are required when you are adding a third-party provider that is not shipped with API Gateway.
      Specification name The client metadata attributes in accordance with the dynamic client registration specification as defined in RFC 7591. The available values are:

      • redirect_uris. Redirection URL that the authorization server uses to redirect the authorization code once the authorization request is approved by end user.
        Note: If you do not specify this attribute, API Gateway automatically generates the URL.

      • token_endpoint_auth_method. The client authentication method at the token endpoint.

      • grant_types. The grant type of authorization flow to obtain authorization codes, ID tokens, and refresh tokens.

      • application_type

      • response_types. The type of response that the client application uses at the authorization endpoint.

      • client_name. Name of the client to use to represent the client application to the end user during authorization.

      • client_uri. URL of the client application.

      • logo_uri. URL of an image to use to represent the client application to the end user during authorization.
        Note: The logo_uri is currently not supported in API Gateway.

      • scope. List of user-authorized scopes that the client uses for requesting access tokens.
        Note: If you do not specify this attribute, the authorization server registers the client with a default set of scopes.

      • contacts. The means (for example, Email address) by which end users can contact the client for support requests.

      • tos_uri. URL of the service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client.
        Note: The tos_uri is currently not supported in API Gateway.

      • jwks_uri. URL of the JSON Web Key (JWK) Set document containing the client’s public keys.
        Note: The jwks_uri is currently not supported in API Gateway.

      • client_id. Identifier that is unique to the client application.

      • client_secret. The password or phrase for the client application to use to authorize communication with the end user.
      Implementation name The client metadata attributes that are used by the authorization server, but are not in accordance with the dynamic client registration specification.

      Example:

      • For the redirect_uris field, provide the value redirectUris.

      • For the grant_types field, provide the value grantTypes.

      • For the client_name field, provide the value name.

      • For the logo_uri field, provide the value logoUrl.

      • For the client_id field, provide the value clientId.

      • For the client_secret field, provide the value secret.
      Extended request parameters. Specifies the additional client metadata attributes that are specific to the authorization server, and are not specified in the dynamic client registration specification.

      In PingFederate (For example): forceSecretChange = true
      Type Specifies the client metadata attribute type. The available values are: Client read, Client registration, Client update, Client delete.
      Key The client metadata attribute key that is specific to the authorization server.
      Value A value for the client metadata attribute key. When sending requests to the authorization server, this value is appended to all requests.
      You can add multiple request parameters by clicking + Add.
      Application profile Specifies the application profile that is specific to the authorization server.
      Type Specifies custom application type other than web and native.
      By default, the web and native application is added.
      You can add multiple application type by clicking + Add. You can also modify and delete the added application type by clicking the respective Edit or Delete icon.
      You can add multiple request parameters by clicking + Add.

    4. Click Save.
      The provider is added and displayed in the list of providers.

    Adding an External Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to add an authorization server.

    As an alternative to using API Gateway as the authorization server, you can use a third-party server as the authorization server. To use an external authorization server, you must configure your third-party authorization server.

    To add an external authorization server

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

    2. Select Security > OAuth/JWT/OpenID.
      The available and configured internal authorization servers and external authorization servers are listed in the respective sections.

    3. Click Add authorization server in the External authorization servers section.

    4. Type a name for the external authorization server.

    5. Type a description for the external authorization server that is being configured.

    6. Provide the discovery endpoint in the Discovery URL field and click Discover.
      When you specify the discovery URL, API Gateway fetches data from the URL response and auto-populates the fields with the fetched data.

    7. Click Introspection and provide the following information to validate the incoming tokens.

      Field Description
      Local introspection. Provide the following information to validate the tokens locally.
      Issuer Name of the token issuer.
      JWKS URI Specifies JSON Web Key Signature endpoint to retrieve the corresponding public certificates for performing local introspection.
      API Gateway's cache has a key as *kid* claim and its value is the certificate corresponding to the *kid* claim. The cache is populated on every restart of API Gateway by invoking the JWKS URI. In the runtime, while validating the token using the local introspection, the *kid* value from the incoming JWT is fetched and the corresponding certificate is retrieved from the cache and the signature validation happens.
      Truststore alias Specify the alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.

      This is required if the JWKS URI is not available for the authorization server and you want to configure this certificate directly.
      Certificate alias Alias of the certificate used to validate the token.

      The Certificate alias field contains a list of the available aliases in the selected truststore. If there are no configured truststores, this field is empty.
      Remote introspection. Provide the following information to validate the tokens remotely if local introspection cannot be done.
      Introspection endpoint URL of the token introspection endpoint of a third-party OAuth 2.0 authorization server. API Gateway uses the introspection endpoint to check that access tokens used in client requests are currently active and are valid to invoke the protected resources.
      Gateway user The name of the Gateway user that API Gateway uses to invoke the token introspection endpoint.
      Client ID ID of the introspection client on the authorization server that API Gateway uses to introspect the access tokens.
      Client secret Password of the introspection client that API Gateway uses to introspect the access tokens.
    8. In the Dynamic client registration section, provide the following information if you want to dynamically create a client from API Gateway when required. You would use this configuration only if you do not intend to use any of the existing clients.

      Field Description
      Enabled Specifies whether dynamic client registration is enabled.

      Click the toggle button to change the state to icon to enable dynamic client registration.

      By default this option is disabled.
      Provider name Select the name of the third-party provider.
      Client registration URL Specifies the corresponding REST endpoint URLs for the client configuration of REST APIs.
      Authentication type Specifies the type of authentication scheme that API Gateway would use to communicate with the external authorization server for client management.

      Select one of the following authentication type:

      • Basic. Specifies the username and password information that would be passed in the authorization header of HTTP request for client authentication.

        • Username. The username to access the protected resources of REST APIs.

        • Password. A valid password associated with the username.

      • Token. Specifies the token information that would be added as a bearer token in the HTTP request for client authentication.

        • Token type. The type of token that would be contained in the HTTP request.

        • Token. The token that would be contained in the HTTP requests.
      • Refresh Token.The refresh token that you would get from the external authorization server for the registered client ID and client secret.

        • Client ID. The client ID that you want to specify from the external authorization server.

        • Client secret. A valid client secret associated with the client ID.
      • Client Credentials.Specifies the client information for which the application is created in the external authorization server.

        • Scope. The scope of the client application that you want to specify from the external authorization server.

        • Client ID. The client ID that you want to specify from the external authorization server.

        • Client secret. A valid client secret associated with the client ID.
      • None.Specifies that you could create the client dynamically in the external authorization server without using any type of authorization.
      Supported grant types Specifies the list of grant types that are supported by API Gateway.Basically, grant types are the ways to get an access token from the external authorization server. Provide the grant type, in the Supported grant types field and click +Add.You can add more than one grant by clicking +Add.
    9. In the SSL Configuration section, provide the following information for SSL configuration, if the authorization server wants the 2-way SSL for the requests.

      Field Description
      Keystore alias Alias of the keystore containing the private key that is used for a secured communication between API Gateway and the authorization server.

      You can view all the keystore aliases available in API Gateway. If there are no configured keystore aliases, the list box contains only the default keystore, DEFAULT_IS_KEYSTORE.
      Key alias Alias for the private key to use to validate the HTTP requests from the client.

      You can view all the aliases available in the selected keystore. If there are no configured keystores, this list box is empty.
      Truststore alias Alias of the truststore on API Gateway that holds the Certificate Authority (CA) certificate of third-party authorization server.

      Note: You need to select a truststore alias only when all of the following are true:

      • The client account on the third-party authorization server is configured to use mutual (two-way) SSL, and

      • The authorization server’s Certificate Authority certificate is not in the set of well-known authorities trusted by the JVM in which API Gateway runs.
    10. In the Metadata section, provide the following information for the authorization server metadata, which is used for the communication to portal.

      Field Description
      Access token URL The endpoint URL on the authorization server through which the client application exchanges the authorization code, client ID, and client secret, for an access token.
      Authorize URL The endpoint URL on the authorization server through which the end user authenticates and grants authorization to the client application.
      Refresh token URL The endpoint URL on the authorization server through which the client application refreshes an expired access token.
    11. Click Scopes.
      OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. For example, an access token issued to a client application may be granted READ and WRITE access to the protected resources, or just the READ access. You can implement your APIs to enforce any scope or a combination of scopes as required. So, if a client receives a token that has READ scope, and it tries to invoke an API endpoint that requires WRITE access, the invocation fails.

      You can provide the meaning to the scope in OAuth/OpenID scopes management section.

    12. Provide the scope, in the Scope field that is registered in the authorization server and click +Add.
      You can add more than one scope by clicking +Add.

    13. Click Save. The external authorization server is added.
      You can add as many authorization servers as required, but only one is the default at any given time.

    Mapping OAuth or OpenID Scopes

    You must have the API Gateway’s manage security configurations functional privilege assigned to manage scopes.

    You have to map the scope that you have defined in the authorization server with the APIs in API Gateway to authorize the access tokens to be used to access the protected resources. You can map either a complete API or parts (resources or methods) of an API to the scope.

    For example, if there is a scope you have defined for an external authorization server, such as readonly, then the access tokens which contain readonly as their scope, should access only the GET resources. So, you can create an API Scope for the GET resources in an API or for multiple APIs and then map this readonly scope to all those API Scopes. Now this access token can invoke only the GET resources. If it tries to invoke any POST or PUT resource it fails. As another example you can consider mapping a business scope such as, inventory, that you have defined in the authorization server; you can map all the resources required for the inventory business to this scope.

    To map a scope

    1. Expand the menu options icon icon, in the title bar, and select OAuth/OpenID scopes.

    2. Click Map scope.

    3. Provide the following information in the Authorization server scope section:

      Field Description
      Select authorization server scope Specifies the scope linked to the authorization server. Type a search word and select the required scope from the search list populated.
      Name Displays the name of the authorization server scope selected. This is populated by default and is non-editable.
      Description A brief description for the scope being mapped.
      Audience Provide a value or URI, the intended recipient of the authorization server scope. The application that receives the token verifies that the audience value is correct and rejects any tokens intended for a different audience.
    4. Click API scopes.

    5. Specify an API scope that is to be linked to the authorization server.
      Alternatively, you can type a search word and select the required API scope from the search list populated.
      The API scopes added are listed in the Selected API scopes table. You can click the delete icon icon, in the corresponding column, to delete an API scope from the list.

    6. Click Save.

    This maps the authorization server scope to the selected API scopes and lists the authorization scope in the scopes list.

    Viewing Scope Mapping Details

    You must have the API Gateway’s manage security configurations functional privilege assigned to manage scopes.

    You can view the scope details and modify the scope details as required from the OAuth/OpenID scopes page.

    To view scope mapping details

    1. Expand the menu options icon icon, in the title bar, and select OAuth/OpenID scopes.
      A list of available scopes appears. Use the Show drop-down list at the bottom of the page to set the maximum number of scopes you want to display in a page. The details, such as, name and description of the scope is displayed in the form of a table. You can delete a scope by clicking the delete icon icon.

    2. Click a scope.
      The scope details page appears. This page displays the details such as the authorization server name, the server scope, the API scopes that are linked to the server scope and the API scope details such as the API to which the scope is associated, the description of the API and API version number.

      You can modify the scope by clicking the Edit button and modifying the required values.

    Viewing Provider List and Provider Configuration

    You can view the list of integrated third-party providers and their configuration details, modify the provider configuration, and delete a provider in the Providers section.

    To view a list of providers and provider configuration

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

    2. Select Security > JWT/OAuth/OpenID > Providers.
      The Providers section displays a list of all the defined third-party providers in API Gateway.

      You can also perform the following operations in the Authorization servers section:

      • You can view the configuration details of the provider by clicking the required provider. The provider details page displays the client metadata field mapping and extended request parameter configuration information of the selected provider.

      • You can edit the provider configuration by clicking the required authorization server and modifying the details as required.

      • You can reset the configuration to system default value by clicking icon in the Action column for the respective provider.

      • You can delete the required authorization server by clicking icon in the Action column for the respective provider.

    Modifying the Provider Configuration

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to modify a provider.

    You might want to modify a provider to change the currently defined configuration settings.

    To modify a provider configuration

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

    2. Select Security > JWT/OAuth/OpenID > Providers.
      The Providers section displays a list of all the available providers in API Gateway.

    3. Click the name of the partner provider you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The provider is updated.

    Viewing Authorization Server List and Server Configuration

    You can view the list of authorization servers and their configurations details, modify the server configuration, and delete an authorization server in the Authorization servers section.

    To view a list of authorization servers and server configuration

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

    2. Select Security > JWT/OAuth/OpenID.
      The Authorization servers section displays a list of all the internal and external authorization servers in API Gateway under respective sections.

      You can also perform the following operations in the Authorization servers section:

      • You can view the configuration details of the authorization server by clicking the required authorization server. The authorization server details page displays the client information, scope information, and token information of the selected authorization server.

      • You can edit the server configuration by clicking the required authorization server and modifying the details as required.

      • You can delete the required authorization server by clicking icon in the Action column for the respective authorization server.

    Modifying Authorization Server Configuration

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to modify an authorization server.

    You might want to modify an OAuth 2.0 authorization server to change the currently defined configuration settings.

    To modify the authorization server configuration

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

    2. Select Security > JWT/OAuth/OpenID.
      The Authorization servers section displays a list of all the internal and external authorization servers in API Gateway.

    3. Click the name of the authorization server you want to modify.

    4. Modify the fields as required.

    5. Click Save.
      The authorization server is updated.

    Deleting an Authorization Server

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to delete an authorization server.

    You delete an authorization server to remove it from API Gateway permanently.

    To delete an authorization server

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

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

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

    4. Click Yes in the confirmation dialog.
      The authorization server is deleted from API Gateway.

    Deleting a Provider

    Pre-requisites:

    You must have the API Gateway’s manage security configurations functional privilege assigned to delete a provider.

    You delete a provider to remove it from API Gateway permanently.

    Important: You must not delete a provider if it is being used by an authorization server.

    To delete a provider

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

    2. Select Security > JWT/OAuth/OpenID.
      The Providers section displays a list of available providers in API Gateway.

    3. Click icon in the Action column of the provider to be deleted.

    4. Click Yes in the confirmation dialog.
      The provider is deleted from API Gateway.

    Configuring Communication Details for Microgateway

    When you want Microgateway to use API Gateway as an OAuth2 authorization server, the communication channel between Microgateway and API Gateway has to be set up. The access token is then introspected in the Microgateway using remote introspection. To enable this you have to configure communication details, such as the introspection endpoint, client ID and client secret, in API Gateway, which are then used by Microgateway to introspect the tokens in API Gateway.

    To configure the communication details for Microgateway

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

    2. Select Security > JWT/OAuth/OpenID > Microgateway.

    3. In the Introspection endpoint field, provide the URL of the introspection endpoint.
      For example: http&colon;//localhost/invoke/pub.oauth/introspectToken. The endpoint can have http or https depending on the protocol used and the hostname is the detail of the host used.

      Microgateway uses the introspection endpoint to check that access tokens used in client requests are currently active and are valid to invoke the protected resources.

    4. In the Client ID field, provide an ID, which specifies the ID of the introspection client on the authorization server that Microgateway uses to introspect the access tokens.

    5. In the Client secret field, provide the Client secret, which specifies the password of the introspection client that Microgateway uses to introspect the access tokens.

    6. In the JWKS URI field, provide the JSON Web Key Signature endpoint to retrieve the corresponding public certificates for performing local introspection.

      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. Microgateway’s cache has a key as kid claim and its value is the certificate corresponding to the kid claim. The cache is populated on every restart of Microgateway by invoking the JWKS URI. In the runtime, while validating the token using the local introspection, the kid value from the incoming JWT is fetched and the corresponding certificate is retrieved from the cache and the signature validation happens.

    7. Click Save.

      The information provided here is stored in the configuration properties file and provisioned as part of the asset provisioning during Microgateway startup.

    Removing Expired OAuth Tokens

    You can remove all the expired OAuth access tokens using the given API.

    You can also schedule the cleanup of the expired OAuth access tokens as required.

    To remove expired OAuth tokens

    1. Make a REST call to the following endpoint:

      GET hostname/invoke/pub.oauth/removeExpiredAccessTokens

    Revoking OAuth Tokens

    You can revoke the OAuth access token from an application using the given API.

    To revoke OAuth token from an application

    1. Make a REST call to the following endpoint with the corresponding client Id and secret of the application in Basic authentication header:

      POST hostname/invoke/pub.oauth/revokeToken

      Sample request

    
    
        POST http(s)://hostname/invoke/pub.oauth/revokeToken
        { "token":"3d77988d5020493c8edde78b12c347e2046ac8438a91405597e669ed714ba96a",
        "token_type_hint":"accessToken"}
    
        
    

    Audit Logging

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

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

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

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

    Best Practices for API Gateway Audit Logging

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

    Configuring Audit Logs

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

    The following events are available for audit log reports:

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

    To configure audit logs

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

    2. Select Destinations.

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

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

    5. Click Save.

    Viewing Audit Logs

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

    To view audit logs

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

    2. Select Audit logs.

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

      • Last 2 days

      • Last 7 days

      • Last 30 days

      • Last 60 days

      • Last 90 days

      • Custom

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

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

    Filtering Audit Log Results

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

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

    To filter audit logs

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

    2. Provide the following:

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

      • Operator - Conditional operator applied for the filters.

      • Value - Search keywords for the given filters.

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

    Downloading Audit Logs

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

    To download audit logs

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

    2. Select Audit logs.

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

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

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

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

      API Gateway audit log are listed below.

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

    External Accounts

    API Gateway user interface 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.

    Overview

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

    API Gateway uses service registries in the following ways:

    Service Registries supported by API Gateway

    API Gateway currently supports the following service registries:

    Adding a Service Registry

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

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

    To add and configure a service registry

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

    2. Click External accounts.

    3. Click Add service registry.

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

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

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

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

      The precedence of the Connection Timeout configuration is as follows:

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

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

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

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

      The precedence of the Read Timeout configuration is as follows:

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

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

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

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

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

      The basic authentication user name.

      Password

      The basic authentication password.

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

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

      Value

      A value for the given HTTP header key.

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

    Removing a Service Registry

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

    To remove a service registry

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

    2. Click Service Registries.

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

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

    Configuring Integration Server Instance for API Implementation

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

    To configure an Integration Server details

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

    2. Click External accounts.

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

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

    5. Provide the following details:

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

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

    7. Click Add. The server details are saved.

    Destination Configuration

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

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

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

    Configuring Events for API Gateway Destination

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

    To configure events for API Gateway destination

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

    2. Select Destinations.

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

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

      The available event types are:

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

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

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

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

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

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

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

      • API management

      • Application management

      • Team management

      • Group management

      • Package management

      • Promotion management

      • Approval management

      • Alias management

      • Analytics management

      • Policy management

      • Plan management

      • User management

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

    8. Click Save.

    Configuring API Portal Destination

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

    To configure API Portal destination

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

    2. Select Destinations.

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

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

      Field Description
      Name Name of the portal being configured.
      Version Version of the portal being configured.
    5. Provide the following information in the Portal configuration section for Gateway to send data to API Portal:

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

      By default, default tenant is considered if the tenant information is not provided.
      Username Username credential to access API Portal instance.
      Password Password credential to access API Portal instance.
    6. Provide the following information in the Gateway configuration section for API 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 API Portal instance.
    7. Click Test to ensure the connection with the API Portal details is established. This connection with the given server is tested and a success message appears.

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

    Configuring Events for API Portal Destination

    Pre-requisites:

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

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

    To configure events for API Portal destination

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

    2. Select Destinations.

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

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

      The available event types are:

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

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

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

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

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

    7. Click Save.

    Post-requisites:

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

    Configuring CentraSite Destination

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

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

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

    To configure CentraSite destination

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

    2. Select Destinations.

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

      The Communication section displays the following information:

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

      The SNMP section displays the following information:

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

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

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

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

    Configuring Events for CentraSite Destination

    Pre-requisites:

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

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

    To configure events for API Gateway destination

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

    2. Select Destinations.

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

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

      The available event types are:

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

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

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

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

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

    7. Click Save.

    Post-requisites:

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

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

    Configuring Elasticsearch Destination

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

    To configure Elasticsearch destination

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

    2. Select Destinations.

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

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

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

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

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

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

    Configuring Events for Elasticsearch Destination

    Pre-requisites:

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

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

    To configure Elasticsearch destination

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

    2. Select Destinations.

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

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

      The available event types are:

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

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

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

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

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

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

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

      • API management

      • Application management

      • Team management

      • Group management

      • Package management

      • Promotion management

      • Approval management

      • Alias management

      • Analytics management

      • Policy management

      • Plan management

      • User management

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

    8. Click Save.

    Post-requisites:

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

    Configuring Email Templates

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

    To configure Email Templates

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

    2. Select Destinations.

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

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

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

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

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

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

      The transaction event parameters from the API Gateway Metrics and
      Event Notification engine are:
      Runtime_Policy: @policy_action_name
      API: @api_name
      Version : @version
      Operation or Resource_Name: @operation_resource_name
      Native endpoint: @native_endpoint
      Event generation time: @description
      Consumer_Name: @consumer_name
      Consumer_ID: @consumer_ID
      Status: @status
      Coorelation_ID:@correlationID
      Error origin: @errorOrigin
      

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

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

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

      Note: You can use the existing parameters multiple times or delete the parameter if the parameter is not required from the available parameters in the template. However, you cannot add new parameters.

      The monitor event parameters from the API Gateway Metrics and
      Event Notification engine are:
      Runtime_Policy: @policy_action_name
      API: @api_name
      Version : @version
      Operation or Resource_Name: @operation_resource_name
      Native endpoint: @native_endpoint
      Action type: @actionType
      Attribute: @attribute
      Consumer_Name: @consumer_name
      Consumer_ID: @consumer_ID
      Alert Message: @alertMessage
      

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

    5. Click Save.