IBM Application Gateway Configuration Specification (OpenAPI)

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](https://www.haproxy.com/blog/haproxy/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 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.

Specifies the secure configuration for the gateway server.

Specifies the configuration related to failover support for the IBM Application Gateway.

Specifies the configuration for client sessions.

Specifies the configuration for WebSocket support.

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.
#### Defaults
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.

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

<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

<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 |
| temp_cache_response |

#### response_code

<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

<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.

#### Examples

For example, to customise:

- the ratelimit management response
- for English language
- to return HTTP status 500
- for clients expecting text/html

Create the following file in the zip file of management response pages:

C/ratelimit.500.html

#### Defaults

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.

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

<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

<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

<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

<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.

#### Examples

For example, to customise:

- the forbidden error response (error code 38cf0427)
- for Korean language
- to return HTTP status 500
- for clients expecting application/json

Create the following file in the zip file of error response pages:

ko/38cf0427.500.json

#### Defaults

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.

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.

#### Defaults

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).

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 codes

| 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 |

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.

Specifies the configuration for any embedded applications.

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.

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.

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".

These entries can be used to override the default post authentication URL which clients will be redirected to once they have successfully authenticated.

The 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.

Attributes Format
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.

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.

The configuration entries in this section allow the reverse proxy to act as an OIDC relying party to IBM Security Verify.

Notice of Deprecation

This identity module is no longer preferred and will be removed in a future version. Use the [OIDC](../../yaml-identity/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
      # ...

Response Type Values
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.

Bearer Token Attrs Format
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 "-access_token" indicates that the access_token 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.

ID Token Attrs Format
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.

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.

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 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 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.

The gateway can apply authorization rules to incoming requests. This entry defines a list of matching requests, rules and actions to perform if matches are found. The rules can be either:
* Defined directly here in an entry.
* Defined in the authorization section and reference by name here in an entry.

This entry defines authorization rules directly. There are also two pre-defined rules which can be used:
* "anyuser" : Which allows access to any user, even if they are not authenticated.
* "anyauth" : Which allows access to any authenticated user.

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.

The gateway can apply authorization rules to incoming requests. These rules can be either:
* Defined directly in a policies:authorization entry.
* Defined here in the authorization section and reference by name in a policies:authorization entry.

This entry defines authorization rules which can be referred to by name in a policies/authorization entry.

This entry is an array and can be used to specify multiple rules.

Rule Format

Authorization rules are composed of credential attributes and the following operators:

Name | Values
---- | ------
logical operators | and, or, not
multi-valued operators | any, all
relational operators | =, !=, matches, >, >=, <, <=, exists

Parenthesis can be used for controlling the order of evaluation.

Examples:

Rule | Description
---- | -----------
(any groupIds = "administrator") | Match when the user is in the administrator group.
(all authenticationLevels >= "2") | Match when all credential authenticationLevels are at least level 2.
(attribute_a matches "a(?:bc)*") | Match when the value of the credential attribute "attribute_a" matches the regular expression.
(level >= "2") and (any groupIds = "forbidden") | Match when the credential attribute "level" is at least level 2 and the user is in the forbidden group.
(not exists attribute_c) | Match when the credential does not have an attribute named "attribute_c".
(AZN_CRED_PRINCIPAL_NAME = "user_a") | Match when the credential attribute "AZN_CRED_PRINCIPAL_NAME" is equal to "user_a".

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
* enc_key
* host
* url_pattern
* user_attribute

This entry is an array and can be used to specify multiple credential services.

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.

Used to define the global configuration and server collections for Redis.

Specifies an array of auditing components to be enabled.

Defines and enables request logging.

Log Format
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.

Specifies an array of trace components to be enabled. Tracing can be used to assist with problem determination in the environment.

Defines and enables transaction logging. This logging can be used to pinpoint performance issues in the environment.

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.

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.