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.

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

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:

1. If a client indicates a particular language and a response exists for that language, it will be served.
2. 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.

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:

1. Include only the C and fr directories in the directory structures for your management and error responses
2. 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

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:

Customizing Responses for Different Types of Clients with mime_type

IAG can serve different responses based on the MIME sub-type found in the request.

For example:

1. A web browser which presents an accept: text/html header will receive the html response
2. An API client presenting accept: application/json will receive a json response - provided that a json response template exists in the directory structure.

IAG uses the following logic to determine the appropriate type of response to return:

1. 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.
2. If the ‘accept’ HTTP header is not present, the MIME sub-type from the
   ‘content-type’ HTTP header in the request is used.
3. 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

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:

Error Pages error_code

IAG provides HTML responses for common error_code values and a HTML and JSON default error response:

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.

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

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