Using the Externalized Configuration Files

Elasticsearch Configuration

Note: Install and run Elasticsearch, version 8.2.3, if you are configuring an external Elasticsearch.

The Elasticsearch configuration and details section contains all the necessary properties for an Elasticsearch HTTP client using which webMethods API Gateway connects to either an externally running Elasticsearch server or to the Elasticsearch-powered API Data Store in webMethods API Gateway. The key configurations are as follows:

tenantId. The webMethods API Gateway tenant id, using which the Elasticsearch indices are created for that tenant.
hosts. A comma separated list of Elasticsearch instances. Example: host1:9200,host2:9240.
autostart. Optional. If the value is not provided, by default it would be false. webMethods API Gateway would connect to the given external Elasticsearch hosts. If the value is set to true, webMethods API Gateway automatically starts the API Data Store. In this case, the hosts should point to API Data Store host and port. The default host for the API Data Store is localhost:9240.
http. The basic authentication credentials and HTTP-connection specific properties.
https. If the enabled property within https is set to true, webMethods API Gateway uses the other https properties to connect to the configured hosts.
sniff. These properties help in adding a new Elasticsearch node to the Elasticsearch cluster.
outboundproxy. Outbound proxy settings between webMethods API Gateway and Elasticsearch.
clientHttpResponseSize. Maximum Response payload size in MB.

A sample Elasticsearch configuration is as follows:

apigw:
  elasticsearch:
    tenantId: apigateway
    hosts: localhost:9200
    autostart: false
    http:
      username: elastic
      password: changeme
      keepAlive: true
      keepAliveMaxConnections: 10
      keepAliveMaxConnectionsPerRoute: 100
      connectionTimeout: 1000
      socketTimeout: 10000
      maxRetryTimeout: 100000
    https:
      enabled: false
      keystoreFilepath: C:/softwares/elasticsearch/config/keystore-new.jks
      truststoreFilepath: C:/softwares/elasticsearch/config/truststore-new.ks
      keystoreAlias: root-ca
      keystorePassword: 6572b9b06156a0ff778c
      truststorePassword: manage
      enforceHostnameVerification: false
    sniff:
      enable: false
      timeInterval: 1000
    outboundProxy:
      enabled: false
      alias: somealias
    clientHttpResponseSize: 1001231

Analytics Data Store Configuration

Note: Install and run Elasticsearch, version 8.2.3, if you are configuring an external Elasticsearch.

The analytics data store configuration supports setting the analytics data store to store analytics data separately from the core data. It also contains the required properties to establish a communication channel between webMethods API Gateway and analytics data store to exchange data. The key configurations are as follows:

tenantId. The webMethods API Gateway tenant id, using which the Elasticsearch indices are created for that tenant.
hosts. A comma separated list of Elasticsearch instances. Example: host1:9200, host2:9240.
http. The basic authentication credentials and HTTP-connection specific properties.
https. The HTTPS-connection specific properties. If the enabled property within https is set to true, webMethods API Gateway uses the other https properties to connect to the configured hosts.
sniff. These properties help in adding a new Elasticsearch node to the Elasticsearch cluster.
outboundproxy. Outbound proxy settings between webMethods API Gateway and Elasticsearch.
clientHttpResponseSize. Maximum response payload size in MB.

A sample analytics data store configuration is as follows:


---
apigw:
  analyticsDataStore:
    tenantId: default
    hosts: localhost:9241
    http:
      username: analyticsdatastore
      password: changeme
      keepAlive: true
      keepAliveMaxConnections: 60
      keepAliveMaxConnectionsPerRoute: 20
      connectionTimeout: 2000
      socketTimeout: 40000
      maxRetryTimeout: 200000
    https:
      enabled: false
      keystoreFilepath: C:/softwares/analyticsdatastore/config/demouser-keystore.jks
      truststoreFilepath: C:/softwares/analyticsdatastore/config/truststore.jks
      keystoreAlias: cn=demouser
      keystorePassword: 6572b9b06156a0ff778c
      truststorePassword: 2c0820e69e7dd5356576
      enforceHostnameVerification: false
    sniff:
      enable: false
      timeInterval: 70000
    outboundProxy:
      enabled: false
      alias: somealias
    clientHttpResponseSize: 200

Kibana Configuration

Note: Install Kibana, version 8.2.3, if you are configuring an external instance of Kibana.

The Kibana configuration supports setting the Kibana server URL, which can point to either the one that is run by webMethods API Gateway or any externally running server. It also contains the SSL certificate related settings that would be used to connect to the SSL protected Elasticsearch server. The key configurations are as follows:

dashboardInstance. The Kibana server URL in the format scheme://hostname:port. Example: http://vmabc:5601.
autostart. Optional. If the value is not provided, by default it would be false. webMethods API Gateway would connect to the given external Kibana server. If the value is set to true, webMethods API Gateway automatically starts the internal Kibana server. In this case, the hosts should point to internal Kibana server host and port. The default value is http://localhost:9405.
sslCA. A list of paths to the PEM file for the certificate authority for the Elasticsearch instance.
sslCert. The path to the PEM format certificate for SSL client authentication.
sslKey. The client certificate key used for client authentication. These files are used to verify the identity of Kibana to the Elasticsearch server when it is SSL protected.

