This page documents the YAML schema which can be used to configure IBM Application Gateway.
The secrets node defines secret data which can be used to obfuscate or encrypt entries within the YAML configuration documents.
Specifies an obfuscation key which is used to decrypt the OBF:<data> type entries.
The obfuscation key is a passphrase which can be used to perform key derivation to generate the key used to decrypt obfuscated entries.
An obfuscated entry can be generated with the following command which requires OpenSSL 1.1.1 or newer:
echo -n "<configuration entry>" | openssl enc -aes256
-pbkdf2 -pass pass:"<obfuscation key>" -md sha512
-base64
U2FsdGVkX19iBhlwc53+QkybjO6RjFHhSbz4VRudYHA=
This obfuscation key and obfuscated entry can be provided in the configuration YAML.
secrets:
obf_key: <obfuscation key>
identity:
oidc:
client_secret: OBF:U2FsdGVkX19iBhlwc53+QkybjO6RjFHhSbz4VRudYHA=
Specifies an encryption key which is used to decrypt the ENC:<data> type entries.
The encryption key is an RSA private key which can be used to decrypt entries which were encrypted using the corresponding RSA public key.
This entry must be a PEM representation of an RSA private key, beginning with -----BEGIN RSA PRIVATE KEY----- and ending with -----END RSA PRIVATE KEY-----.
An RSA key pair can be created with the following commands:
Generate the RSA private key:
openssl genrsa -out private.pem 2048
Generate the corresponding public key:
openssl rsa -pubout -in private.pem -out public.pem
An encrypted entry can be generated with the following command using the public key:
echo -n "<configuration entry>" | openssl rsautl
-encrypt -inkey public.pem -pubin | base64
oYpkxULIexyLR2wUl+mz6Nfki8Pd23Fv0buZZxAuh+Cq1A677NTZwmcWcWN9+MBBVJaISNM0uIVd33/n83Awf77Q/LXtjtzsk41Ux690YVsagh75n/BPk7Ca+4txzwB48yOrTKtIRVbNC2H+Rpa/7LMNSc1Zjez9PqNO4WIa323NzKA4y3Cx1h3DTKANrgsJgXDHNWNs/Ar9pPXxSeFNGmgnYRVtEZtN73IAMs8TzNJKNGkBkmr6vdZvlkjI6ebezJS1kawDvaKQ/C5GXdbpoaJE+JYgYsHDEZLpiasn0Ii4yt3HHNKpsX0UUBSIMO3di0brjJPoJFccVPHLDYgPlw==
This encryption key and encrypted entry can be provided in the configuration YAML.
secrets:
enc_key: '@private.pem'
identity:
oidc:
client_secret: ENC:oYpkxULIexyLR2wUl+mz6Nfki8Pd23Fv0buZZxAuh+Cq1A677NTZwmcWcWN9+MBBVJaISNM0uIVd33/n83Awf77Q/LXtjtzsk41Ux690YVsagh75n/BPk7Ca+4txzwB48yOrTKtIRVbNC2H+Rpa/7LMNSc1Zjez9PqNO4WIa323NzKA4y3Cx1h3DTKANrgsJgXDHNWNs/Ar9pPXxSeFNGmgnYRVtEZtN73IAMs8TzNJKNGkBkmr6vdZvlkjI6ebezJS1kawDvaKQ/C5GXdbpoaJE+JYgYsHDEZLpiasn0Ii4yt3HHNKpsX0UUBSIMO3di0brjJPoJFccVPHLDYgPlw==
The server node defines configuration for the gateway daemon front-end.
Specifies the protocols which will be supported by the server. The server will listen on a different port for each protocol: http/8080 and https/8443. If no protocols are specified, the server will listen for https requests only.
Additionally, the server can be configured to expect the PROXY Protocol header by using the *_proxy values.
Note that if the proxy protocol is enabled for a given protocol, all traffic for that protocol will be expected to contain the PROXY protocol headers. That is, the following entries are exclusive:
- http and http_proxy
- https and https_proxy
| Protocol | Port | Description |
|---|---|---|
http |
8080 |
HTTP |
https |
8443 |
HTTPS |
http_proxy |
8080 |
HTTP with Proxy Protocol |
https_proxy |
8443 |
HTTPS with Proxy Protocol |
The name(s) of the protocols which the gateway will listen on.
server:
protocols:
- https
- http_proxy
The rules which define whether a client is allowed to connect to this server. The rule is of the format:
[+|-]<client-ip>
where:
| Element | Description |
|---|---|
+ |
Indicates that the client is permitted access. |
- |
Indicates that the client is not permitted access. |
<client-ip> |
The IP address of the client, which can also contain the pattern matching characters * and ?. |
The client IP address of a request will be evaluated against each rule in sequence until a match is found. The corresponding code (+|-) will then be used to determine whether the client connection is accepted. If the client IP matches no configured rules the client connection will be accepted.
A client IP address pattern(s).
server:
client_ip_rules:
- +10.0.0.*
- -9.*.*.*
Specifies the secure configuration for the gateway server.
Specifies the configuration the gateway server will use when securely communicating with clients. This configuration includes:
The certificate to be used for secure communication with clients. If a certificate is not provided, the gateway will generate a self-signed certificate during bootstrapping.
The TLS protocols that are enabled for client communication.
Any additional server certificates which should be used for specific hosts using the server name indication (SNI) TLS extension.
server:
ssl:
front_end:
certificate:
- '@host.crt'
- '@host.key'
- '@ca.crt'
tlsv12: true
sni:
- certificate:
- '@test.crt'
- '@test.key'
hostname: www.test.com
- certificate:
- '@example.crt'
- '@example.key'
hostname: www.example.com
trust_certificates:
- '@www-dev.pem'
- '@redis-staging-1.pem'
- '@redis-staging-2.pem'
PEM based personal certificate files which will be used when communicating with the client. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
If a certificate is not provided, the gateway will generate a self-signed certificate during bootstrapping.
A boolean which indicates whether or not TLS v1.0 is enabled.
A boolean which indicates whether or not TLS v1.1 is enabled.
A boolean which indicates whether or not TLS v1.2 is enabled.
A boolean which indicates whether or not TLS v1.3 is enabled.
Specifies a list of SNI certificate to hostname mappings for the front end.
No Additional ItemsPEM based personal certificate files which will be used when communicating with clients which indicate this host. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
No Additional ItemsThe name of the host for this SNI entry.
Control the algorithms and parameters used in key agreement for TLSv1.2 and TLSv1.3.
If custom is specified, the supported_groups configuration must specify the named groups to use in the key exchange. For other entries, the named groups will be determined automatically.
Control which named groups to allow in the TLSv1.2 and TLSv1.3 key agreement. It is only used when key_agreement is set to custom.
ECDHE_X25519MLKEM768ECDHE_X25519ECDHE_SecP256r1MLKEM768ECDHE_SECP256R1ECDHE_SecP384r1MLKEM1024ECDHE_SECP384R1ECDHE_SECP521R1ECDHE_X448MLKEM768MLKEM1024The following groups can only be configured when TLSv1.3 is enabled:
ECDHE_X25519MLKEM768ECDHE_SecP256r1MLKEM768ECDHE_SecP384r1MLKEM1024MLKEM768MLKEM1024The name(s) of the groups which will be permitted.
For a list of valid ciphers, see:
- Supported Groups
- Supported Groups for TLSv1.3
Enables or disables the TLS protocols that are used for communication between the gateway daemon and the protected application.
server:
ssl:
applications:
tlsv13: true
A boolean which indicates whether or not TLS v1.0 is enabled.
A boolean which indicates whether or not TLS v1.1 is enabled.
A boolean which indicates whether or not TLS v1.2 is enabled.
A boolean which indicates whether or not TLS v1.3 is enabled.
Control the algorithms and parameters used in key agreement for TLSv1.2 and TLSv1.3.
If custom is specified, the supported_groups configuration must specify the named groups to use in the key exchange. For other entries, the named groups will be determined automatically.
Control which named groups to allow in the TLSv1.2 and TLSv1.3 key agreement. It is only used when key_agreement is set to custom.
ECDHE_X25519MLKEM768ECDHE_X25519ECDHE_SecP256r1MLKEM768ECDHE_SECP256R1ECDHE_SecP384r1MLKEM1024ECDHE_SECP384R1ECDHE_SECP521R1ECDHE_X448MLKEM768MLKEM1024The following groups can only be configured when TLSv1.3 is enabled:
ECDHE_X25519MLKEM768ECDHE_SecP256r1MLKEM768ECDHE_SecP384r1MLKEM1024MLKEM768MLKEM1024The name(s) of the groups which will be permitted.
For a list of valid ciphers, see:
- Supported Groups
- Supported Groups for TLSv1.3
Specifies the ciphers and cipher suites which will be permitted for all secure communications.
The following tables show the list of available ciphers.
TLS_DHE_PSK_WITH_AES_128_CCM_8TLS_DHE_PSK_WITH_AES_128_CCMTLS_DHE_PSK_WITH_AES_256_CCM_8TLS_DHE_PSK_WITH_AES_256_CCMTLS_DHE_RSA_WITH_AES_128_CCM_8TLS_DHE_RSA_WITH_AES_128_CCMTLS_DHE_RSA_WITH_AES_128_GCM_SHA256TLS_DHE_RSA_WITH_AES_256_CCM_8TLS_DHE_RSA_WITH_AES_256_CCMTLS_DHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHATLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHATLS_ECDHE_ECDSA_WITH_AES_128_CCM_8TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHATLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_ECDSA_WITH_RC4_128_SHATLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHATLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256TLS_ECDHE_RSA_WITH_AES_128_CBC_SHATLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384TLS_ECDHE_RSA_WITH_AES_256_CBC_SHATLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384TLS_ECDHE_RSA_WITH_RC4_128_SHATLS_PSK_WITH_AES_128_CCM_8TLS_PSK_WITH_AES_128_CCMTLS_PSK_WITH_AES_256_CCM_8TLS_PSK_WITH_AES_256_CCMTLS_RSA_EXPORT1024_WITH_DES_CBC_SHATLS_RSA_EXPORT1024_WITH_RC4_56_SHATLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5TLS_RSA_EXPORT_WITH_RC4_40_MD5TLS_RSA_WITH_3DES_EDE_CBC_SHATLS_RSA_WITH_AES_128_CBC_SHA256TLS_RSA_WITH_AES_128_CBC_SHATLS_RSA_WITH_AES_128_CCM_8TLS_RSA_WITH_AES_128_CCMTLS_RSA_WITH_AES_128_GCM_SHA256TLS_RSA_WITH_AES_256_CBC_SHA256TLS_RSA_WITH_AES_256_CBC_SHATLS_RSA_WITH_AES_256_CCM_8TLS_RSA_WITH_AES_256_CCMTLS_RSA_WITH_AES_256_GCM_SHA384TLS_RSA_WITH_DES_CBC_SHATLS_RSA_WITH_NULL_MD5TLS_RSA_WITH_NULL_NULLTLS_RSA_WITH_NULL_SHATLS_RSA_WITH_RC4_128_MD5TLS_RSA_WITH_RC4_128_SHATLS_RSA_WITH_NULL_SHA256TLS_ECDHE_ECDSA_WITH_NULL_SHATLS_ECDHE_RSA_WITH_NULL_SHATLS_AES_128_GCM_SHA256TLS_AES_256_GCM_SHA384TLS_CHACHA20_POLY1305_SHA256TLS_AES_128_CCM_SHA256TLS_AES_128_CCM_8_SHA256The name(s) of the ciphers and cipher suites which will be permitted.
For a list of valid ciphers, see:
- Supported Cipher Names
- Supported TLSv1.3 Cipher Names
server:
ssl:
ciphers:
- TLS_PSK_WITH_AES_256_CCM
- TLS_AES_128_CCM_8_SHA256
PEM based signer certificates or signer certificate chains which should be added to IAG's trust store. These can be signer certificates which are required for secure communication with resource servers or external services.
No Additional ItemsPEM certificate data.
server:
ssl:
trust_certificates:
- '@www-dev.pem'
- '@redis-staging-1.pem'
- '@redis-staging-2.pem'
Specifies the configuration related to failover support for the IBM Application Gateway.
server:
failover:
key: 123A....
cookie_name: jwe_cookie
domain_cookie: false
The key which is used to protect the failover JWE cookie. This key should be 512 bits in length. If the key is greater than this size it will be truncated, and if it is less than this size it will be right-padded with 0's. An example openssl command to create this key is: openssl rand -out oct-512-bit.bin 64
Specifies the configuration for client sessions.
server:
session:
cookie_name: sess_cookie
max_sessions: 20
timeout: 600
inactive_timeout: 100
redis:
enabled: true
key_prefix: iag-
default_collection: test-collection
client_list_cache_lifetime: 10
concurrent_sessions:
enabled: true
prompt_for_displacement: true
max_user_sessions: 15
user_identity_attribute_name: AZN_CRED_PRINCIPAL_NAME
reauth:
login_time_window: 10
The maximum number of concurrent sessions.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum lifetime (in seconds) for a session. If set to 0 the sessions will not have a maximum lifetime, however once max_sessions is reached sessions will be reaped using a least recently used algorithm.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum lifetime (in seconds) a session can remain inactive before it is expired. If set to 0 the sessions will not have a maximum inactive lifetime.
Value must be greater or equal to 0 and lesser or equal to unlimited
During an obligated re-authentication, depending on the policy and identity provider a different user credential may be returned to the application gateway. By default, the application gateway will not accept a credential if the user name does not match the user which the session was originally established for. Use this entry to change the behaviour and allow the application gateway to accept a credential containing a different user name during re-authentication.
Specifies the configuration for distributed sessions using a Redis environment.
Redis collections are defined using the services/redis[] entry.
Enables the Redis session cache.
The server needs to manually delete stale entries from the Redis cache during session creation and idle timeout events. In order to be able to delete the stale entries it needs an up-to-date list of active clients of the Redis server (using the CLIENT LIST Redis command). This command, depending on the number of clients which are registered with the Redis server, can be expensive and so IAG will cache and reuse the returned list of clients for a small period of time. This configuration entry controls the length of time, in seconds, that a client list will be cached.
Value must be greater or equal to 0 and lesser or equal to unlimited
Specifies the configuration information associated with the tracking and management of concurrent user sessions.
Is concurrent user session tracking and management enabled?
If enabled the gateway will prompt users before automatically displacing existing sessions with the same user identity. If disabled the gateway will automatically log out the existing user session.
The maximum number of concurrent sessions which are allowed for a single user. A value of 0 indicates that an unlimited number of sessions are allowed, and a value of -1 indicates that only a single session is allowed for the user and that any existing sessions will be displaced by the new session. The maximum number of user sessions for a particular session can also be defined using the tagvalue_max_concurrent_web_sessions attribute of the credential.
Value must be greater or equal to -1 and lesser or equal to unlimited
The name of the credential attribute which holds the unique user identity for the session. If the configured attribute does not exist in the credential the default user identity of unknown will be used.
These entries control the behaviour of the re-authentication policies.
Controls the amount of time a re-authentication will be considered valid for. This is a time (in seconds) after a re-authentication occurs during which a client will not be prompted to perform re-authentication again.
By default, the logintimewindow is set to zero, which means that every request to a resource protected with the reauth policy directive will require the client to perform re-authentication.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum number of concurrent connections allowed per client IP address. Once the maximum number of concurrent connections has been reached, subsequent connections from the client IP will not be accepted and will simply be closed. A value of 0 indicates that an unlimited number of connections will be allowed for each client IP.
Value must be greater or equal to 0 and lesser or equal to unlimited
server:
max_concurrent_connections_per_ip: 10
The number of configured worker threads specifies the number of concurrent incoming requests that can be serviced by this gateway instance. Choosing the optimal number depends on the quantity and type of traffic on your network. Modifying this value should be done carefully to ensure optimal performance.
Value must be greater or equal to 1 and lesser or equal to unlimited
server:
worker_threads: 300
A boolean which indicates whether or not to enable support for HTTP/2 clients. HTTP/2 supports a reduced set of cipher suites. The minimum cipher is TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 which should be added to the server/ssl/ciphers[] entry.
server:
http2: true
Specifies the configuration for WebSocket support.
server:
websocket:
worker_threads:
max: 100
idle: 0
timeouts:
applications:
read: 30
write: 30
front_end:
read: 30
write: 30
The number of available WebSocket worker threads.
The maximum number of threads which will be used used to proxy WebSocket connections through the gateway. A value of zero will cause WebSockets to be blocked. Each WebSocket connection will require two worker threads. If more than the max value are in use, the daemon will immediately close the WebSocket even if the WebSocket upgrade request to the application succeeded. The WebSocket threads operate independently from the server:worker_threads entry.
Value must be greater or equal to 0 and lesser or equal to unlimited
To avoid the overhead of starting and stopping web socket worker threads a number of threads can be left running idle. This will consume memory resources to keep them alive and idle when not in use, but will save CPU and thread start-up time when a new web socket requires threads. This option specifies the maximum count of cached idle worker threads. A value of zero will disable the caching of idle threads.
Value must be greater or equal to 0 and lesser or equal to unlimited
Web socket timeout settings.
Specifies the web socket timeouts for connections between the gateway daemon and protected applications (in seconds). If the timeout is reached the web socket connection will be closed.
The maximum length of time (in seconds) to wait on a read operation to complete.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum length of time (in seconds) to wait on a write operation to complete.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies the web socket timeouts for connections to the gateway (in seconds). If the timeout is reached the web socket connection will be closed.
The maximum length of time (in seconds) to wait on a read operation to complete.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum length of time (in seconds) to wait on a write operation to complete.
Value must be greater or equal to 1 and lesser or equal to unlimited
Defines static assets which are served from the default / path of the reverse proxy. This entry must be either a zip file or a path which is relative to the /var/iag/config directory of the container. The provided contents will completely replace the default set of pages served from the / path of the IAG.
If no value is specified here, the default set of pages will be used. The default set of pages, local_pages.zip, can be downloaded from GitHub (https://github.com/IBM-Security/ibm-application-gateway-resources/tree/master/pages) and used as a starting point for creating custom pages.
server:
local_pages:
content: '@myPages.zip'
type: zip
The content which will be used for the local web space. The content can either be the name of a directory, relative to the /var/iag/config directory of the container, or a zip file.
The type of content which is being supplied. Either a zip file or a directory name.
This entry overloads the server generated management response pages.
This entry must be either a zip file or a path which is relative to the /var/iag/config directory of the container.
The provided contents will completely replace the default set of management pages served by the IAG.
The pages which are provided should conform to the directory structure and file name syntax explained below.
The directory structure is:
<language_code>/<page_name>.<response_code>.<mime_type>
<language_code> is a directory containing all the pages which will be presented to clients which prefer that language.
If you do not wish to ever return pages to clients in a specific language, the corresponding language_code directory can be omitted.
The reverse proxy will use the container language (set via the LANG environment variable) if a page is requested in a language which is not provided.
For example, to only ever return management pages in English and French, include only the C and fr directories in the zip file and run the container with LANG=C.
When a language other than English or French is requested, the page will fall back to LANG and be returned in English.
language_code |
Language |
|---|---|
| pt | Brazilian Portuguese |
| cs | Czech |
| zh_CN | Chinese (Simplified) |
| zh_TW | Chinese (Traditional) |
| C | English |
| fr | French |
| de | German |
| hu | Hungarian |
| it | Italian |
| ja | Japanese |
| ko | Korean |
| pl | Polish |
| es | Spanish |
| ru | Russian |
<page_name> corresponds to the specific event which the page is returned for.
The list of valid page_names are:
page_name |
|---|
| help |
| login_success |
| logout |
| oidc_fragment |
| ratelimit |
| redirect |
| tempcacheresponse |
<response_code> can be used to control the HTTP status code which the reverse proxy presents when it serves the page.
This part of filename is optional and 200 will be used if no response_code is indicated.
<mime_type> corresponds to the mime sub-type which this page will be returned for.
For example, if a client request contains the accept header text/html, html is the mime sub-type and should be used for the file extension.
If an accept header is not present, the reverse proxy will also consider the content-type header.
For example, to customise:
ratelimit management responsetext/htmlCreate the following file in the zip file of management response pages:
C/ratelimit.500.html
If no value is specified here, the default set of pages will be used.
The default set of pages, management_pages.zip, can be downloaded from GitHub (https://github.com/IBM-Security/ibm-application-gateway-resources/tree/master/pages) and used as a starting point for creating custom management pages.
server:
management_pages:
content: '@mgmtPages.zip'
type: zip
The content which will be used for the management pages. The content can either be the name of a directory, relative to the /var/iag/config directory of the container, or a zip file.
The type of content which is being supplied. Either a zip file or a directory name.
This entry overloads the server generated error response pages.
This entry must be either a zip file or a path which is relative to the /var/iag/config directory of the container.
The provided contents will completely replace the default set of error pages served by the IAG.
The pages which are provided should conform to the directory structure and file name syntax explained below.
The directory structure is:
<language_code>/<error_code>.<response_code>.<mime_type>
<language_code> is a directory containing all the pages which will be presented to clients which prefer that language.
If you do not wish to ever return pages to clients in a specific language, the corresponding language_code directory can be omitted.
The reverse proxy will use the container language (set via the LANG environment variable) if a page is requested in a language which is not provided.
For example, to only ever return error pages in English and French, include only the C and fr directories in the zip file and run the container with LANG=C.
When a language other than English or French is requested, the page will fall back to LANG and be returned in English.
language_code |
Language |
|---|---|
| pt | Brazilian Portuguese |
| cs | Czech |
| zh_CN | Chinese (Simplified) |
| zh_TW | Chinese (Traditional) |
| C | English |
| fr | French |
| de | German |
| hu | Hungarian |
| it | Italian |
| ja | Japanese |
| ko | Korean |
| pl | Polish |
| es | Spanish |
| ru | Russian |
<error_code> corresponds to a specific error code in hexadecimal format.
The special error code of default can also be used to configure a default page which is used for any error codes which do not have a specific page.
<response_code> can be used to control the HTTP status code which the reverse proxy presents when it serves the page.
This part of filename is optional and the default value will be used if no response_code is indicated.
error_code |
Default response_code |
Description |
|---|---|---|
| 38cf0420 | 301 | Moved Permanently |
| 38cf0421 | 302 | Moved Temporarily |
| 38cf0427 | 403 | Forbidden |
| 38cf0428 | 404 | Not Found |
| 38cf04c6 | 500 | Server Not Responding |
| 38cf04d7 | 500 | Server Not Responding |
| 38cf08cc | 403 | Forbidden (Time based) |
| default | 400 | Any other error code |
<mime_type> corresponds to the mime sub-type which this page will be returned for.
For example, if a client request contains the accept header text/html, html is the mime sub-type and should be used for the file extension.
If an accept header is not present, the reverse proxy will also consider the content-type header.
For example, to customise:
forbidden error response (error code 38cf0427)application/jsonCreate the following file in the zip file of error response pages:
ko/38cf0427.500.json
If no value is specified here, the default set of pages will be used.
The default set of pages, error_pages.zip, can be downloaded from GitHub (https://github.com/IBM-Security/ibm-application-gateway-resources/tree/master/pages) and used as a starting point for creating custom error pages.
server:
error_pages:
content: '@errorPages.zip'
type: zip
The content which will be used for the error pages. The content can either be the name of a directory, relative to the /var/iag/config directory of the container, or a zip file.
The type of content which is being supplied. Either a zip file or a directory name.
This entry overloads the default assets used in server generated error and management response pages.
These assets are served by the application gateway on the configured path segment (default pkmspublic) and are suitable for embedding in server generated responses such as error or management pages.
If no value is specified here, the default set of assets will be used.
The default set of assets, used by the default error and management pages, public_assets.zip, can be downloaded from GitHub (https://github.com/IBM-Security/ibm-application-gateway-resources/tree/master/pages).
server:
public_assets:
content: '@publicAssets.zip'
type: zip
path_segment: public
The content which will be used for the public assets. The content can either be the name of a directory, relative to the /var/iag/config directory of the container, or a zip file.
The type of content which is being supplied. Either a zip file or a directory name.
The path which the assets will be available from. By default, this is pkmspublic.
The language(s) which will be permitted when the application gateway generates error and management response pages. The accept-language HTTP header from the request is used to determine the language used when generating responses.
The first language in the list will be treated as the default language. The default language will be used if none of the languages contained in the accept-language HTTP header have been enabled.
If this entry is not defined, all languages will be enabled with English (C) set as the default.
language code |
Language |
|---|---|
| pt | Brazilian Portuguese |
| cs | Czech |
| zh_CN | Chinese (Simplified) |
| zh_TW | Chinese (Traditional) |
| C | English |
| fr | French |
| de | German |
| hu | Hungarian |
| it | Italian |
| ja | Japanese |
| ko | Korean |
| pl | Polish |
| es | Spanish |
| ru | Russian |
The language(s) which will be permitted when the application gateway generates error and management response pages.
server:
enabled_languages:
- fr
- ja
Specifies the configuration for the credential service cache. When the cache is enabled, IAG will cache the encrypted credentials received from the external credential service. If the cache is not enabled, IAG will request credentials from the credential service for every request requiring single sign-on.
server:
credential_service_cache:
cache_enabled: true
cache_size: 2048
entry_lifetime: 3600
entry_idle_timeout: 3600
login_clear_user: true
A boolean to indicate whether the credential service cache is enabled or not.
The cache size, the number of entries which will be cached.
Value must be greater or equal to 0 and lesser or equal to unlimited
The entry lifetime, the maximum number of seconds entries will be cached for, regardless of whether they are being used or not.
Value must be greater or equal to 0 and lesser or equal to unlimited
The entry idle timeout, the number of seconds a cache entry which is not being used will remain cached for.
Value must be greater or equal to 0 and lesser or equal to unlimited
If set to true, on successful authentication any existing cached credentials for the authenticating user will be cleared.
Specifies the configuration for any embedded applications.
Specifies the configuration information related to the embedded credential viewer application.
The credential viewer application can be used to display information about the credential associated with the current user session.
Note: The credential viewer application is not accessible through a virtual host junction. This is because, in the case of a virtual host junction, the back-end server is mounted at the root of the object space. As a result, any attempt to access local applications results in trying to source the application from the back-end server instead of locally.
The rules which define the credential attributes which will be included in the response data.
The format of the configuration entry is:
[+|-]<attribute-name>
where:
| Element | Description |
|---|---|
| + | Indicates that this attribute should be added to the response. |
| - | Indicates that this attribute should not be added to the response. |
| <attribute-name> | The name of the credential attribute, which can also contain pattern matching characters (i.e. * ?). |
For example the value -AUTHENTICATION_LEVEL indicates that the authentication level attribute should not be added to the response.
When constructing a response each credential attribute will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the credential attribute will be added to the response or not.
If the attribute name does not match a configured rule it will, by default, be added to the response.
The rule could alternatively contain the name of a single credential attribute whose value is used to define the attribute rules.
In this scenario each individual rule in the attribute should be separated by a space character.
If only a single attribute-rule configuration entry is defined, and the entry does not start with a + or - character, it will be used as the name of the credential attribute which contains the attribute rules.
server:
local_applications:
cred_viewer:
path_segment: credview
enable_html: true
attributes:
- -AUTHENTICATION_LEVEL
The path at which the application will be available. The path should be a simple path segment (i.e. should not contain a / character).
A boolean flag indicating whether or not the embedded HTML page which can render the JSON data is enabled.
The rules which define the credential attributes which will be included in the response data. See the Attributes Format table for a description of the expected format.
No Additional ItemsSpecifies the configuration information related to the embedded authorization decision application. The authorization decision application provides a Web service for making remote authorization decisions.
server:
local_applications:
azn_decision:
path_segment: azndec
max_cache_size: 100
max_cache_lifetime: 60
The path at which the application will be available. The path should be a simple path segment (i.e. should not contain a / character).
The maximum number of credentials which can be cached. If the addition of a new credential will exceed this maximum cache size a least-recently-used algorithm will be used to remove an older entry, making room for the new credential.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum lifetime, in seconds, of an entry in the cache.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies the configuration information related to the embedded jwks application. The jwks application returns the public keys contained in the key database used for junction communication. The response data will conform to RFC 7517.
server:
local_applications:
jwks:
path_segment: jwks
The path at which the application will be available. The path should be a simple path segment (i.e. should not contain a / character).
Specifies the global configuration related to rate limiting. Rate limiting policies are defined using the policies/rate_limiting[] entry.
Additional rate limiting headers can also be enabled. The rate limiting response headers include:
| header | value |
|---|---|
| X-Rate-Limit-Policy | The name of the rate limiting policy which is closest to being hit. |
| X-Rate-Limit-Remaining | The number of requests left for the rate limiting policy in the current rate limit window. |
| X-Rate-Limit-Reset | The time (UTC Epoch time) at which the rate limiting policy resets. |
server:
rate_limiting:
cache_size: 16384
response_headers: false
redis:
collection_name: test-collection
sync_window: 10
The number of unique records to cache locally for the rate limiting capability. When this cache is exhausted, the oldest cached records are ejected. This effectively resets the rate limiting counters for this client(s). This number needs to be higher than the number of requests being rate limited across a refresh interval.
Value must be greater or equal to 1 and lesser or equal to unlimited
These entries control whether or not rate limiting data will be stored in a Redis database. When stored in a Redis database, rate limiting data can be shared across multiple gateway instances.
Specify the name of a Redis collection which will be used for maintaining rate limiting data. Redis collections are defined using the services/redis[] entry.
The length of time (in seconds) a record from Redis will be cached locally by this instance. Records will only be synchronized with Redis after this window has elapsed.
Value must be greater or equal to 0 and lesser or equal to unlimited
Specifies whether or not the gateway will insert the rate limiting headers into responses.
By default, the rate limiting response headers are disabled.
Specifies whether or not the gateway will use the default content security policy.
The default policy inserts the following HTTP headers into all responses:
| header | value |
|---|---|
| x-frame-options | DENY |
| x-xss-protection | 1 |
| content-security-policy | default-src 'self'; frame-ancestors 'self'; form-action 'self'; |
| x-content-type-options | nosniff |
server:
content_security_policy: disabled
This entry can be used to set HTTP headers which are always present in all responses which are returned to clients.
For each entry, only one of macro, attribute or text can be specified.
Each entry corresponds to a single HTTP header.
The name of the HTTP header to be included in the response.
The name of a credential attribute which the value will be taken from.
String content which will be inserted into the header verbatim.
server:
response_headers:
- header: X-Client-ID
macro: USER
- header: X-Client-Apparent-IP
attribute: AZN_CRED_NETWORK_ADDRESS_STR
- header: X-IBM-Environment
text: staging
This node defines how users will authenticate to the reverse proxy.
These entries can be used to override the default authentication challenge which unauthenticated clients will be redirected to when first accessing the reverse proxy.
If an OIDC identity source is configured, this entry will default to the OIDC authentication URI "/pkmsoidc?iss=default".
identity:
auth_challenge_redirect:
url: /eai/login_start
parameters:
- source: macro
value: HOSTNAME
name: host
- source: credential
value: AZN_CRED_NETWORK_ADDRESS_STR
name: origin
- source: header
value: X-IBM-Proxy
name: proxy
The URI which a client will be redirected to in order to start the authentication process. This URI can be absolute or server relative.
Additional parameters which can be included in the redirect URI as query string arguments.
No Additional ItemsThe source the value should be taken from.
The name which should be used to name the parameter inserted into the redirect URL. If this value is not specified, the parameter will be named accordingly:
macro sources, the name will be used verbatim.header sources, the name will be of the format HTTPHDR_<name>credential sources, the name will be of the format CREDATTR_<name>These entries can be used to override the default post authentication URL which clients will be redirected to once they have successfully authenticated.
identity:
auth_complete_redirect:
url: /landing
parameters:
- source: macro
value: HOSTNAME
name: host
- source: credential
value: AZN_CRED_NETWORK_ADDRESS_STR
name: origin
- source: header
value: X-IBM-Proxy
name: proxy
The URI which a client will be redirected to upon successful authentication. This URI can be absolute or server relative.
Additional parameters which can be included in the redirect URI as query string arguments.
No Additional ItemsThe source the value should be taken from.
The name which should be used to name the parameter inserted into the redirect URL. If this value is not specified, the parameter will be named accordingly:
macro sources, the name will be used verbatim.header sources, the name will be of the format HTTPHDR_<name>credential sources, the name will be of the format CREDATTR_<name>The configuration entries in this section allow the reverse proxy to act as an OIDC relying party.
IBM Security Verify, IBM Security Verify Access and IBM Security Access Manager 9.0.7.0+ are supported as OIDC identity providers.
| Name | Description |
|---|---|
| code | The authorization code flow will be used to retrieve both an access token and identity token. |
| id_token | The implicit flow will be used to retrieve the identity token. |
| id_token token | The implicit flow will be used to retrieve both an access token and identity token. |
A JSON data element from the bearer token response which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:
[+|-]<json-data>
where:
| Element | Description |
|---|---|
| + | Indicates that this JSON data should be added to the credential. |
| - | Indicates that this JSON data should not be added to the credential. |
| <json-data> | The corresponding JSON data name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-accesstoken" indicates that the accesstoken should not be added to the credential.
When a bearer token is received each JSON data element will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the JSON data will be added to the credential or not.
If the JSON data name does not match a configured rule it will by default be added to the credential.
A claim from the ID token response which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:
[+|-]<claim>
where:
| Element | Description |
|---|---|
| + | Indicates that this claim should be added to the credential. |
| - | Indicates that this claim should not be added to the credential. |
| <claim> | The corresponding claim name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-email" indicates that the email claim should not be added to the credential.
When an ID token is received each claim will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the claim will be added to the credential or not.
If the claim name does not match a configured rule it will by default be added to the credential.
identity:
oidc:
- discovery_endpoint: https://www.test.com/mga/sps/oauth/oauth20/metadata/oidc_def
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
client_secret: 1a2b3c4d5e
pkce: true
ssl:
certificate:
- '@www-test-com-ca.pem'
mapped_identity: '{sub}'
redirect_uri_host: www.test2.com
response_type: code
response_mode: query
proxy: https://www.testproxy.com:443
scopes:
- profile
- email
allowed_query_args:
- oidc_test=value
bearer_token_attrs:
- -access_token
id_token_attrs:
- -email
- name: other_provider
discovery_endpoint: https://www.provider.com/oidc/discovery
client_id: 66666666-7777-8888-9999-10101010101010
client_secret: 6f7g8h9ij10
The name of this provider. This field is optional and if not supplied the name "default" will be used.
The name field is used to determine the kick-off URL for this OIDC provider. The format of the kick-off URL is /pkmsoidc?iss=<name>.
Note that each OIDC provider must have a unique name.
The fully qualified discovery endpoint for the OIDC OP.
For IBM Security Verify, this URL is usually in the format: https://<verify-hostname>/oidc/endpoint/default/.well-known/openid-configuration
For IBM Security Verify Access, this URL is usually in the format: https://<verify-access-hostname>/<junction>/sps/oauth/oauth20/metadata/<definition_name>
The client identity registered with the identity provider.
The client secret registered with the identity provider.
Enables Proof Key for Code Exchange (RFC 7636). Enable this option if the OIDC provider requires PKCE.
SSL settings for the OIDC connection.
If required, any signer certificates required for the reverse proxy to trust the identity provider can be specified here in PEM format.
No Additional ItemsA formatted string which is used to construct the credential principal name from elements of the ID token. Claims can be added to the identity string, surrounded by {}, for example:
{iss}/{sub} - would construct a principal name like the following:
https://server.example.com/248289761001
This is the host which is used in the redirect URI registered with the OIDC OP. If no redirect URI host is configured the host header from the request will be used. The format of the redirect URI will be: http[s]://<host>/pkmsoidc.
The required response type for authentication responses. See the Response Type Values table for a description of the available values.
The required response mode for authentication responses. If no response mode is configured the response mode parameter will not be included in the authentication request.
Specifies the proxy, if any, which is used to reach the identity provider. The proxy configuration entry should be in URL format. Eg: http[s]://<address>:<port>
Any scopes to be sent in the authentication request in addition to the openid scope.
Additional query string arguments can be provided to the authentication kick-off URL which will in turn be appended to the corresponding authentication request. This entry is used to define a list of allowed query string arguments. Any other arguments passed to the kick-off URL will be ignored.
No Additional ItemsA list of JSON data elements from the bearer token response which should be included or excluded in the credential as an extended attribute. See the Bearer Token Attrs Format table for a description of the expected format.
No Additional ItemsA list of claims from the ID token response which should be included or excluded in the credential as an extended attribute. See the ID Token Attrs Format table for a description of the expected format.
No Additional ItemsThe configuration entries in this section allow the reverse proxy to accept an OAuth bearer token and use the configured OAuth introspection endpoints to validate the token and create an authenticated session.
IBM Security Verify, IBM Security Verify Access and IBM Security Access Manager 9.0.7.0+ provide supported OAuth introspection endpoints.
Multiple introspection endpoints may be different so that different providers can be enabled for different resource servers.
A JSON data element from the introspection response token which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:
[+|-]<json-data>
where:
| Element | Description |
|---|---|
| + | Indicates that this JSON data should be added to the credential. |
| - | Indicates that this JSON data should not be added to the credential. |
| <json-data> | The corresponding JSON data name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-exp" indicates that the expiry time of the token should not be added to the credential.
When an introspection response token is received each JSON data element will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the JSON data will be added to the credential or not.
If the JSON data name does not match a configured rule it will by default be added to the credential.
The name which is used to identify and describe this endpoint.
A boolean flag which indicates whether this endpoint is restricted to certain resource servers or not. If the endpoint is restricted only those resource servers which specifically mention this endpoint, using the identity/oauth element within the resource server definition, will be allowed to use this endpoint.
The fully qualified introspection endpoint for the OAuth provider.
For IBM Security Verify, this URL is usually in the format:<br/>
https://<verify-hostname>/v1.0/endpoint/default/introspect
For IBM Security Verify Access, this URL is usually in the format:<br/>
https://<verify-access-hostname>/<junction>/sps/oauth/oauth20/introspect
The client identity which is used to authenticate to the introspection endpoint.
The client secret which is used to authenticate to the introspection endpoint. If a client_id field is not configured the secret will be treated as a bearer token, otherwise it will be used in a basic authentication header.
The name of the HTTP header which contains the client identifier which is used to authenticate to the introspection endpoint. This configuration entry is mutually exclusive with the clientid configuration entry. If the clientid configuration entry is provided this configuration entry will be ignored.
Introspection can be authenticated with BA or Forms. Specify the value client_secret_post to post the client credentials or client_secret_basic to provide the credentials via the Authorization header. If not provided will default to client_secret_post
A hint about the type of the token submitted for introspection.
SSL settings for the OAuth introspection connection.
If required, any signer certificates required for the reverse proxy to trust the OAuth provider can be specified here in PEM format.
No Additional ItemsA formatted string which is used to construct the credential principal name from elements of the introspection response token. Claims can be added to the identity string, surrounded by {}, for example:
{iss}/{sub} - would construct a principal name like the following:
https://server.example.com/248289761001
Specifies the proxy, if any, which is used to reach the OAuth provider. The proxy configuration entry should be in URL format. Eg: http[s]://<address>:<port>
A list of JSON data elements from the introspection response token which should be included in or excluded from the credential as an extended attribute. See the Attributes Format table for a description of the expected format.
No Additional ItemsBy default the OAuth scope attribute is provided as a single space separated string. By enabling this configuration option the scope attribute will instead be converted to a multi-value attribute.
Additional HTTP headers which can be included in the introspection request.
No Additional ItemsThe source that the HTTP header value should be taken from.
For the header or credential type, the name of the HTTP header or credential attribute the value will be taken from.
For the text type, this is the string literal which will be used as the value.
The name of the HTTP header which will be included in the introspection request.
identity:
oauth:
- name: verify_introspection
restricted: false
introspection_endpoint: https://ibm-app-gw.verify.ibm.com/v1.0/endpoint/default/introspect
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
client_secret: 1a2b3c4d5e
auth_method: client_secret_post
proxy: https://www.testproxy.com:443
token_type_hint: access_token
ssl:
certificate:
- '@www-test-com-ca.pem'
mapped_identity: '{sub}'
attributes:
- +scope
- +client_id
- +iat
- +exp
multi_valued_scope: true
headers:
- source: header
value: host
name: X-Forwarded-For
- source: credential
value: AZN_CRED_NETWORK_ADDRESS_STR
name: origin
- source: text
value: green
name: X-Deployment-Status
External Authentication Interface, which allows an application to assert client identity information to the IBM Application Gateway container.
Please note that an access policy which allows unauthenticated access to this resource must be created. The URL string patterns are case-sensitive and may contain wild card patterns.
The format for a regular path-based application is: <URL pattern>
The format for a Virtual Host application is: http[s]://virtual-host-name[:port]/<URL pattern>
For Virtual Host applications to match a trigger they must also have the same protocol (http[s] = TCP/SSL) and have the same virtual-host-name and port as the trigger.
identity:
eai:
triggers:
- /auth_app/login_complete
- /auth_app/login_complete_v2
- https://auth.ibm.com:9443/eai/login
- https://auth.ibm.com:9443/eai/login_v2
The list of URLs for which the response could potentially contain authentication information.
No Additional ItemsThe configuration entries in this section allow the reverse proxy to act as an OIDC relying party to IBM Security Verify.
This identity module is no longer preferred and will be removed in a future version. Use the OIDC identity module.
When using the OIDC identity module, discovery_endpoint is given rather than hostname.
The format for an IBM Security Verify discovery_endpoint is:
https://<hostname>/oidc/endpoint/default/.well-known/openid-configuration
For example, refer to the IBM Security Verify OIDC configuration below:
identity:
ci_oidc:
hostname: www.test.com
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
# ...
The equivalent OIDC configuration is:
identity:
oidc:
discovery_endpoint: https://www.test.com/oidc/endpoint/default/.well-known/openid-configuration
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
# ...
| Name | Description |
|---|---|
| code | The authorization code flow will be used to retrieve both an access token and identity token. |
| id_token | The implicit flow will be used to retrieve the identity token. |
| id_token token | The implicit flow will be used to retrieve both an access token and identity token. |
A JSON data element from the bearer token response which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:
[+|-]<json-data>
where:
| Element | Description |
|---|---|
| + | Indicates that this JSON data should be added to the credential. |
| - | Indicates that this JSON data should not be added to the credential. |
| <json-data> | The corresponding JSON data name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-accesstoken" indicates that the accesstoken should not be added to the credential.
When a bearer token is received each JSON data element will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the JSON data will be added to the credential or not.
If the JSON data name does not match a configured rule it will by default be added to the credential.
A claim from the ID token response which should be included or excluded in the credential as an extended attribute.
The format of the configuration entry is:
[+|-]<claim>
where:
| Element | Description |
|---|---|
| + | Indicates that this claim should be added to the credential. |
| - | Indicates that this claim should not be added to the credential. |
| <claim> | The corresponding claim name, which can also contain pattern matching characters (i.e. * ?). |
For example the value "-email" indicates that the email claim should not be added to the credential.
When an ID token is received each claim will be evaluated against each rule in sequence until a match is found.
The corresponding code (+|-) will then be used to determine whether the claim will be added to the credential or not.
If the claim name does not match a configured rule it will by default be added to the credential.
identity:
ci_oidc:
hostname: www.test.com
client_id: 11111111-2222-3333-4444-5a5a5a5a5a5a5a
client_secret: 1a2b3c4d5e
mapped_identity: '{sub}'
redirect_uri_host: www.test2.com
response_type: code
response_mode: query
proxy: https://www.testproxy.com:443
scopes:
- profile
- email
allowed_query_args:
- oidc_test=value
bearer_token_attrs:
- -access_token
id_token_attrs:
- -email
The fully qualified host name of the IBM Security Verify tenant.
The client identity registered with IBM Security Verify.
The client secret registered with IBM Security Verify.
A formatted string which is used to construct the credential principal name from elements of the ID token. Claims can be added to the identity string, surrounded by {}, for example:
{iss}/{sub} - would construct a principal name like the following:
https://server.example.com/248289761001
This is the host which is used in the redirect URI registered with the OIDC OP. If no redirect URI host is configured the host header from the request will be used. The format of the redirect URI will be: http[s]://<host>/pkmsoidc.
The required response type for authentication responses. See the Response Type Values table for a description of the available values.
The required response mode for authentication responses. If no response mode is configured the response mode parameter will not be included in the authentication request.
Specifies the proxy, if any, which is used to reach IBM Security Verify. The proxy configuration entry should be in URL format. Eg: http[s]://<address>:<port>
Any scopes to be sent in the authentication request in addition to the openid scope.
Additional query string arguments can be provided to the authentication kick-off URL which will in turn be appended to the corresponding authentication request. This entry is used to define a list of allowed query string arguments. Any other arguments passed to the kick-off URL will be ignored.
No Additional ItemsA list of JSON data elements from the bearer token response which should be included or excluded in the credential as an extended attribute. See the Bearer Token Attrs Format table for a description of the expected format.
No Additional ItemsA list of claims from the ID token response which should be included or excluded in the credential as an extended attribute. See the ID Token Attrs Format table for a description of the expected format.
No Additional ItemsThe resource_servers node defines the resource servers which provide content for the gateway.
The definition for a single resource server which provides content for the gateway.
The path at which the resource server will be made available. This entry is required if the virtual_host entry has not been specified. It is not valid to have both path and virtual_host entries specified.
resource_servers:
- path: /static
The virtual host, as defined by the host header in the request, at which the resource server will be made available. This will be the hostname and port number specified in the web browser when it makes the request. The port number should always be specified, whether the default port is being used (443 for SSL), or if the virtual host is using a non-default port for the intended protocol. If your docker or container host is mapping an incoming port number such as 443 to some other port inside the container (i.e. 8443), then specify here the incoming port number (i.e. 443).
This entry is required if the path entry has not been specified.
It is not valid to have both path and virtual_host entries specified.
resource_servers:
- virtual_host: application.ibm.com:443
The connection type the reverse proxy will make for this resource server.
resource_servers:
- path: /example
connection_type: ssl
A boolean flag indicating whether or not this resource server uses a transparent path. For path type resource servers, setting this entry to true will result in the passing of the entire URL as observed by the reverse proxy to the resource server, including the value given in "path". If set to false the reverse proxy will filter the path from the URL and pass only the remainder of the URL to the resource server.
resource_servers:
- path: /example
transparent_path: true
A boolean flag indicating whether or not user requests, for the lifetime of a session, are always processed by the same resource server.
resource_servers:
- path: /example
stateful: true
Specifies the information associated with the HTTP2 configuration of the resource server.
resource_servers:
- path: /example
http2:
enabled: true
A boolean flag indicating whether or not to use HTTP/2 when making requests by the reverse proxy to the resource server.
The Server Name Indicator the reverse proxy will indicate to the resource server during TLS negotiation.
resource_servers:
- path: /example
connection_type: ssl
sni: www.test.com
Specifies the configuration information associated with the provision of identity information to the resource server.
| Type | Description |
|---|---|
| utf8_bin | Unencoded UTF-8 data. This setting allows data to be transmitted without data loss, and the user does not need to URI-decode the data. |
| utf8_uri | URI encoded UTF-8 data. All white space and non-ASCII bytes are encoded %XY, where X and Y are hex values (0-F). |
| lcp_bin | Unencoded local code page data. Data loss can potentially occur with this mode. Use with caution. |
| lcp_uri | URI encoded local code page data. Any UTF-8 characters that cannot be converted to a local code page are converted to question marks (?). |
Mode | Description
---- ---| -----------
filter | The Authorization header, if provided by the client, will be removed before the resource request is forwarded to the resource server. This is the default option if no option is specified.
supply | A new Authorization header will be created by the gateway and forwarded to the resource server. The Basic Authentication information contained in the header will consist of the name of the authenticated user, along with a static password. Use the password YAML configuration entry to set the static password.
ignore | The Authorization header, if provided by the client, will be forwarded to the resource server unchanged.
service | A new Authorization header will be constructed using a username and password retrieved from a configured credential service. See "services/credential" for more information about configuring a credential service. The YAML entries "service" and "resource_name" must be specified when using this mode.
resource_servers:
- path: /example
identity_headers:
encoding: utf8_uri
basic_auth:
mode: filter
ip_address: true
attributes:
- attribute: emailAddress
header: email_header
- attribute: AUTHENTICATION_LEVEL
header: auth_level
ltpa:
key: '@ltpa_keyfile'
key_password: passw0rd
version: 2
session_cookie: true
jwt:
certificate:
- '@jwt.crt'
- '@jwt.key'
hdr_name: jwt
claims:
- text: www.ibm.com
name: iss
- attr: AZN_CRED_PRINCIPAL_NAME
name: sub
- attr: AZN_*
- path: /ibmiis
connection_type: tcp
servers:
- host: test.ibm.com
port: 80
identity_headers:
kerberos:
resource_spn: HTTP/web.test.ibm.com@IBM.COM
always_send_tokens: true
user_identity:
username: '{preferred_username}'
Specifies the information associated with Kerberos tokens. Note that the instance level services/kerberos entry must be configured before enabling Kerberos tokens for any resource server.
The the service principal name of the target when requesting a Kerberos token. The service principal name can be determined by executing the Microsoft utility setspn (that is, setspn -L user, where user is the identity of the back-end web servers account).
Indicates whether IAG sends a security token for every HTTP request or whether IAG waits for a 401 response before it adds the security token.
Configures the UPN used by the gateway when performing Kerberos constrained delegation.
An administrator can overwrite the UPN or sections of the UPN for Kerberos constrained delegation users with this entry. The replacement information can be either plain text or names of credential attributes that store the required information. If you specify plain text, the text is directly copied into the UPN sections. If you specify names of credential attributes by surrounding the text with braces eg. {preferred_username}, the replacement text is fetched from the value of the corresponding credential attribute.
The realm to append to the client credential for Kerberos constrained delegation. The realm value must be uppercase. Any input data that is not uppercase is automatically converted to uppercase. The realm must also be added as a realm to the Kerberos configuration in the Services module.
The encoding type to use for any identity headers passed to the resource server. See the Encoding table for a description of the available options.
Controls the basic authentication information, contained within the Authorization header, that is passed to the resource server.
See the Basic Authentication Modes table for a description of the available modes.
Note that some modes require additional parameters:
- If the mode is service, the following entries must also be
provided:
- service
- resource_name
supply, the following entry must also bepasswordThe mode of handling the basic authentication headers.
If the mode entry is set to supply then the password must be provided here.
If the mode entry is set to service then the credential service name must be provided here.
Used only when mode is service. The name of the resource which will be passed to the credential service when retrieving the username/password.
A boolean flag indicating whether or not to provide the client IP address as a HTTP header in requests forwarded to the resource server. The IP address will be added in the iv-remote-address HTTP header.
A boolean flag indicating whether or not to provide an ASN.1 encoded version of the credential as a HTTP header in requests forwarded to the resource server. The credential will be added in the iv-creds HTTP header.
Specifies a list of attributes from the authenticated credential which will be inserted into the HTTP requests sent to the resource server.
No Additional ItemsThe name of the credential attribute.
The name of the HTTP header which will contain the credential attribute. If no name is supplied the name of the credential attribute itself will be used.
Specifies the information associated with the generation of JSON Web tokens (JWT).
PEM based personal certificate files which will be used to sign the JWT. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
No Additional ItemsThe name of the HTTP header which will contain the generated JWT.
The claims which are to be added to the JWT. The claim can either be obtained from a literal string, or from the value of a credential attribute.
No Additional ItemsThe name of the claim which is to be added to the JWT. If the name is not specified, and the claim value is obtained from an attribute name, the name of the claim will match the name of the attribute. Nested objects can be specified, separating the name of each object field with a . (dot). If the name of a field itself embeds a dot it should be escaped with a backslash character.
The literal text to be used as the claim value. If both a text value and an attr value is specified the text value will be used. If an array is supplied in the configuration the claim will be added to the JWT as a JSON array.
The type of textual data which is being provided. This will control the JSON type which is used in the JWT.
Controls whether or not this claim will always be added as an array type. If this value is not specified, any single value attributes will be added as single values and any multi-valued attributes as arrays.
The name of the credential attribute from which the claim value will be obtained. The * and ? pattern matching characters can be used to match multiple attributes, however the pattern matching characters will be ignored if a claim name is specified. If both a text value and an attr value is specified the text value will be used.
Specifies the information associated with the generation of an LTPA token.
The key which is used to protect the LTPA token. This key must be in the correct proprietary format for an LTPA key.
The password which is used to access the LTPA key.
The version of the LTPA token to create. Valid versions are 1 or 2, with a default of 1.
Value must be greater or equal to 1 and lesser or equal to 2
Specifies the configuration information associated with mutual authentication processing for the resource server.
resource_servers:
- path: /example
mutual_auth:
basic_auth:
username: admin
password: passw0rd
certificate_auth:
certificate:
- '@cert.crt'
- '@cert.key'
Specifies the configuration information associated with the basic authentication header which will be sent to the resource server.
The name of the user to be included in the basic authentication header.
The password of the user to be included in the basic authentication header.
Specifies the configuration information associated with the client certificate which will be sent to the resource server.
PEM based personal certificate files which will be used when communicating with the resource server. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
No Additional ItemsSpecifies the location of the resource server that is being protected. This is an array type and multiple resource servers can be specified.
No Additional ItemsThe name or IP address of the server.
The port on which the server is listening.
Value must be greater or equal to 0 and lesser or equal to 65535
If the resource server resides on a virtual host, this parameter can be used to specify the hostname which the reverse proxy should present in the host header for requests to this resource server. If this resource server definition is for a virtual host, this will be inherited from the resource server definition and should not be specified.
SSL settings for the server.
If required, a signer certificate required for the reverse proxy to trust the resource server can be specified here in PEM format.
No Additional ItemsThis option can be used to ensure that the resource server presents a specific certificate.
This entry defines how the resource server URLs are handled.
A boolean flag indicating whether or not URLs are case insensitive.
A boolean flag indicating whether or not to forbid requests to URLs that appear to be Windows style file name aliases. If this entry is set to true it will also enforce that URLs are case insensitive.
The priority group for this server. The load balancing algorithm in IAG will forward client requests to any currently available server with the highest priority.
Value must be greater or equal to 1 and lesser or equal to 9
The UUID for this server. The UUID of the server is used if this is a stateful resource server to ensure that client requests are always handled by the same server. This field is optional and will be automatically generated if not provided.
The UUID only needs to be manually set when multiple instances of IAG are handling the same stateful traffic. That is, so that each IAG instance is using the same UUIDs for the same servers.
resource_servers:
- path: /example
servers:
- host: www.test.com
port: 443
virtual_host: testportal.test.com
ssl:
certificate:
- '@www-test-com.crt'
server_dn: cn=test
url_style:
case_insensitive: true
windows: false
For virtual_host resource servers, the gateway selects the resource server for a request based on the HTTP host header contained within the request.
The 'aliases' option can be used to specify additional aliased host headers which will be matched to this virtual host resource server.
Multiple aliases can be specified for a resource server.
The format of the alias should be: <host>:<port>. Note that the port is required even if the default HTTP or HTTPS ports are used.
resource_servers:
- virtual_host: example.ibm.com
aliases:
- tcp.example.ibm.com:80
- tls.example.ibm.com:443
Specifies the configuration information used for performing form-based single sign-on to the protected application.
Login form fields can be populated with data from three possible sources, indicated by the source field:
| Source | Usage |
|---|---|
| service | Data from the credential service will be used to populate this field. |
| attribute | A credential attribute value will be used to populate the field. |
| static | A static string will be used to populate this field. |
Depending on the type of source used, the usage of the value can differ.
| Source | Usage |
|---|---|
| service | The field from the credential service data to use. This can be either username or password |
| attribute | The name of a credential attribute for which the value of will be used to populate this field. |
| static | A static string literal which will be used to populate this field. |
In the below example:
- Forms login will be attempted automatically on requests to the URL authenticate/login
- On the page, the HTML form with action="login.jsp" will be detected as the login form
- Credentials will be retrieved from the service named testCredentialService service provided in the services/credential YAML.
When requests are made to this service, the {resource} token will be substituted with jspApp.
- To complete the login, IAG will send a forms POST to the URL indicated by the HTML form, containing the fields:
- username, which is populated by the username retrieved from the credential service.
- password, which is populated by the decrypted version password of the password retrieved from the credential service.
- SSO_SOURCE which is a static field always containing the string IAG-SSO
- LOGIN_ORIGIN which is populated using the value of the credential attribute AZN_CRED_MECH_ID for the current user session.
- When IAG submits the forms-based login, it will consider a response from the application with a HTTP status code 302 and a location header matching "*/loginSuccess" to be a successful login.
- If the response does not look like a successful login, IAG will present the login form to the client.
- As credential learning is enabled, when IAG observes the client POST to /login.jsp, it will extract the username and password fields and store them with the credential service for future use.
resource_servers:
- path: /jspApp
forms_login:
credential_learning: true
login_resources:
- resource: authenticate/login
form_action: /login.jsp
service: testCredentialService
resource_name: jspApp
form_response_pattern: '*login_prompt*'
fields:
- name: username
source: service
value: username
- name: password
source: service
value: password
- name: SSO_SOURCE
source: static
value: IAG-SSO
- name: LOGIN_ORIGIN
source: credential
value: AZN_CRED_MECH_ID
response_rules:
- success: true
response_code: 302
headers:
- name: Location
value: '*/loginSuccessful'
A boolean flag indicating whether or not credential learning is enabled for this resource server. If credential learning is enabled, when IAG is unable to automatically complete the forms login but observes a successful manual login, the credentials used will be encrypted and stored in the credential service for future use.
This entry is a list of login resources which each contain configuration for each forms-based login page.
No Additional ItemsThis entry specifies a pattern that uniquely identifies requests for an application's login page.
The page will then be intercepted to begin the forms-login sign-on process. The pattern provided is compared to the request URI.
This entry specifies a pattern that identifies which form contained in the intercepted page is the login form. The matching is performed based on the action attribute of the HTML <form> node.
This optional entry specifies a pattern which is used to determine if the page contains the login form or not. If the page content does not include this pattern, it will be returned to the client. By default, the gateway will only examine the first 32,768 bytes of the response for the pattern. Because the pattern is checked against the entire cached response it will usually start and end with a '*'.
The name of the credential service which is used to store and retrieve credentials for this resource.
The resource name which will be used when making requests to the configured credential service.
This entry is a list of the form fields which are need to complete the form-based login.
No Additional ItemsThe name of the form field that will be populated.
The data source which will be used to populate this form field.
See the Login Form Field Types table for an explanation of the values.
This entry defines what information for the given source will be used to populate this form field.
See the Login Form Field Values table for an explanation of the values.
A list of rules which are used to determine if the forms-based was successful or not. These rules are evaluated in the order they are provided here.
No Additional ItemsA boolean to indicate whether this rule is used to detect a successful login or not.
true indicates a successful login, false indicates a failed login attempt.
The HTTP status code expected in the response for this rule.
The HTTP headers expected in the response.
No Additional ItemsThe name of the HTTP header to examine in the response.
HTTP header names are not case sensitive.
The expected value of the HTTP header.
Header values are case sensitive.
Specifies the configuration which is used to establish the health of the resource server.
resource_servers:
- path: /example
health:
ping:
method: HEAD
url: /
policy:
frequency: 600
threshold: 1
recovery:
frequency: 300
threshold: 1
timeout: 10
rule:
- -50?
- +*
rule:
- -50?
- +*
Specifies the configuration that allows the reverse proxy to periodically ping each resource server to determine whether it is running.
The HTTP method which will be used in the ping request.
The URL to which the ping request will be sent.
The policy associated with the ping requests.
The frequency (in seconds) which ping requests will be sent. If set to 0 the ping will be disabled.
Value must be greater or equal to 0 and lesser or equal to unlimited
Specifies how many consecutive times the ping must fail before the resource server is considered unhealthy.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies how long the reverse proxy should wait for responses to ping requests. A value of 0 will result in an indefinite wait. If not specified the timeout will default to the http or https timeout.
Value must be greater or equal to 0 and lesser or equal to unlimited
When the resource server is unhealthy, these entries specify how often they should be pinged and how many consecutive successful pings should be observed before the resource server is considered healthy again.
The frequency (in seconds) which ping requests will be sent. If this value is not set it will default to the value of the ping frequency.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies how many consecutive times the ping must fail before the resource server is considered unhealthy.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies how to interpret responses to ping requests. This entry is an ordered list of rules based on the response status codes. Status codes prefixed with a + are considered healthy, and codes prefixed with - unhealthy. The wildcard characters * and ? can be used.
Regular (client initiated) requests can also be observed to determine the resource server health. This entry is an ordered list of rules based on the response status codes. Status codes prefixed with a + are considered healthy, and codes prefixed with - unhealthy. The wildcard characters * and ? can be used.
Specifies the limits that can be set on the percentage of worker threads that may be consumed by this resource server.
resource_servers:
- path: /example
worker_threads:
soft_limit: 60
hard_limit: 80
Specifies the soft limit (as a percentage) of worker threads that the resource server can use. Warning messages will be displayed when the resource server uses more worker threads than allowed.
Value must be greater or equal to 0 and lesser or equal to 100
Specifies the hard limit (as a percentage) of worker threads that the resource server can use. Warning messages will be displayed when the resource server uses more worker threads than allowed and clients are returned the 503 Service Unavailable message.
Value must be greater or equal to 0 and lesser or equal to 100
Configures the pool of persistent connections which is maintained for the resource server. A persistent connection will allow an established connection to the resource server to be used for multiple requests.
resource_servers:
- path: /example
persistent_connections:
max_cache_size: 100
connection_timeout: 5
The maximum number of persistent connections which will be stored in the cache for future use. Connections with resource servers will be cached for future use unless the configured limit is reached, or the connection: close header is received in the HTTP response. Please note that if enabled there is the potential for different user sessions to use the same connection when processing requests. To disable the persistent connection functionality simply specify a value of 0.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum number of seconds a persistent connection can remain idle in the cache before the connection is cleaned up and closed by the IAG. This value should be lower than the configured maximum connection lifetime for the resource server. This behaviour is controlled for the Apache Web server, as an example only, by the KeepAliveTimeout configuration entry.
Value must be greater or equal to 0 and lesser or equal to unlimited
Defines any special identity provider information for this resource server.
resource_servers:
- path: /example
identity:
oauth: verify_introspection
The name of the OAuth introspection endpoint to use when accessing this resource server.
The policies node defines the configuration of path based policies for the IBM Application Gateway.
The gateway can transform inbound requests from clients before forwarding them to the application or outgoing responses from the application before returning them to the client. Refer to the documentation for information about how to author HTTP transformation rules XSL documents.
This node defines the transformations which will take place on requests. This entry is an array and can be used to specify multiple transformations.
No Additional ItemsThe name which is associated with this transformation.
The host (obtained from the host header in the request) for which this transformation will take place. If no host header is specified all hosts will be matched.
The paths for which this transformation will take place. If the wildcard "*" is specified all paths will be matched. This entry is an array and can be used to specify multiple paths.
No Additional ItemsThe HTTP method for which this transformation will take place. If the wildcard "*" is specified all methods will be matched.
The HTTP transformation rule.
policies:
http_transformations:
request:
- name: resource_1_rule
host: www.test.com
paths:
- '*'
method: GET
rule: '@http_trans_rule.lua'
This node defines the transformations which will take place on requests before authorization has been completed. This entry is an array and can be used to specify multiple transformations.
No Additional Itemspolicies:
http_transformations:
preazn:
- name: resource_1_preazn_rule
host: www.test.com
paths:
- '*'
method: GET
rule: '@http_trans_rule.lua'
This node defines the transformations which will take place on requests after authorization has been completed. This entry is an array and can be used to specify multiple transformations.
No Additional Itemspolicies:
http_transformations:
postazn:
- name: resource_1_postazn_rule
host: www.test.com
paths:
- '*'
method: GET
rule: '@http_trans_rule.lua'
This node defines the transformations which will take place on requests after authentication has been completed. This entry is an array and can be used to specify multiple transformations.
No Additional ItemsThe name which is associated with this transformation.
The host (obtained from the host header in the request) for which this transformation will take place. If no host header is specified all hosts will be matched.
The authentication mechanisms for which this transformation should be triggered.
The name of the authentication mechanism is located within the AZNCREDAUTH_METHOD attribute of an authenticated credential.
The HTTP transformation rule.
policies:
http_transformations:
postauthn:
- name: resource_1_postauthn_rule
host: www.test.com
authentication_mechanisms:
- oidc
rule: '@http_trans_rule.lua'
This node defines the transformations which will take place on responses. This entry is an array and can be used to specify multiple transformations.
No Additional Itemspolicies:
http_transformations:
response:
- name: resource_1_rule
host: www.test.com
paths:
- /resource_1
- /alt/resource_1
method: GET
rule: '@http_trans_rule.lua'
- name: legacy_xslt_rule
host: www.test.com
paths:
- /legacy
method: GET
rule: '@legacy_rule.xsl'
attributes:
- AZN_CRED_PRINCIPAL_NAME
This node contains secrets which can be loaded in Lua HTTP Transformation rules.
The secret values can be loaded using the Control.getConfig method, passing a nil value for the first parameter and the secret name for the second parameter.
For example, the following Lua snippet loads the value of a secret named "serviceApiKey":
value = Control.getConfig(nil, "serviceApiKey")
Name of the secret. This is the name which can be used when loading the secret data.
The content of the secret.
policies:
http_transformations:
secrets:
- name: serviceApiKey
value: $SERVICE_API_KEY
- name: serviceApiEndpoint
value: https://api.myservice.ibm.com/v1
The reverse proxy can support cross-origin resource sharing with CORS aware clients.
Each defined policy must at a minimum contain:
* name
* method
* policy:allow_origins
This entry is an array and can be used to specify multiple CORS policies.
The name which is associated with this CORS policy.
The host (obtained from the host header in the request) for which this CORS policy will be applied. If no host header is specified all hosts will be matched.
The paths for which this CORS policy will be applied. This entry is an array and can be used to specify multiple paths.
No Additional ItemsThe HTTP method for which this CORS policy will be applied.
The definition of the CORS policy.
A list of origins which are permitted to make cross-origin requests. To allow cross-origin requests from any origin, add a single entry *.
The reverse proxy can respond to pre-flight requests using the information from this policy. If set to false, pre-flight requests will be forwarded to the protected application.
Headers that are indicated as allowed in responses to pre-flight requests. Specifying no allowheader entries will indicate to clients that all headers are permitted. Not case-sensitive. Only valid if handlepre_flight is set to true.
No Additional ItemsMaximum time (in seconds) a client should cache the results of a pre-flight request. A value of -1 indicates to clients that they should not cache, 0 indicates that clients may cache at their own discretion. Only valid if handlepreflight is set to true.
Value must be greater or equal to -1 and lesser or equal to unlimited
Methods that are indicated as allowed in responses to pre-flight requests. Specifying no allowmethod entries will indicate to clients that all methods are permitted. Case-sensitive. Only valid if handlepre_flight is set to true.
No Additional ItemsIndicates to clients that authentication is required when accessing this resource.
Indicates to clients which headers they expose from the response.
No Additional Itemspolicies:
cors:
- name: cors_policy_A
host: www.test.com
paths:
- /test
- /development
method: GET
policy:
allow_origins:
- www.test.com
- www.example.com
handle_pre_flight: true
allow_headers:
- test_header
- test_header2
max_age: 600
allow_methods:
- update
- create
allow_credentials: true
expose_headers:
- test_header
- test_header2
The gateway can apply rate limiting to incoming requests. This entry defines the rate limiting policies and where they will be applied. Refer to the documentation for information about how to author a rate-limiting policy.
This entry is an array and can be used to define multiple policies.
The name to be associated with this rate limiting rule.
The methods to which this rate limiting rule will be applied. If the wildcard "*" is specified all methods will be matched.
No Additional ItemsThe paths to which this rate limiting rule will be applied. The path supports wildcards. This entry is an array and can be used to specify multiple paths. Note that the policy will be duplicated and applied for each specified path, multiple paths do not share a common request bucket. To share a common request bucket for multiple paths, provide a single path pattern which matches all required paths.
No Additional ItemsThe rate limiting rule.
policies:
rate_limiting:
- name: rate_policy_A
methods:
- GET
- POST
paths:
- /test*
- /release*
rule: 'ip: true
capacity: 3
interval: 60
reaction: TEMPLATE
'
The gateway can inject content into responses. This entry defines the content and when injection should take place. Content injection is performed based on the request path and a specific location within the response.
This entry is an array and can define multiple content injection points.
A name to be associated with this content injection rule.
The path for which content injection will take place. This entry is an array and can be used to specify multiple paths.
No Additional ItemsShould the location match a full line, or should it match any string in the response? When a full line match is configured the content will be inserted prior to the matching line. When a partial line match is configured the content will be inserted immediately prior to the matching string.
The location where the content should be injected. If a full line match is being used the location is pattern matched against a line in the response using the *. wildcard characters. The maximum length of a line which can be matched is 8192 bytes.
If a partial line match is being used this configuration entry will control whether the matching string is replaced with the supplied content, or whether the supplied content is inserted prior to the matching string. This configuration entry will be ignored if full line matches are being used.
The data which is to be injected.
policies:
content_injection:
- name: content_injection_1
paths:
- /test
- /test2
location: <h3>*
content: '<hr/>
<h4>Add heading4 after heading3</h4>
<hr/>
'
The gateway can act as a Web Application Firewall using the ModSecurity engine.
The Web Application Firewall policy must at a minimum contain:
* configuration
* rules
If there are no request_match entries defined, the WAF will only be active when the Control.triggerWAF function has been called from within a Lua HTTP Transformation.
policies:
waf:
configuration:
content: wafConfigDir
type: path
rules:
content: '@wafRules.zip'
type: zip
request_match:
- method: GET
path: /index.html
version: HTTP/1.1
- method: GET
path: /jct/*
- method: GET
path: /login/*
phases:
request_headers: true
request_body: true
response_headers: false
response_body: false
logging: true
Defines configuration files for the ModSecurity engine. This entry must be either a zip file or a path which is relative to the /var/iag/config directory of the container. The specified location must contain at least one file, named modsecurity.conf. The modsecurity.conf configuration will be applied first, other configuration files (with the .conf suffix) will be applied in alphabetical order.
The content which will be used for configuring the ModSecurity engine.
The type of content which is being supplied. Either a zip file or a directory name.
Defines the rule files for the ModSecurity engine. This entry must be either a zip file or a path which is relative to the /var/iag/config directory of the container. The specified location must contain at least one file. Files with a .conf suffix will be treated as configuration files, other files will be treated as data files.
The content which will be used as rules for the ModSecurity engine.
The type of content which is being supplied. Either a zip file or a directory name.
This entry defines a list of request matches for which the Web Application Firewall will be run.
Each defined request match must contain at least:
* method
* path
The HTTP method for which this match should be triggered. This value can include the wildcard * character to match multiple methods.
The HTTP path for which this match should be triggered. This value can include the wildcard * character to match multiple paths.
The HTTP version string for which this match should be triggered. This value can include the wildcard * character to match multiple versions.
The phases of the request cycle for which this match should be triggered. The default is to trigger at each phase of the request cycle.
Whether or not to run the WAF rules after the HTTP request headers have been received.
Whether or not to run the WAF rules after the HTTP request body has been received.
Whether or not to run the WAF rules after the HTTP response headers have been received.
Whether or not to run the WAF rules after the HTTP response body has been received.
Whether or not to run the WAF rules during the logging phase.
The services node defines services within the Application Gateway configuration.
This configuration is used to describe an external credential service which IAG can use to retrieve credentials for use in single sign-on to protected applications.
Each credential service must contain:
* name
* enckey
* host
* urlpattern
* user_attribute
This entry is an array and can be used to specify multiple credential services.
The name which is associated with this credential service.
The hostname of the endpoint where the credentials will be retrieved from.
The port of the endpoint where the credentials will be retrieved from.
The proxy server which will be used when connecting to the credential service. The configuration entry should be of the form: <server>:<port>
The path of the endpoint where the credentials will be retrieved from. This must contain the {user} and {resource} macros. When communicating with the credential service, IAG will substitute {resource} for the resource name provided in the configuration which refers to this credential service.
The name of the credential attribute which is used to populate the {user} macro in the URL used when communicating with the credential service.
The type of encoding to perform on the user_attribute for inclusion in the URL to communicate with the credential service.
- If this value is url, the user attribute value will be URL Encoded.
- If this value is base64url, the user attribute value will be converted to lower case and Base64 Encoded for URL.
The key which will be used to encrypt and decrypt credential data. This key should be an RSA or ECDSA key for which the private and public parts are available.
SSL settings for the credential service connection.
PEM based personal certificate files which will be used when communicating with the resource server. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
No Additional ItemsSpecifies the accepted DN of the certificate presented by the credential service. If this entry is empty, any DN will be accepted.
The server name (SNI) which will be indicated when establishing a connection to the credential service. If this entry is empty, no name will be indicated.
Controls how IAG will authenticate itself when communicating with the credential service. Only one of the following may be used at any time.
Uses the OAuth client credential flow to retrieve an access token to use when communicating with to the credential service.
The endpoint which will be called to obtain an access token which is used in requests to the credential service.
The endpoint should conform to the OAuth client credential flow (OAuth 2.0 RFC 6749, section 4.4).
The client identifier to use during the OAuth client credential flow.
The client identifier to use during the OAuth client credential flow.
Specifies how the client id and secret will be posted to the authentication endpoint.
- If this value is form, the client id and secret will be included in forms POST data.
- If this value is basic, a basic authentication header will be constructed using the client id and secret.
Uses an access token presented in the authorization header as a bearer token when communicating with the credential service.
The literal access token that will be passed as a bearer token.
Alternatively, if surrounded by {}, this field can name a credential attribute for which the value of will be used as a bearer token.
Uses basic authentication when communicating with the credential service.
The username to be used to perform basic authentication to the credential service.
The password to be used to perform basic authentication to the credential service.
services:
credential:
- name: myCredService
enc_key: '@vault-rsa.pem'
host: ibm_app_gw.ice.ibmcloud.com
proxy: proxy.ibm.com:3128
url_pattern: /v1.0/pwdvault/{user}/resources/{resource}
ssl:
certificate:
- '@vault-ibm-com.crt'
server_dn: cn=vault
sni: vault.verify.ibm.com
user_attribute: AZN_PRINCIPAL_ID
user_attribute_encoding: url
authentication:
sso:
client_id: 36bxxxx-xxxx-xxxx-xxxx-xxxxxxxxxae5
client_secret: ctZxxxxqQs
endpoint: https://ibm_app_gw.ice.ibmcloud.com/v1.0/endpoint/default/token
payload: form
This configuration is used to describe a Kerberos configuration file which IAG can use to perform Kerberos Constrained Delegation as a means of authentication to a protected application.
The Kerberos service must contain:
* keytab
* keytab_spn
* realms
* libdefaults
keytab_spn and keytab must correspond to the service principal name and generated key table for a user which IAG will authenticate itself as. This user must have permission to perform delegated authentication.
This entry is an object and can be used to specify a single kerberos service.
services:
kerberos:
keytab: '@ibm-app-gateway.keytab'
keytab_spn: HTTP/ibm-app-gateway@IBM.COM
realms:
- name: IBM.COM
kdc: ibm.com
libdefaults:
properties:
- name: default_tgs_enctypes
value: rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts
- name: default_tkt_enctypes
value: rc4-hmac des-cbc-md5 des-cbc-crc aes256-cts
The Kerberos key table file which IAG will use to authenticate with the server.
The service principal name of the impersonating user when creating a Kerberos token. The service principal name can be determined by executing the Microsoft utility setspn (that is, setspn -L user, where user is the identity of the IAG account).
Realm-specific contact information and settings associated with the Microsoft Windows Server to use for performing Kerberos impersonation.
No Additional ItemsThe name of the Kerberos Realm being configured.
The name or address of a host running a KDC for that realm. An optional port number, separated from the hostname by a colon, may be included.
Advanced additional properties to be added to the Realm configuration. These properties correspond to the properties in the [realms] <realm name> section of krb5.conf.
No Additional ItemsName of the entry to be written into the realms section of the Kerberos configuration.
Value of the entry to be written into the realms section of the Kerberos configuration.
The hostname for this realm.
Advanced additional properties to be added to the Kerberos library configuration. These properties correspond to the properties in the [libdefaults] section of krb5.conf.
The properties to be added to the Kerberos libdefaults configuration. Each entry consists of a name and a value.
No Additional ItemsName of the entry to be written into the libdefaults section of the Kerberos configuration.
Value of the entry to be written into the libdefaults section of the Kerberos configuration.
Authentication paths for non-hierarchical cross-realm.
No Additional ItemsThe client realm for this authentication path.
The realms associated with this capath.
No Additional ItemsThe server realm for this capath.
The inter realm for this capath.
Used to define the global configuration and server collections for Redis.
services:
redis:
default_collection: redis-a
key_prefix: iag-test-
collections:
- connect_timeout: 20
cross_domain_support:
master_authn_server_url: https://mas.ibm.com
master_session_code_lifetime: 150
health_check_interval: 200
idle_timeout: 100
io_timeout: 300
matching_host: www.webseal.ibm.com
max_pooled_connections: 200
name: test-collection-session
servers:
- host: redis-a.ibm.com
name: redis-a
password: passw0rd
username: testuser
port: 6380
ssl:
client_certificate: '@redis-a-client.pem'
sni: redis-a.ibm.com
trust_certificates: '@redis-a-ca.pem'
- connect_timeout: 10
health_check_interval: 200
idle_timeout: 100
io_timeout: 300
max_pooled_connections: 200
name: test-collection-ratelimiting
servers:
- host: redis-b.ibm.com
name: redis-b
password: passw0rd
username: user
port: 6380
ssl:
trust_certificates: '@redis-b-ca.pem'
The key prefix for all data which is stored on the Redis server.
The name of the default collection of Redis servers to be used.
Used to define the configuration for a collection of replicated Redis servers.
No Additional ItemsThe name of the redis collection.
Any specific hosts (obtained from the Host header of the HTTP request) for which this collection should be used.
This entry is only applicable to Redis collections being used for storing session data.
The maximum number of pooled connections to a Redis server.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum number of seconds a pooled connection can remain idle before the connection is closed.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum number of seconds to wait for a connection to be established with a Redis server.
Value must be greater or equal to 0 and lesser or equal to unlimited
The maximum number of seconds to wait for a valid response from a Redis server.
Value must be greater or equal to 0 and lesser or equal to unlimited
The interval (in seconds) between health check requests sent to the Redis server.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies the configuration information associated with the sharing of sessions across multiple DNS domains.
These entries are only applicable to Redis collections being used for storing session data.
The base URL of the master authentication server for this collection of Redis servers. The master authentication server, if specified, will be responsible for the generation of all new sessions for this collection. The entry should be of the format: http{s}://server{:port}.
The maximum number of seconds that a session code, used when communicating the session information from the master authentication server, will remain valid.
Value must be greater or equal to 1 and lesser or equal to unlimited
Used to define the configuration for the individual Redis servers within the collection.
No Additional ItemsA label, or name, which is used to identify this server.
The server name or IP address of the Redis server.
The port on which the Redis server is listening for requests.
Value must be greater or equal to 1 and lesser or equal to unlimited
The name of the user which is used when authenticating to the Redis server.
The password which is used to access the Redis server.
The SSL information associated with the Redis server.
The PEM based certificates which are to be trusted when communicating with the Redis server. The trusted certificates should include the CA certificate for the Redis server certificate, as well as any intermediate certificates used to sign the client certificate (if mutual authentication is in use). SSL/TLS will not be used when communicating with the Redis server if no trust certificates are specified.
No Additional ItemsThe PEM based personal certificate files which will be used when performing mutual authentication with the resource server. These certificate files should include the private key, a certificate signed with the private key, and the signer certificate or signer certificate chain (if required).
No Additional ItemsThe Server Name Indication (SNI) value which is provided when establishing the SSL connection with the Redis server.
The logging node defines the configuration entries which are used to manage the various logging capabilities of the IBM Application Gateway.
Specifies the language in which the log messages will be displayed. The LANG environment variable, if set, will take precedence over this configuration entry. The following languages are supported:
Language Code | Language ------------- | -------- cs | Czech de | German en | English es | Spanish fr | French hu | Hungarian it | Italian ja | Japanese ko | Korean pl | Polish pt | Brazilian Portuguese ru | Russian zhCN | Chinese (Simplified) zhTW | Chinese (Traditional)
logging:
language: de
A boolean which indicates whether the logging will be in JSON format or not. If not specified logging will not be in JSON format.
logging:
json_logging: true
Specifies an array of auditing components to be enabled.
No Additional ItemsThe name of the auditing component(s).
logging:
components:
- audit.authn
- audit.azn
Defines and enables request logging.
The following directives can be added to the format property to customize the log format:
| Directive | Description |
|---|---|
| %a | Client IP Address. |
| %A | Local IP Address. |
| %b | Bytes in the response excluding HTTP headers in CLF format: - instead of 0 when no bytes are returned. |
| %B | Bytes in the response excluding HTTP headers. |
| %{attribute}C | Attribute from the credential named attribute. |
| %{cookie}e | Contents of the Cookie cookie in the request. |
| %{cookie}E | Contents of the Cookie cookie in the response. |
| %d | Transaction identifier, or session sequence number. |
| %F | Time taken to serve the request in microseconds. |
| %h | Client host. |
| %H | Request protocol. |
| %{header}i | Contents of the Header header in the request. |
| %j | The name of the resource server servicing the request. |
| %J | The length of time, in microseconds, that the resource server server spent processing the request. This will include the time that it took to send the request to the server, the length of time that it took the server to process the request, and the length of time that it took to read and process the response header. |
| %l | Client logname (RFC 1314) (default -). |
| %m | Request method (i.e. GET, POST, HEAD). |
| %{header}o | Contents of the Header header in the response. |
| %M | The time, in Common Log Format, at which the request was received with millisecond precision. |
| %p | Port over which the request was received. |
| %q | The decoded query string (prepended with ? or empty). |
| %Q | The raw query string (prepended with ? or empty). |
| %r | First line of the request with decoded URL. |
| %R | First line of the request with decoded URL including HTTP://HOSTNAME. |
| %s | Response status. |
| %S | The hostname of the backend server which serviced this request. |
| %t | Time in Common Log Format format. |
| %{format}t | The time in the given format. |
| %T | Time taken to serve the request in seconds, or part thereof. |
| %u | Remote user. |
| %U | The URL requested. |
| %v | Canonical ServerName of the server servicing the request. |
| %z | The decoded path string. |
| %Z | The raw path string. |
logging:
request_log:
file:
file_name: request.log
format: '%t %a %R'
By default the request log events will be written to the console of the container. By setting the file configuration the request log events can instead be written to a local file.
The name of the generated log file. If the file name is supplied without any path information the file will be written to the /var/iag/logs directory. If the file name contains path information the hosting directory must be created and available before the container is started.
The maximum size (in MB) that the file can reach before it is rolled over.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum number of rollover files to be kept on disk. When the number of rollover log files reaches the specified threshold, the oldest log file is deleted.
Value must be greater or equal to 1 and lesser or equal to unlimited
A boolean which indicates whether rolled over log files should be automatically compressed to conserve disk space.
The format of the events written to the request log. See the Log Format table above for the available directives.
Specifies an array of trace components to be enabled. Tracing can be used to assist with problem determination in the environment.
No Additional ItemsThe name of the tracing component to be enabled. Refer to the troubleshooting documentation for the full list of component names.
The name of the generated log file. If the file name is supplied without any path information the file will be written to the /var/iag/logs directory. If the file name contains path information the hosting directory must be created and available before the container is started.
The level of detail to be gathered by the tracing component in the range 0 to 9. Level 1 specifies the least detailed output and level 9 specifies the most detailed output. Level 0 will disable tracing for the component.
Value must be greater or equal to 0 and lesser or equal to 9
The maximum size (in MB) that the file can reach before it is rolled over.
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum number of rollover files to be kept on disk. When the number of rollover log files reaches the specified threshold, the oldest log file is deleted.
Value must be greater or equal to 1 and lesser or equal to unlimited
A boolean which indicates whether rolled over log files should be automatically compressed to conserve disk space.
logging:
tracing:
- file_name: http_trans.log
component: pdweb.http.transformation
level: 9
- file_name: http.log
component: pdweb.http
level: 5
max_file_size: 12
max_rollover_files: 10
compress: true
Defines and enables transaction logging. This logging can be used to pinpoint performance issues in the environment.
logging:
transaction:
file_name: trans.log
max_file_size: 1024
max_files: 5
compress: true
The name of the generated log file. If the file name is supplied without any path information the file will be written to the /var/iag/logs directory. If the file name contains path information the hosting directory must be created and available before the container is started.
The maximum size of the log file (in kilobytes) before it is rolled over. If not specified the file size is 262144 KB (256MB).
Value must be greater or equal to 1 and lesser or equal to unlimited
The maximum number of files to be created, including rollover files. If not specified the max number of files is unlimited.
Value must be greater or equal to 1 and lesser or equal to unlimited
A boolean which indicates whether the generated file should be compressed. If not specified the files will not be compressed.
Configures the statistic collection and publishing capability for the gateway. The statistics for the configured components will be published to the specified statsd server over UDP. Statistics can be used to monitor the environment, or assist with problem determination in the environment.
logging:
statistics:
server: 127.0.0.1
port: 8125
frequency: 20
components:
- iag.authn
The server on which the statsd server is listening for requests.
The port on which the statsd server is listening for requests.
Value must be greater or equal to 0 and lesser or equal to 65535
The frequency (in seconds) that statistics are sent from the memory buffer to the statsd server.
Value must be greater or equal to 1 and lesser or equal to unlimited
Specifies an array of statistic components to be enabled. Refer to the troubleshooting documentation for a full description of the available component names.
The advanced node defines advanced daemon tuning parameters.
This entry defines customize legacy reverse proxy daemon configuration entries. This configuration is applied last and can be used to overload parameters specified in other sections of the configuration YAML.
This entry is an array and can be used to specify multiple tuning parameters.
The name of the configuration stanza which contains the configuration entry.
The name of the configuration entry.
The operation to be perform on the configuration entry.
The value(s) for the new configuration entry. The value is only required for the add and set operations.
advanced:
configuration:
- stanza: server
entry: web-http-port
operation: set
value:
- '80'
- stanza: server
entry: web-https-port
operation: set
value:
- '443'