Using the Externalized Configuration Files
The API Gateway administrator provides configuration settings in one or more external configuration files and creates the master configuration file listing the external configuration files. On startup, API Gateway reads config-sources.yml file and loads all the external configuration source files that it references. The settings in the externalized configuration files override the respective internal configuration settings (such as uiconfiguration.properties, server.cnf). Once the API Gateway configuration space is updated, the rest of the API Gateway package gets loaded with the updated configuration settings.
Note:
For settings that are not given in the externalized configuration files, API Gateway use the settings given in the internal configuration files.
The below sample externalized configuration file template contains the configuration settings that the API Gateway administrator wants to externalize. The given external configuration settings overwrite the respective internal configuration settings. For the configuration settings that are not specified in the externalized configuration file, the settings given in the respective internal configuration files take precedence.
apigw:
elasticsearch:
.....
kibana:
.....
filebeat:
......
cluster:
......
users:
......
masterpassword:
......
ui:
......
alias:
......
uiConfig:
......
Elasticsearch Configuration
Note:
Install and run Elasticsearch, version 7.7.1, if you are configuring an external instance of Elasticsearch.
The Elasticsearch configuration and details section contains all the necessary properties for an Elasticsearch HTTP client using which API Gateway connects to either an externally running Elasticsearch server or to the Elasticsearch-powered API Gateway data store in API Gateway. The key configurations are as follows:
tenantId. The
API Gateway tenant id, using which the Elasticsearch indices are created for that tenant.
hosts. A comma separated list of external Elasticsearch instances. Example: host1:9200,host2:9240.
autostart.
Optional. If the value is not provided, by default it would be
false.
API Gateway would connect to the given external Elasticsearch hosts. If the value is set to
true,
API Gateway automatically starts the
API Gateway data store. In this case, the hosts should point to
API Gateway data store host and port. The default host for the
API Gateway 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,
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
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
Kibana Configuration
Note:
Install Kibana, version 7.7.1, if 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 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.
API Gateway would connect to the given external Kibana server. If the value is set to
true,
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
Note:
Install and run Terracotta server (a version that is compatible with API Gateway 10.7) for clustering API Gateway instances.
The cluster configuration contains the Terracotta clustering settings. The key configurations are as follows:
aware,
name,
tsaUrls,
sessTimeout,
actionOnStartupError. All are Terracotta cluster settings that are set in the server watt properties.
terracottaLicenseFileName. The Terracotta server license file name. The file should be present in the folder
SAGInstallDir/common/conf.
API Gateway would use this file for joining 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 property a valid license file should be present in the SAGInstallDir/common/conf location, otherwise the property is ignored.
Note:
When cluster settings are given in the configuration files, the API Gateway server, on startup, would update the internal settings with the values from the configuration files but the node does not join the cluster. You have to restart the server for the cluster settings to become effective and for the node to join the cluster.
API Gateway UI Configuration
The API Gateway UI configuration supports configuring the login page of API Gateway when the SSO configuration is enabled. The key configurations are as follows:
apigwAuthPriority. Displays the login page based on the value.
If the configuration is set as
apigwAuthPriority:form, then API Gateway login page appears displaying the
Login with SSO option option link.
If the configuration is set as
apigwAuthPriority:"saml", then API Gateway redirects you to SSO login page.
A sample API Gateway UI configuration is as follows:
apigw:
uiConfig:
apigwAuthPriority: form
User Configuration
The user configuration supports configuring user and group information on the 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 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 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 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 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 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 API Gateway holds environment-specific property values to use in policy routing configuration. API Gateway aliases can be defined through external configuration. The alias configuration supports configuring aliases on the 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"
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. 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 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 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 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"
cluster:
aware: "true"
name: "APIGatewayTSAcluster"
tsaUrls: "VMYAI105BVT06:9510"
terracottaLicenseFileName: "terracotta-license.key"
sessTimeout: "20"
actionOnStartupError: "standalone"
uiConfig:
apigwAuthPriority: form
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=VMYAI105BVT06: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 API Gateway on startup. Using this file 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 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, PROPERTIES and CC_YAML. YAML. A YAML configuration file. PROPERTIES. A properties configuration file. CC_YAML. A YAML configuration file, which is reserved for Command Central updates. |
allowEdit | Indicates whether this file can be updated from 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 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. Important:
For the CC_YAML file type, the location is fixed as cc-config.yml. This file must not be modified manually as it is updated directly by Command Central. Instead, use the Command Central interfaces to modify this file. |
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 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
Limitations
If you have defined cluster configuration in the externalized configuration file, on startup the 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. API Gateway server restart is required for the cluster settings to become effective and to join the cluster.