A sample Kibana configuration is as follows:


apigw:
  kibana:
    dashboardInstance: http://localhost:9405
    autostart: true
    elasticsearch:
      sslCA: C:/softwares/elasticsearch/config/SAG-B1HPWT2.pem
      sslCert: C:/softwares/elasticsearch/config/SAG-B1HPWT2.crt
      sslKey: C:/softwares/elasticsearch/config/SAG-B1HPWT2.key

Filebeat Configuration

The Filebeat configuration supports configuring the SSL certificate related settings that are used to connect to the SSL protected Elasticsearch server. The key configurations are as follows:

sslCA. A list of paths to the PEM file for the certificate authority for the Elasticsearch instance.
sslCert. The path to the PEM format certificate for SSL client authentication.
sslKey. The client certificate key used for client authentication. These files are used to verify the identity of Kibana to Elasticsearch server when it is SSL protected.

A sample Filebeat configuration is as follows:


apigw:
  filebeat:
    output:
      elasticsearch:
        sslCA: C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.pem
        sslCert: C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.crt
        sslKey: C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.key

Cluster Configuration

This section describes the cluster configuration steps for both peer-to-peer clustering using Apache Ignite or Terracotta Server Array.

Peer-to-peer cluster configuration based on Apache Ignite technology

With peer-to-peer clustering the cluster members synchronize by using distributed caches. Therefore, each webMethods API Gateway server requires two ports. Hence, these ports have to be accessible for communication. If you have deployed the cluster on a traditional on-premise installation with real or virtual machines then the firewall must be open to the server ports.

In order to form a cluster, each cluster member requires information about possible other servers. If the cluster is deployed on a traditional on-premise installation, or as Docker containers, then you have to specify the names of the participating hosts. This is an initial member list. If you want to scale the cluster, you can include servers with host name that is not in the initial list. Such a server contacts any server in the initial list, and then negotiates joining the cluster.

If the cluster is deployed in a Kubernetes environment, the cluster specification requires the Kubernetes namespace and the name of the Kubernetes service that exposes the webMethods API Gateway deployment. New cluster members are then detected by checking the endpoints attached to the Kubernetes service.

In order to analyze the service endpoints you must start the webMethods API Gateway deployment with a service account with specific permissions. For details about the service account permissions, see API Gateway Clustering on Kubernetes.

The cluster configuration contains peer-to-peer cluster and the related Elasticsearch cluster settings.

Note: The cluster configuration for Elasticsearch clustering settings is only applicable to API Data Store.

The key configurations are as follows:

aware, name, sessTimeout, actionOnStartupError. These parameters have the same meaning as in Terracotta clustering. However, note that in this case they will not be applied to the server watt properties.
ignite.discoveryPort. The port that is used to discover the participating cluster members. Each cluster member opens this port in order to be discoverable. Each server tries to contact other servers through this port. The discoveryPort must be different from the communicationPort.
ignite.communicationPort. The port that is used to communicate between distributed caches. Each server opens this port to receive information and distribute distribute cache entries to other cluster members. The communicationPort must be different from the discoveryPort.
ignite.portRange. The number of ports to include in the range available to multiple cluster members on the same host. The default value of the portRange parameter is 0.
The portRange parameter applies to both the discoveryPort and the communicationPort. When you specify a non-zero portRange value, ensure that the resulting ranges for the discovery port and the communication port do not overlap.

Generally, each cluster member is deployed on its own host. However, for trial or demo purposes you might have multiple cluster members on the same host. In such a situation, each server requires its own discovery and communication port, and must know the other servers' ports. You can use the portRange parameter to configure this scenario. The portRange is a number that defines the size of a port range. For example, if you configure the port with port number 10100 and portRange as 5, the resulting port range that is available is 10100 to 10105. When a server starts, it picks an unused port from the range 10100 to 10105, and uses the port to communicate with the other servers. Another server on start up can use an unused port from the same port range to communicate with the other servers. This allows all servers to use the same cluster configuration.
ignite.hostnames. The list of initial host names participating in the cluster. The list is comma-separated.
ignite.k8sServiceName. The name of the service that exposes the webMethods API Gateway deployment, in case of a Kubernetes cluster.
ignite.k8sNamespace. The name of the Kubernetes namespace within which the webMethods API Gateway is deployed, in case of a Kubernetes cluster.

A sample cluster configuration for an on-premise or Docker deployment is as follows:

apigw:
  cluster:
    aware:       true
    name:        APIGatewayCluster
    sessTimeout: 60
    actionOnStartupError: standalone
    ignite:
      hostnames:         daeirnd33974,daeirnd33562,daeirnd33974
      discoveryPort:     10100
      communicationPort: 10400

A sample cluster configuration for Kubernetes cluster is as follows:

apigw:
  cluster:
    aware:       true
    name:        APIGatewayCluster
    sessTimeout: 60
    actionOnStartupError: standalone
    ignite:
      k8sServiceName:    api-gateway-service
      k8sNamespace:      api-gateway-namespace
      discoveryPort:     10100
      communicationPort: 10400

A sample cluster configuration for multiple servers on the same host is as follows:

apigw:
  cluster:
    aware:       true
    name:        APIGatewayCluster
    sessTimeout: 60
    actionOnStartupError: standalone
    ignite:
      hostnames:         localhost
      discoveryPort:     10100
      communicationPort: 10400
      portRange:         3

