20.2.3 Understanding Cross-Site Scripting Protection

Protect your application from a cross site-scripting security breach. About Cross Site-scripting Security Breaches

Learn about cross site-scripting security breaches.

Cross-site scripting (also referred to as XSS) is a security breach that takes advantage of dynamically generated web pages. In an XSS attack, a web application is sent a script that activates when it is read by a user's browser. Once activated, these scripts can steal data, even session credentials, and return the information to the attacker.

If malicious code were introduced into an Oracle APEX application, it could be rendered into HTML regions and other places within the application during normal page rendering. To prevent the introduction of malicious code into session state, the APEX engine escapes characters in certain cases. Protecting HTML Regions and Other Static Areas

Learn how to protect HTML regions and other static display areas. About Protecting HTML Regions and Other Static Areas

Learn how to protect HTML regions and other static display areas.

In HTML regions and other static display areas, you can reference session state using the substitution strings. Special substitution strings available within a template are denoted by the number symbol (#), for example, #ABC#. To reference page or application items use the &ITEM. notation.

Examples of static display areas include HTML regions, page headers and footers, region headers and footers, region titles, button labels, help text, form item labels and post-element text, templates, radiogroup (before and after field text), event success messages, event error messages, navigation bar attributes, application static substitution string values, chart labels and legends, breadcrumbs and list framing text, and calendar text, labels, or legends.

Developers can also append an exclamation mark (!) followed by a predefined filter name to a page or application item name or to a report column reference to escape special characters in the substitution value. About Safe Item Display Types

Learn about safe item display types.

When session state is referenced in this way, the value emitted to the page will not have special characters (<, >, &, ") escaped if the referenced item is Display Only with the attribute Save Session State set to No and Escape Special set to No.

If the referenced item has a display type other than Display Only with the attribute Save Session State set to No, the value emitted to the page will have special characters escaped. Although application-level items are also considered to have a safe display type, they do not actually have display properties like form items do. About the Rules Used to Determine Whether to Escape Values

Review rules used to determine whether to escape values.

The APEX engine uses predefined smart escaping rules to determine if and when to escape values fetched from session state.

The reason for these rules is that items that use the display types listed previously are often for text containing HTML that is intended to be emitted to the browser without being filtered (that is, escaped). The only way this can be made safe is by the enforcement of the rule that these types of items are always escaped on input to the application. For example, if a user passes some text into a safe item using an APEX f?p URL syntax, the APEX engine escapes special characters when saving the value into session state. This has two intended results:

  1. If the value contains no special characters, the value passed in is saved into session state exactly as it was provided.
  2. If the value contains special characters, those characters are escaped when the value is saved into session state.

In either situation, the item can now safely be referenced using an &ITEM. notation in any HTML region or other static area mentioned previously. About Using Safe Item Types to Hold and Emit HTML Markup

Learn about using safe item types to hold and emit HTML markup.

You can use the safe item types listed previously to hold and emit HTML markup to the browser. For example, suppose you have a requirement to render some text in bold face by referencing a safe page item named P1_XXX (using &P1_XXX.) The item P1_XXX is presumed to contain the following HTML:


You can achieve this by using application controls (computations, processes, item source expressions, item default values, and so on) to store values into these safe items. When values are introduced in this way, you ensure the safety of the content. When you use these methods, the APEX engine does not escape any special characters when saving the values into session state.

Finally, the safety of safe items is ensured by a rule that prevents those items from being posted on a page and submitted to the APEX engine as part of a page submission. About Protecting Dynamic Output

Learn about protecting dynamic output.

Items fetched from session state and rendered using htp.p or other methods should be explicitly escaped by the code where it is appropriate to do so. For example, suppose a PL/SQL dynamic content region on a page uses the following:


If the value of the item fetched from session state could contain unintended tags or scripts, you might want to use the following in the region:


However, if you are confident that the fetched value is safe for rendering, you do not need to escape the value. As a developer, you must determine when it is appropriate to not escape output.

As a best practice, follow this rule:

  • Never emit an item fetched from session state without escaping it unless the item is a safe type.

The reason for this is that as a developer, there is no way you can prevent a hacker from posting a malicious value into a non-safe item. Even if your application does not present these items visibly to ordinary users, be aware that a hacker can mount a XSS attack using your application if you do not follow this rule. About Protecting Report Regions

Learn about protecting report regions.

The APEX engine escapes data rendered in the body of a report. References to session state in report headings and messages are fetched from session state using the smart escaping rules so that the values of safe item types are not escaped and the values of other item types are escaped.

APEX automatically escapes HTML special characters of a report column when the column's Escape special characters attribute is set to On. If you need to render HTML fragments instead of plain column values (for example, for highlighting), instead of concatenating the HTML fragment in the query itself (which prevents you from using Escape special characters), you should use the report column's HTML Expression attribute. In the HTML Expression attribute, you can enter static HTML and embed escaped column values with the #COLUMN# notation. The extended column notation gives you control regarding how APEX should escape a column value:

  • #COLUMN!HTML# - Escapes reserved HTML characters.
  • #COLUMN!ATTR# - Escapes reserved characters in a HTML attribute context.
  • #COLUMN!JS# - Escapes reserved characters in a JavaScript context.
  • #COLUMN!RAW# - Preserves the original item value and does not escape characters.
  • #COLUMN!STRIPHTML# - Removes HTML tags from the output and escapes reserved HTML characters.

For example, suppose you have a report based on this query:

FROM emp

In this example, all columns are escaped. You could define a HTML Expression on DELETE_LINK as follows:

<a href="javascript:if (confirm('Do you really want to delete #ENAME!JS#?')) doSubmit('DELETE-#EMPNO#');">Delete</a>

This example renders a link that asks if you would like to delete an employee and submits a request to delete the row if the user is confirmed. If you had not used #ENAME!JS# but #ENAME#, a name like O'Neill would cause a syntax error and an attacker could exploit the improper escaping for cross-site scripting. About Protecting Form Items

Learn about protecting form items.

When form items, including hidden items, obtain their values during the generation of the form page to be sent to the browser, the resulting text is escaped before rendering. Some of the safe item types are exceptions to this rule to support the intended behavior of each display type.

Some item types have the Security attribute Escape special characters. Use the Escape special characters attribute to specify whether or not the value should be escaped. To prevent Cross-Site Scripting (XSS) attacks, always set this attribute to On. If you need to render HTML tags stored in the page item or in the entries of a list of values, you can set this flag to Off. In such cases, you should take additional precautions to ensure any user input to such fields are properly escaped when entered and before saving.

Developers can also append an exclamation mark (!) followed by a predefined filter name to a page or application item name or to a report column reference, to escape special characters in the substitution value. About Restricting Characters Entered on an Item

Learn about restricting characters entered on an item.

Limit cross-site scripting (XSS) and other injection attacks by restricting the characters users can save in session state. To accomplish this, edit the page item and configure the Security, Restricted Characters attribute. Restricted Characters can be saved in session state. Available options include:

  • All Characters Allowed

    No restriction applies.

  • Allowlist for a-Z, 0-9 and space

    Only allow characters a-z, A-Z, 0-9, and space.

  • Blocklist HTML command characters (<>").

    Reserved HTML characters can NOT be saved.

  • Blocklist &<>"/;,*|=% and --

    The following characters: &, <, >, ", /, ;, ",", *, |, =, % and "--" (PL/SQL comment) can NOT be saved.

  • Blocklist &<>"/;,*|=% or -- and new line

    The following characters: &, <, >, ", /, ;, ",", *, |, =, %, "--", and new line characters can NOT be saved.

If you select a restriction, APEX displays an error message if a user tries to save data which does not conform to the selected character restriction.