Custom Pages
The IBM Application Gateway (IAG) under certain conditions will return server generated responses. These conditions include scenarios such as error conditions or server generated operations.

By default, IAG includes a set of unbranded responses which will be served. A copy of the default responses are can be retrieved from the pages directory of the IAG Resources repository.
Pages | Description |
---|---|
management_pages.zip | This zip file contains a directory structure including the default management responses. |
error_pages.zip | This zip file contains a directory structure including the default error message responses. |
public_assets.zip | This zip file contains a directory structure including the default JavaScript and CSS assets references in the default error and management pages. |
Replacing the default Response Pages
Server generated responses can be customized by providing a set of response templates in the directory structure expected by IAG. The content can either be provided as a zip archive or a directory which is bind mounted into the IAG container.
For example, to replace the default error responses with the content of an archive errorPages.zip
which is mounted in the container at /var/iag/config/errorPages.zip
:
server:
error_pages:
content: "@errorPages.zip"
type: zip
See also: YAML Reference for error_pages
For example, to replace the default management responses with the content of the directory myMgmtPages
which is mounted in the container at /var/iag/config/myMgmtPages
:
server:
management_pages:
content: myMgmtPages
type: path
See also: YAML Reference for management_pages
Note that if custom responses are provided, IAG will not use any responses from the default set of responses. That is, if a custom set of responses is provided it is expected to include all possible responses you wish for IAG to serve. For this reason, the strategy recommended when customizing responses is to begin with the archive of default responses and make additions/omissions as required.
Directory Structure and Naming Convention for Management and Error Responses
The template content for Management and Error responses is expected in a specific directory structure adhering to the following name convention.
Note
Note that the token
<response_code>
is optional for both management and error pages.
Management Pages
<language_code>/<page_name>.<response_code>.<mime_type>
Example
./C/help.html
./C/login_success.html
./C/logout.html
./C/oidc_fragment.html
./C/ratelimit.html
./C/redirect.html
./C/temp_cache_response.html
./cs/help.html
./cs/login_success.html
...
Error Pages
<language_code>/<error_code>.<response_code>.<mime_type>
Example
./C/38cf0420.html
./C/38cf0421.html
./C/38cf0427.html
./C/38cf0428.html
./C/38cf04c6.html
./C/38cf04d7.html
./C/38cf08cc.html
./C/default.400.html
./cs/38cf0420.html
./cs/38cf0421.html
...
Controlling Language Support with language_code
language_code
The default set of responses are provided in 14 different languages. When creating the directory structure, directories for languages you do not wish to serve can be omitted.
IAG will select the language for the response using the following logic:
- If a client indicates a particular language and a response exists for that language, it will be served.
- If a client indicates a particular language and a response does not exist for that language, IAG will select a response using the container language (set via the
LANG
environment variable)
The complete list of languages supported by IAG and their corresponding language_code
values are listed below.
language_code | Language |
---|---|
C | English |
cs | Czech |
de | German |
es | Spanish |
fr | French |
hu | Hungarian |
it | Italian |
ja | Japanese |
ko | Korean |
pl | Polish |
pt | Brazilian Portuguese |
ru | Russian |
zh_CN | Chinese (Simplified) |
zh_TW | Chinese (Traditional) |
Example
Consider a scenario where your application is being deployed for Canadian users and you want to only ever return English or French server generated responses.
To only ever return responses in English or French with all other languages falling back to English:
- Include only the
C
andfr
directories in the directory structures for your management and error responses - Run the container with
LANG=C
to indicate that English is the default language
Controlling the Language of Translated Messages
From version 22.07 onwards, the default pages are provided only for the C
locale and the messages are populated using macros.
Even though the provided set of pages are C
(English language) locale, IAG will still substitute the text macros with messages in the client's locale. To control this behavior, use the server/enabled_languages
option.
For example, to only provide messages in English and French, use the following configuration:
server:
enabled_languages:
- C
- fr
Note that for all clients which do not match C
or fr
, they will fall back to C
as the first language specified is used as the default.
See also: YAML Reference for enabled_languages
Customizing HTTP Status Codes with response_code
response_code
The HTTP status code returned for management and error responses can be customized on a per-response template basis. This token of the filename in the naming conventions is optional, if a response_code
is not explicitly indicated, the default value will be used.
Management Responses
The default HTTP status code for management responses is 200.
Error Responses
The default HTTP status codes for error responses vary based on the type of error. The default status codes for the standard set of error responses are:
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 |
Customizing Responses for Different Types of Clients with mime_type
mime_type
IAG can serve different responses based on the MIME sub-type found in the request.
For example:
- A web browser which presents an
accept: text/html
header will receive thehtml
response - An API client presenting
accept: application/json
will receive ajson
response - provided that ajson
response template exists in the directory structure.
IAG uses the following logic to determine the appropriate type of response to return:
- The MIME sub-type in the
accept
HTTP header of the request is inspected.
IAG uses the first MIME entry that is found in the ‘accept’ header, disregarding
any specified quality factor and any subsequent MIME types. - If the ‘accept’ HTTP header is not present, the MIME sub-type from the
‘content-type’ HTTP header in the request is used. - If none of the above correspond to a response template file, the default
(html) is selected.
Example
For example, consider an environment with the following error responses:
C/38cf0428.404.html
C/38cf0428.400.json
Three different clients make a request for a resource which does not exist, this would result in the error_code 38cf0428
.
Web browser client
GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
accept: text/html
content-type: text/html; charset=UTF-8
user-agent: mozilla/5.0 ...
In this case, the accept
header is present and contains the mime sub-type html
.
IAG will serve C/38cf0428.404.html
to the client with a HTTP status code 404.
API client
PUT /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
content-type: application/json; charset=UTF-8
user-agent: mobile-app-demo/1.3
In this case, the accept
header is not present, but a content-type
header is and contains the mime sub-type json
.
IAG will serve C/38cf0428.400.json
to the client with a HTTP status code 400.
Other client
GET /unknownResource HTTP/1.1
host: demo.ibm-app-gw.com
user-agent: curl/7.64.1
accept: */*
In this case, both the accept
and content-type
headers do not contain a meaningful mime sub-type, so IAG will fall back to the html
page.
IAG will serve C/38cf0428.404.html
to the client with a HTTP status code 404.
Management Pages page_name
page_name
IAG provides default HTML responses for all management pages.
A complete list of the possible page_name
values and details about the provided default responses is below:
page_name | response_code | mime_type |
---|---|---|
help | 200 (default) | html |
login_success | 200 (default) | html |
logout | 200 (default) | html |
oidc_fragment | 200 (default) | html |
ratelimit | 200 (default) | html |
redirect | 200 (default) | html |
temp_cache_response | 200 (default) | html |
Error Pages error_code
error_code
IAG provides HTML responses for common error_code
values and a HTML and JSON default
error response:
error_code | response_code | Description | mime_type |
---|---|---|---|
38cf0420 | 301 (default) | Moved Permanently | html |
38cf0421 | 302 (default) | Moved Temporarily | html |
38cf0427 | 403 (default) | Forbidden | html |
38cf0428 | 404 (default) | Not Found | html |
38cf04c6 | 500 (default) | Server Not Responding | html |
38cf04d7 | 500 (default) | Server Not Responding | html |
38cf08cc | 403 (default) | Forbidden (Time based) | html |
default | 400 | Any other error code | html |
default | 400 | Any other error code | json |
The error_code
default
indicates a template that will be selected for any error_code
which does not have an explicitly defined response template.
Responses can be added for error_code
values not listed in the default set of responses. To customize the response for an error_code
not present in the default set of responses, simply create a new response file following the naming convention and including the actual error_code
in the filename.
Response Macros
Contextual data can be inserted into response templates using the following macros. These macros can be used regardless of the mime sub-type.
Macro | Example | Description |
---|---|---|
%BACK_URL% | https://demo.ibm.com | Substitutes the value of the referer header from the request, or "/" if none. |
%CREDATTR{name}% | %CREDATTR{UID}% == 502HB8S9Q1 | The value of the user credential attribute that has the specified name . |
%ERROR_CODE% | 0x38cf0421 | The numeric value of the error code. |
%ERROR_TEXT% | Moved Temporarily | The text associated with an error code in the message catalog. |
%HOSTNAME% | ibm-app-gw.ibm.com | Fully qualified host name. |
%HTTPHDR{header}% | %HTTPHEADER{HOST}% == ibm-app-gw.ibm.com | Used to include the contents of a specified HTTP header. If the specified HTTP header does not exist within the request, the macro will contain the text: Unknown . |
%HTTPS_BASE% | https://ibm-app-gw.ibm.com:8443 | Base HTTPS URL of the server, "https://host:port/". |
%LOCATION% | https://ibm-app-gateway/application1/ | Contains the URL to which the client is being redirected. Sent only in redirects. |
%METHOD% | GET | The HTTP method requested by the client. |
%PKMSPUBLIC% | /pkmspublic | The path segment where IAG is serving the public assets from. |
%REFERER% | https://demo.ibm.com/dispatch?foo=bar | The value of the HTTP referer header from the request, or Unknown , if none. |
%REFERER_ENCODED% | https://demo.ibm.com/dispatch%3Ffoo%3Dbar | A URI encoded version of the HTTP referer header. |
%URL% | /application1/demo?foo=bar | A URI encoded version of the URI. |
%URL_ENCODED% | /application1/demo%3Ffoo%3Dbar | A URI encoded version of the URI. |
%USERNAME% | 502HB8S9Q1 | The name of the user who originated the request. |
Example
Consider the default error response, C/default.400.json
, which contains the following content:
{
"error_code":"%ERROR_CODE%",
"error_message":"%ERROR_TEXT%"
}
A request is made which results in IAG needing to redirect the client. When this error response is served to the client, the %ERROR_CODE%
and %ERROR_TEXT%
macros are populated:
{
"error_code":"0x38cf0421",
"error_message":"Moved Temporarily"
}
Public Assets
The public assets are resources which IAG will make available to all clients, regardless of authentication. This can be used to embed JavaScript, CSS or images within the error and management pages.
The %PKMSPUBLIC%
Macro
%PKMSPUBLIC%
MacroThe %PKMSPUBLIC%
macro can be used to dynamically insert the path segment where IAG is configured to serve the public assets from.
For example, to include a custom CSS file named default.css
from the public assets in an error page, use the macro:
<link href="%PKMSPUBLIC%default.css" rel="stylesheet" type="text/css"></link>
The page served by IAG will populate the macro with the correct path segment. The HTML returned to the client will look like:
<link href="/pkmspublic/default.css" rel="stylesheet" type="text/css"></link>
IAG will serve the file to all clients from the following URL: https://<application-gateway>/pkmspublic/default.css
Customizing the Path Segment
The default path segment pkmspublic
can be customized by specifying a path segment in the configuration YAML:
version: '23.04'
server:
...
public_assets:
type: zip
content: B64:UEsD...AAA=
path_segment: assets
Using the example above, IAG will now populate the macro with this value:
<link href="/assets/default.css" rel="stylesheet" type="text/css"></link>
IAG will serve the file to all clients from the following URL: https://<application-gateway>/assets/default.css
Public Assets Structure
Similar to the error and management pages, the public assets can be specified on a per-language basis.
For example, to provide different versions of default.css for English language and Korean language clients, provide a directory structure containing C
and ko
versions:
./C/default.css
./ko/default.css
See also: YAML Reference for public_assets
Content Security Policy
IAG provides a secure default Content Security Policy for all generated responses served from version 22.07 onwards. Prior to 22.07, a more relaxed Content Security Policy was configured by default.
Version 22.07 and greater
When the configuration YAML indicates a version of 22.07 or later, the following Content Security Policy headers are returned:
content-security-policy: default-src 'self'; frame-ancestors 'self'; form-action 'self';
x-frame-options: DENY
x-content-type-options: nosniff
x-xss-protection: 1
Additionally, the default set of management and errors pages returned by IAG is changed to a set which does not violate this policy. All JavaScript and CSS assets are served from separate URLs in the public assets directory.
Versions prior to 22.07
When using legacy versions of IAG or configuration YAML which indicates a version lower than 22.07, the default Content Security Policy is less strict:
content-security-policy: frame-ancestors 'none'
x-frame-options: DENY
x-content-type-options: nosniff
x-xss-protection: 1
The default set of error and management pages contains embedded JavaScript and CSS, which is permitted by this Content Security Policy. Note that IAG contains both sets of error and management pages and will select a set based on the version indicated in the configuration YAML.
Customising the Content Security Policy
Note
If the provided configuration YAML indicates a version lower than 22.07, IAG will continue to use the legacy Content Security Policy by default.
The strict Content Security Policy can be disabled using the server/content_security_policy
configuration entry.
version: 23.04
server:
...
content_security_policy: disabled
See also: YAML Reference for content_security_policy
To define a custom Content Security Policy for responses generated by the application gateway, use the server/response_headers
to define static text headers. For example:
version: 23.04
server:
...
response_headers:
- header: content-security-policy
text: default-src 'self'; img-src 'self' cdn.example.com;
- header: x-frame-options
text: deny
- header: x-content-type-options
text: nosniff
- header: x-xss-protection
text: 1
See also: YAML Reference for response_headers
Updated about 1 month ago