Cluster configuration using Terracotta Server Array

Note: Install and run the Terracotta server (a version that is compatible with API Gateway 10.11) for clustering webMethods API Gateway instances.

The cluster configuration contains the Terracotta cluster settings. The key configurations are as follows:

aware, name, tsaUrls, sessTimeout, actionOnStartupError. All are required Terracotta cluster settings in the server watt properties.
terracottaLicenseFileName. The Terracotta server license file name. The file should be present in the folder SAGInstallDir/common/conf. webMethods API Gateway uses this file to join the Terracotta cluster.

A sample Cluster configuration is as follows:


apigw:
  cluster:
    aware: true
    name: APIGatewayTSAcluster
    tsaUrls: VMYAI105BVT06:9510
    terracottaLicenseFileName: terracotta-license.key
    sessTimeout: 20
    actionOnStartupError: standalone

For terracottaLicenseFileName parameter a valid license file should be present in the SAGInstallDir/common/conf location, otherwise the parameter is ignored.

Note: When cluster settings are given in the configuration files, the webMethods API Gateway server, on startup, updates the internal settings with the values from the configuration files but the webMethods API Gateway node does not join the cluster. You must restart the server for the cluster settings to become effective and for the webMethods API Gateway node to join the cluster.

User Configuration

The user configuration supports configuring user and group information on the webMethods API Gateway server. By default, the local users created are assigned to the Everybody group. The key configurations are as follows:

firstName. First name of the user.
lastName. Last name of the user.
password. Password of the user.
emailAddresses. List of email addresses of the user.
active. Active status of the user.
language. Preferred language of the user.
groups. Names of the groups the user belongs to.

A sample user configuration is as follows:


---
apigw:
  users:
    tstk:
      firstName: "stark"
      lastName: "Koop"
      password: "oops"
      emailAddresses: [ tstk@sag.com, tstk@sag.co.uk ]
      active: true
      groups:
      - "group1"
      - "group2"
    fred:
      firstName: "Fred"
      lastName: "Barker"
      password: "oops"
      emailAddresses: [ fred@sag.com ]
      active: true
      groups: [group1,group2]
    bob:
      firstName: "Bob"
      lastName: "Tate"
      password: "oops"
      emailAddresses: [ bob@sag.com ]
      active: true

Master Password Configuration

In webMethods API Gateway, you would be using passwords while enforcing security related policies, while connecting to various destinations such as, API Portal, CentraSite, Email, and SNMP, while configuring the security-related aliases, configuring outbound proxy servers, and so on.

To protect these passwords API Gateway encrypts them. By default, it encrypts them using Password-Based Encryption (PBE) standard, also known as PKCS5. This encryption method requires the use of an encryption key or master password that you specify.

The master password configuration supports configuring of encryption key or master password on the webMethods API Gateway server. The key configurations are as follows:

expiry. Expiry interval for the master password.
oldPassword. Current password of the user.
newPassword. New password of the user.

A sample master password configuration is as follows:


---
apigw:
  masterpassword:
    expiry: "60"
    oldPassword: "old1"
    newPassword: "new1"

UI Configuration

The UI configuration supports configuring HTTP and HTTPS port on the webMethods API Gateway server.

The key HTTP and HTTPS configurations are as follows:

Parameters	Description
`maxHttpHeaderSize` This parameter is applicable to HTTP and HTTPS.	Specifies the maximum size of the request and response HTTP header, specified in bytes. If not specified, this attribute is set to 8192 (8 KB).
`connectionTimeout` This parameter is applicable to HTTP.	This property specifies the time, in milliseconds, after which the connection times out.
`server` This parameter is applicable to HTTP and HTTPS.	This property overrides the server header for the HTTP response.
`maxSpareThreads` This parameter is applicable to HTTP and HTTPS.	Specifies the maximum number of request processing threads the connector creates, which determines the maximum number of simultaneous requests that webMethods API Gateway server can handle.
`disableUploadTimeout` This parameter is applicable to HTTP and HTTPS.	This flag allows the servlet container to use a different, usually longer connection timeout during data upload.
`minSpareThreads` This parameter is applicable to HTTP and HTTPS.	Specifies the minimum number of threads always kept running. This includes both active and idle threads.
`redirectPort` This parameter is applicable to HTTP and HTTPS.	When a SSL port is required by the client, the request is redirected to this port number.
`acceptCount` This parameter is applicable to HTTP and HTTPS.	Specifies the maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full is refused. The default value is 100.
`port` This parameter is applicable to HTTP and HTTPS.	Specifies the TCP port number on which this connector creates a server socket and awaits incoming connections.
`enableLookups` This parameter is applicable to HTTP and HTTPS.	Set to `true` if you want calls to `request.getRemoteHost()` to perform DNS lookup in order to return the actual host name of the remote client. Set to `false` to skip the DNS lookup and return the IP address in string form instead (thereby improving performance).
`enabled` This parameter is applicable to HTTP and HTTPS.	Enable or disable webMethods API Gateway web-app port.
`alias` This parameter is applicable to HTTP and HTTPS.	Identifies a proxy server and a port on the server through which you want to route requests.
`sslProtocol` This parameter is applicable to HTTPS.	Specifies the SSL protocols to use. A single value may enable multiple protocols. For more information, see JVM documentation. If not specified, the default is `TLS`.
`sslEnabled` This parameter is applicable to HTTPS.	Use this attribute to enable SSL traffic on a connector. The default value is `false`. To turn on SSL handshake or encryption or decryption on a connector set this value to `true`.When turning this value to `true`, set the scheme and the secure attributes to pass the correct `request.getScheme()` and `request.isSecure()` values to the servlets.
`keystoreType` This parameter is applicable to HTTPS.	The keystore file type to use for the server certificate. If not specified, the default value is `JKS`.
`keystoreFile` This parameter is applicable to HTTPS.	The pathname of the keystore file where the server certificate is stored. By default, the pathname is the file `.keystore` in the operating system home directory of the user that is running Tomcat. If the `keystoreType` doesn't need a file use " " (empty string) for this parameter.
`keystorePass` This parameter is applicable to HTTPS.	The password used to access the specified keystore file.
`scheme` This parameter is applicable to HTTPS.	Set this attribute to the name of the protocol you wish to have returned by calls to `request.getScheme()`.
`secure` This parameter is applicable to HTTPS.	Set this attribute to `true` if you wish to have calls to `request.isSecure()` to return `true` for requests received by this connector.

For more information on HTTP and HTTPS port configuration, see Apache Tomcat documentation.

A sample UI configuration is as follows:


---
apigw:
  ui:
    http:
      maxHttpHeaderSize: "8192"
      connectionTimeout: "20001"
      server: "SoftwareAG-Runtime"
      maxSpareThreads: "78"
      disableUploadTimeout: "true"
      minSpareThreads: "23"
      redirectPort: "19073"
      acceptCount: "102"
      port: "11072"
      enableLookups: "false"
      enabled: "true"
      alias: "defaultHttp"
    https:
      maxHttpHeaderSize: "8192"
      server: "SoftwareAG-Runtime"
      maxSpareThreads: "72"
      disableUploadTimeout: "true"
      minSpareThreads: "22"
      acceptCount: "104"
      port: "11075"
      enableLookups: "false"
      enabled: "true"
      alias: "defaultHttps"
      sslProtocol: "tls"
      sslEnabled: "true"
      keystoreType: "xxy"
      keystoreFile: "Test2"
      keystorePass: "geheim"
      scheme: "xScheme"
      secure: "true"

Aliases Configuration

An alias in webMethods API Gateway holds environment-specific property values to use in policy routing configuration. webMethods API Gateway aliases can be defined through external configuration. The alias configuration supports configuring aliases on the webMethods API Gateway server.

The key configurations are as follows:

name. A unique name for the alias.
description. A description of the alias.
type. Type of the alias. The following aliases configuration are supported:
- simple
- endpoint
- httpTransportSecurityAlias
- soapMessageSecurityAlias
- samlIssuerAlias
- authServerAlias
- webmethodsAlias
- transformationAlias
- serviceRegistryAlias
- clientMetadataMapping
- awsConfigurationAlias
- isConfigurationAlias
owner. Owner of the alias.

Sample configuration of the supported aliases are as follows:

simple alias configuration:


apigw:
  aliases:
    simpleAlias1:
        type: "simple"
        value: "vmspar02w"

endpoint alias configuration:


apigw:
  aliases:
      endpointAlias1:
          type: "endpoint"
          endPointURI: "http://vmspar02w:9998"
          connectionTimeout: 30
          readTimeout: 30
          suspendDurationOnFailure: 0
          optimizationTechnique: "None"
          passSecurityHeaders: false
          keystoreAlias: "ksAlias"

httpTransportSecurityAlias configuration:


apigw:
  aliases:
    httpSec1:
      type: "httpTransportSecurityAlias"
      authType: "HTTP_BASIC"
      authMode: "INCOMING_HTTP_BASIC_AUTH"
      httpAuthCredentials:
        userName: "Bob"
        password: "R3Vlc3NJdA=="
        domain: "EUR"

isConfigurationAlias configuration:


apigw:
  aliases:
    myIsAlias:
      type: "isConfigurationAlias"
      url: "http://localhost:5555"
      username: "Administrator"
      password: "bXlwYXNz"
      keystoreAlias: "DEFAULT_IS_KEYSTORE"
      keyAlias: "ssos"
      packageName: "WmAPIGateway"
      folderName: "test2"
      importSwaggerBasedOnTags: "false"
      enableMTOM: "true"
      enforceWSICompliance: "true"
      validateSchemaWithXerces: "true"
      contentModelComplianceForWSDL: "Lax"

authServerAlias configuration:


apigw:
  aliases: 
   testAuthServer:
      type: "authServerAlias"
      description: "Test Auth server"
      tokenGeneratorConfig:
        expiry: "0"
        accessTokenExpInterval: "3600"
        authCodeExpInterval: "600"
        algorithm: "null"
      supportedGrantTypes: ["authorization_code","client_credentials","implicit"]
      authServerType: "EXTERNAL"
      localIntrospectionConfig: 
        issuer: "testIssuer"
        trustStoreAlias: "DEFAULT_IS_TRUSTSTORE"
        certificateAlias: "sso"
        jwksuri: "http://mytest.com"
        description: "Issuer description"
      remoteIntrospectionConfig:
        introspectionEndpoint: "http://myendpoint"
        clientId: "1234"
        clientSecret: "c2VjcmV0"
        user: "Administrator"
      metadata:
        authorizeURL: "http://softwareag.com/authorize"
        accessTokenURL: "http://softwareag.com/accessToken"
        refreshTokenURL: "http://softwareag.com/authorize/refresh"
      sslConfig:
        keyStoreAlias: "DEFAULT_IS_KEYSTORE"
        keyAlias: "ssos"
        trustStoreAlias: "DEFAULT_IS_TRUSTSTORE"
      discoveryURL: "http://softwareag.com/.well-known/openid-configuration"

The properties of the supported aliases are as follows:

Type	Parameters
`simple`	`value.` Value of the simple alias.
`endpoint`	`endPointURI.` The default URI or components of the URI such as service name. `connectionTimeout.` Time interval (in seconds) after which a connection attempt times out. `readTimeout.` Time interval (in seconds) after which a socket read attempt times out. `suspendDurationOnFailure.` Time to suspend the request upon a failure. `optimizationTechnique.` Type of optimization technique used for SOAP messages. `passSecurityHeaders.` Boolean value whether to pass security headers or not. `keystoreAlias.` Keystore alias name that is used for the signing or encryption. `keyAlias.` Key alias in the particular keyStore . `truststoreAlias.` Truststore alias name to validate the server certificate.
`httpTransportSecurityAlias`	`authType.` The type of authentication you want to use while communicating with the native API. The authentication types supported are: `HTTP_BASIC`, `NTLM`, `OAUTH2`, `KERBEROS`, `JWT`, `ALIAS`, and `REMOVE_INCOMING_HTTP_HEADERS`. `authMode.` Authentication mode to use while communicating with the native API. The authentication modes supported are: `NEW`, `INCOMING_HTTP_BASIC_AUTH`, `INCOMING_WSS_USER`, `INCOMING_X509`, `DELEGATE_INCOMING`, `INCOMING_OAUTH_TOKEN`, `INCOMING_JWT`, `TRANSPARENT`, and `INCOMING_KERBEROS`. `httpAuthCredentials.` Credentials to use for HTTP authentication. The authentication credentials supported are: `userName.` Specify a username to access the native API. `password.` Specify a password to access the native API. `domain.` Specify a domain to access the native API. `kerberosCredentials.` Credentials to use for Kerberos authentication. The authentication credentials supported are: `clientPrincipal.` A unique identity to which Kerberos can assign tickets. `clientPassword.` Password for the client principal. `servicePrincipal.` A unique identifier of a service instance. `servicePrincipalNameForm.` The format in which you want to specify the principal name of the service that is registered with the principal database. `servicePrincipalNameForm` value can be `hostbased` or `username`. `requestDelegateToken.` Boolean value whether the token needs to be delegated or not. `oauth2Token.` OAuth2 token to use for authentication.
`transformationAlias`	`fileName.` Name of the file. `content.` Content of the file.
`serviceRegistryAlias`	`endpointURI.` Endpoint to use to communicate with the service registry. `heartBeatInterval.` webMethods API Gateway pings the service registry on the configured interval for every API. `username.` Username to use in the basic authentication when communicating with the service registry. `password.` Password to use in the basic authentication when communicating with the service registry. `keystoreAlias.` A keystore is a repository of private key. This keystore contains the private key to use for the SSL communication with the service registry. `keyAlias.` The key alias is the private key to use for signing when using SSL communication with the service registry. `trustStoreAlias.` A truststore is a repository of public keys. This truststore contains the public key of the service registry to use for the SSL communication with the service registry. `customHeaders.` Custom headers to send while communicating with the service registry. `discoveryInfo.` Contains information like resource path and HTTP method to use while discovering a service in service registry. `registrationInfo.` Contains information like resource path and HTTP method to use while registering a service in service registry. `deRegistrationInfo.` Contains information like resource path and HTTP method to use while de-registering a service from service registry. `serviceRegistryType.` Contains the information about the type of service registry. `connectionTimeout.` The time interval (in seconds) after which a connection attempt times out while communicating with service registry. `readTimeout.` The time interval (in seconds) after which a socket read attempt times out while communicating with service registry.
`awsConfigurationAlias`	`region.` The configured AWS instance region detail. `accessKey.` The access key ID for the AWS instance. This is used to sign the requests. `secretKey.` The secret access key for the AWS instance. This is used to sign the requests.
`samlIssuerAlias`	`issuerCommunicationMode.` Mode of communication to the STS. `issuerPolicy.` The webMethods Integration Server service name. `issuerAuthScheme.` The authentication type to use for communicating to STS. `issuerAuthMode.` Mode of communication to STS. `wssCredentials.` Credentials for the WSS Username token. `kerberosCredentials.` Credentials for the Kerberos token. `endpoint.` The endpoint URI of the STS. `samlVersion.` SAML version used for authentication. `wsTrustVersion.` WS-Trust version that webMethods API Gateway must use to send the RST to the SAML issuer. `appliesTo.` Specify the scope for which this security token is required. `extendedParameters.` 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 tokens. `signAndEncryptConfig.` Private and public keys to use signature and encryption.
`webmethodsAlias`	`serviceName.` The webMethods Integration Server service name. `runAsUser.` The user name you want webMethods API Gateway to use to invoke the IS service. `complyToISSpec.` Set to true, if you want the input and the output parameters to comply to the IS Spec specified.
`clientMetadataMapping`	`providerName.` Name of the provider. `implNames.` Map of specification names to the implementation names of the service provider. `extendedValuesV2.` List of headers that needs to be sent along with the client management request. `generateCredentials.` Specifies whether webMethods API Gateway should generate `clientId` and `client secret`. `supportedApplicationTypes.` List of `application_type` values supported by the authorization server provider.
`soapMessageSecurityAlias`	`authType.` Type of authentication. `authMode.` Mode of authentication `wssCredentials.` Credentials required for the WSS Username token. `kerberosCredentials.` Credentials for the Kerberos token. `samlIssuerConfig.` SAML issuer configuration name. `signAndEncryptConfig.` Private and public keys to use for signature and encryption.
`isConfigurationAlias`	`url.` URL of the Integration Server. `username.` User credentials required to access the Integration Server instance. `password.` Password required to access the Integration Server instance. `keystoreAlias.` 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. `keyAlias.` The alias for a specific key in the specified keystore. `packageName.` Default package name where the alias is published. `folderName.` Default folder name where the alias is published.
`authServerAlias`	`description.` Description of the auth server. `tokenGeneratorConfig.` Specifies the token information that would be added as a bearer token in the HTTP request for client authentication. `supportedGrantTypes.` Specifies the list of grant types that are supported by API Gateway. The grant types supported are: `authorization_code`, `client_credentials`, and `implicit`. `localIntrospectionConfig.` Specifies the introspection endpoint to check that access tokens used in client requests are currently active and are valid to invoke the protected resources. `sslConfig.` Specifies the SSL configuration information.

Consolidating Externalized Configuration Files

You can consolidate the configurations of different inter-components and cluster in a single configuration file.

A sample consolidated configuration file is as follows:


apigw:  
	elasticsearch:    
			tenantId: "apigateway"    
			hosts: "localhost:9240"    
			autostart: "true"    
			http:      
					username: ""      
					password: "@secure.elasticsearch.http.password"      
					keepAlive: "true"      
					keepAliveMaxConnections: 10      
					keepAliveMaxConnectionsPerRoute: 100      
					connectionTimeout: 1000      
					socketTimeout: 10000      
					maxRetryTimeout: 100000    
			https:      
					enabled: "false"      
					truststoreFilepath: "C:/softwares/elasticsearch-version/config/truststore-new.ks"      
					keystoreAlias: "root-ca"      
					truststorePassword: "@secure.elasticsearch.http.truststore.password"      
					enforceHostnameVerification: "false"    
			sniff:      
					enable: "false"      
					timeInterval: 1000    
			outboundProxy:      
					enabled: "false"      
					alias: "esoutboundproxyalias"    
			clientHttpResponseSize: 1001231  
	kibana:    
			dashboardInstance: "http://localhost:9405"    
			autostart: "true"    
		elasticsearch:      
			sslCA: "C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.pem"  
		filebeat:    
			output:      
				elasticsearch:        
					sslCA: "C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.pem"  
analyticsDataStore:
    tenantId: default
    hosts: "localhost:9241"
    http:
      username: analyticsdatastore
      password: changeme
      keepAlive: true
      keepAliveMaxConnections: 60
      keepAliveMaxConnectionsPerRoute: 20
      connectionTimeout: 2000
      socketTimeout: 40000
      maxRetryTimeout: 200000
    https:
      enabled: false
      keystoreFilepath: C:/softwares/analyticsdatastore/config/demouser-keystore.jks
      truststoreFilepath: C:/softwares/analyticsdatastore/config/truststore.jks
      keystoreAlias: cn=demouser
      keystorePassword: 6572b9b06156a0ff778c
      truststorePassword: 2c0820e69e7dd5356576
      enforceHostnameVerification: false
    sniff:
      enable: false
      timeInterval: 70000
    outboundProxy:
      enabled: false
      alias: somealias
    clientHttpResponseSize: 200
cluster:    
		aware: "true"    
		name: "APIGatewayTSAcluster"    
		tsaUrls: "VMYAI105BVT06:9510"    
		terracottaLicenseFileName: "terracotta-license.key"    
		sessTimeout: "20"    
		actionOnStartupError: "standalone"    
users:
    tstk:
      firstName: "stark"
      lastName: "Koop"
      password: "oops"
      emailAddresses: [ tstk@sag.com, tstk@sag.co.uk ]
      active: true
      groups:
      - "group1"
      - "group2"
    fred:
      firstName: "Fred"
      lastName: "Barker"
      password: "oops"
      emailAddresses: [ fred@sag.com ]
      active: true
      groups: [group1,group2]
    bob:
      firstName: "Bob"
      lastName: "Tate"
      password: "oops"
      emailAddresses: [ bob@sag.com ]
      active: true
masterpassword:
    expiry: "60"
    oldPassword: "old1"
    newPassword: "new1"
ui:
    http:
      maxHttpHeaderSize: "8192"
      connectionTimeout: "20001"
      server: "SoftwareAG-Runtime"
      maxSpareThreads: "78"
      disableUploadTimeout: "true"
      minSpareThreads: "23"
      redirectPort: "19073"
      acceptCount: "102"
      port: "11072"
      enableLookups: "false"
      enabled: "true"
      alias: "defaultHttp"
    https:
      maxHttpHeaderSize: "8192"
      server: "SoftwareAG-Runtime"
      maxSpareThreads: "72"
      disableUploadTimeout: "true"
      minSpareThreads: "22"
      acceptCount: "104"
      port: "11075"
      enableLookups: "false"
      enabled: "true"
      alias: "defaultHttps"
      sslProtocol: "tls"
      sslEnabled: "true"
      keystoreType: "xxy"
      keystoreFile: "Test2"
      keystorePass: "geheim"
      scheme: "xScheme"
      secure: "true"
aliases:
    simpleAlias1:
        type: "simple"
        value: "vmspar02w"
    endpointAlias1:
          type: "endpoint"
          endPointURI: "http://vmspar02w:9998"
          connectionTimeout: 30
          readTimeout: 30
          suspendDurationOnFailure: 0
          optimizationTechnique: "None"
          passSecurityHeaders: false
          keystoreAlias: "ksAlias"
    httpSec1:
          type: "httpTransportSecurityAlias"
          authType: "HTTP_BASIC"
          authMode: "INCOMING_HTTP_BASIC_AUTH"
          httpAuthCredentials:
             userName: "Bob" 
             password: "R3Vlc3NJdA==" 
             domain: "EUR"
   myIsAlias:
          type: "isConfigurationAlias"
          url: "http://localhost:5555"
          username: "Administrator"
          password: "bXlwYXNz"
          keystoreAlias: "DEFAULT_IS_KEYSTORE"
          keyAlias: "ssos"
          packageName: "WmAPIGateway"
          folderName: "test2"
          importSwaggerBasedOnTags: "false"
          enableMTOM: "true"
          enforceWSICompliance: "true"
          validateSchemaWithXerces: "true"
          contentModelComplianceForWSDL: "Lax"
  testAuthServer:
          type: "authServerAlias"
          description: "Test Auth server"
          tokenGeneratorConfig:
            expiry: "0"
            accessTokenExpInterval: "3600"
            authCodeExpInterval: "600"
            algorithm: "null"
          supportedGrantTypes: ["authorization_code","client_credentials","implicit"]
          authServerType: "EXTERNAL"
          localIntrospectionConfig: 
            issuer: "testIssuer"
            trustStoreAlias: "DEFAULT_IS_TRUSTSTORE"
            certificateAlias: "sso"
            jwksuri: "http://mytest.com"
            description: "Issuer description"
         remoteIntrospectionConfig:
            introspectionEndpoint: "http://myendpoint"
            clientId: "1234"
            clientSecret: "c2VjcmV0"
            user: "Administrator"
         metadata:
            authorizeURL: "http://softwareag.com/authorize"
            accessTokenURL: "http://softwareag.com/accessToken"
            refreshTokenURL: "http://softwareag.com/authorize/refresh"
        sslConfig:
            keyStoreAlias: "DEFAULT_IS_KEYSTORE"
            keyAlias: "ssos"
            trustStoreAlias: "DEFAULT_IS_TRUSTSTORE"

Similarly, you can consolidate separate property files into a single file as shown in the following sample.


apigw.elasticsearch.tenantId=apigateway
apigw.elasticsearch.autostart=true
apigw.elasticsearch.hosts=localhost:9240
apigw.elasticsearch.clientHttpResponseSize=1001231
apigw.elasticsearch.http.keepAlive=true
.
.
.
apigw.kibana.dashboardInstance=http://localhost:9405
apigw.kibana.elasticsearch.sslCert=/path/to/your/client.crt
apigw.kibana.elasticsearch.sslKey=/path/to/your/client.key
apigw.kibana.elasticsearch.sslCA=C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.pem
.
.
.
.
apigw.filebeat.output.elasticsearch.sslCert=/path/to/your/client.crt
apigw.filebeat.output.elasticsearch.sslKey=/path/to/your/client.key
apigw.filebeat.output.elasticsearch.sslCA=C:/softwares/elasticsearch-version/config/SAG-B1HPWT2.pem
.
.
.
apigw.cluster.tsaUrls=daeirnd33974:9510
apigw.cluster.actionOnStartupError=standalone
apigw.cluster.name=APIGatewayTSAcluster
apigw.cluster.sessTimeout=20
apigw.cluster.terracottaLicenseFileName=terracotta-license.key

Master configuration YAML file and its usage

The master configuration file, config-sources.yml, contains the paths, metadata, and properties for the other configuration files. The master configuration file and the other configuration files should be present in the folder SAGInstallDir\IntegrationServer\instances\instance_name\packages\WmAPIGateway\resources\configuration. The master configuration file can contain references to both YAML and Properties file types.

The master configuration file is read by webMethods API Gateway on startup. Using this file webMethods API Gateway reads the different configurations provided in the folder. If any entry has an invalid file name or path it is ignored but the error is logged into the webMethods API Gateway logs.

A sample master configuration file is as follows:

######################## Master configuration ############################

# This is the master configuration file which contains the configuration 
# source definitions.
#

#=======================  Sources configuration ==========================

sources:

#--------------------- YAML file configuration source --------------------

- type: YAML
  allowEdit: true
  properties:
    location: allExternal-settings.yml

#------------------- Properties file configuration source ----------------

#- type: PROPERTIES
# allowEdit: true
# properties:
# location: system-settings.properties
#

#==================================  END =================================

The table lists and explains the properties of a configuration file source entry.

Property	Detail
`type`	Indicates the type of the configuration source. The applicable types are YAML and PROPERTIES. `YAML`. A YAML configuration file. `PROPERTIES`. A properties configuration file.
`allowEdit`	Indicates whether this file can be updated from webMethods API Gateway and is useful for hiding passwords. Valid values are `true` and `false`. If the value is set to `true`, it hides the clear text passwords. If the value is set to `false`, it displays the clear text passwords.
`properties`	Properties that enable webMethods API Gateway to connect to the defined configuration source. For the 10.5 release only the `location` property is supported. `location`. An absolute or relative path to a component-specific configuration file. In case of relative path, the file would be located relative to the system-defined location `SAGInstallDir`\IntegrationServer\instances\instance_name\packages\WmAPIGateway\resources\configuration.

Note: The master configuration filename config-sources.yml is system-defined. A file with a different name is not treated as the master configuration file.

Hiding Clear Text Passwords in Configuration Files

To prevent unauthorized users from reading the credentials in the configuration files and other potential threats, the Administrator can enable hiding of such secrets by setting the allowEdit flag to true in the master configuration file. When allowEdit is set to true the secret values in the configuration files are stored in the Password manager and the plain text values in the files are replaced with the Password manager keys on API Gateway startup. After this, a user can see only the password keys in the files. On startup, API Gateway would retrieve the passwords for those settings from the Password manager using those keys and hence it is advised not to alter any of the password manager key values in the file. The passwords can be modified at any time and the same are replaced with the Password manager keys in the next API Gateway startup.

This table provides the list of the settings and their respective Password manager keys.

Setting	Password manager key replacement
`apigw: elasticsearch: http: username: elastic`	@secure.elasticsearch.http.password
`apigw: elasticsearch: https: keystorePassword: 6572b9b06156a0ff778c`	@secure.elasticsearch.http.keystore.password
`apigw: elasticsearch: https: truststorePassword: 6572b9b06156a0ff778c`	@secure.elasticsearch.http.truststore.password

Properties File Support for Externalized Configurations

In addition to YAML files, configurations can be saved in Properties files as well. The property names are the same as those in the YAML configuration files. The property names in Properties files are delimited by a "." for forming the property name. For example. the tenantId property under apigw > elasticsearch in YAML, can be specified as apigw.elasticsearch.tenantId in the properties file.

A sample Properties file is as follows:

apigw.elasticsearch.tenantId=default
apigw.elasticsearch.autostart=false
apigw.elasticsearch.hosts=vmabc\:9240
apigw.elasticsearch.http.password=admin123
apigw.elasticsearch.http.username=admin
apigw.kibana.dashboardInstance=http://localhost:9405
apigw.kibana.elasticsearch.sslCert=/path/to/your/client.crt

Environment Variables Support for Externalized configurations

All the supported externalized configurations can be defined through environment variables. The environment variable names are the same as the property names. Instead of the . delimiter the _ delimiter is used.

The main purpose of the environment variables is to inject a configuration into an webMethods API Gateway container during startup.

A sample externalized configuration with environment variable is as follows:


apigw_elasticsearch_tenantId=default
apigw_elasticsearch_autostart=false
apigw_elasticsearch_hosts=vmabc\:9240
apigw_elasticsearch_http.password=admin123
apigw_elasticsearch_http_username=admin
apigw_kibana_dashboardInstance=http://localhost:9405
apigw_kibana_elasticsearch_sslCert=/path/to/your/client.crt

Configuring Multiple Configuration Files and Its Effects

The master configuration file can have many entries (0 to N) for defining multiple configuration files as configuration sources. When such a file is used to start API Gateway, the configuration values from all the files would be merged into a single effective configuration. If the same configuration value is present in two files, then the value in the file which has a higher preference is given priority. The order of preference is in the reverse order in which they are defined in the master configuration file, that is, the configuration values that are defined in the last configuration file entry would have the highest preference. A sample use case is explained below.

Assume file1.yml has the following configurations.

apigw:
  elasticsearch:
    tenantId: default

And, file2.properties has the following configurations.

apigw.elasticsearch.tenantId=apigateway

And, file3.yml has the following configurations.

apigw:
  elasticsearch:
    http:
      username: admin
      password: admin123
  kibana:
    dashboardInstance: http://localhost:5601

Then the combined configuration that becomes effective is as follows.

Effective config.yml configuration:

apigw:
  elasticsearch:
    tenantId: apigateway
    http:
      username: admin
      password: admin123
  kibana:
    dashboardInstance: http://localhost:5601

Limitation

If you have defined cluster configuration in the externalized configuration file, on startup the webMethods API Gateway server updates the internal settings with the values from the externalized configuration files but the node in the cluster will not be updated. webMethods API Gateway server restart is required for the cluster settings to become effective and to join the cluster.