Manual Chapter : Setting Up Cross-Domain Request Enforcement

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 17.1.2, 17.1.1, 17.1.0, 17.0.0
Manual Chapter

Setting Up Cross-Domain Request Enforcement

About cross-domain request enforcement

Cross-Origin Resource Sharing (CORS) is an HTML5 feature that enables one website to access the resources of another website using JavaScript within the browser. On occasion, your web application might need to share resources with another external website that is hosted on a different domain. Using Application Security Manager, you can safely allow CORS by specifying the conditions that state when a foreign web application is allowed to access your web application, after making a cross-domain request. This feature is called
cross-domain request enforcement
.
You enable cross-domain request enforcement as part of the Allowed HTTP or WebSocket URL properties within a security policy. Then you can specify which domains can access the response generated by requesting this URL (the “resource”). For HTTP URLs, you can also configure how to overwrite CORS response headers that are returned by the web server.
This feature does not affect internal redirection, which is always allowed. For example,
Location: /anotherpage/onthisserver/internal_redirect.php
would be allowed even if cross-domain request enforcement is enabled on the system.

Setting up cross-domain request enforcement

For this task, the security policy needs to have an allowed HTTP or WebSocket URL.
If you want to allow your application website to access the resources of another website, you can add cross-domain request enforcement to an existing HTTP or WebSocket URL. This procedure shows how to enable Cross-Origin Resource Sharing (CORS) support on your application server for either type of URL.
  1. On the Main tab, click
    Security
    Application Security
    URLs
    .
    The Allowed HTTP URLs screen opens.
  2. In the
    Current edited security policy
    list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. Locate the HTTP or WebSocket URL that needs CORs support:
    1. From the Allowed URLs menu, choose either Allowed HTTP URLs or Allowed WebSocket URLs.
    2. In either the Allowed URLs List or the Allowed WebSocket URLs List, click the URL you want to modify.
    The Allowed HTTP URL Properties screen or WebSocket URL Properties screen for the URL opens.
  4. From either
    URL Properties
    list, select
    Advanced
    .
  5. Click the HTML5 Cross-Domain Request Enforcement tab.
  6. For
    Enforcement Mode
    , specify the option to determine how to handle CORS requests.
    Select this option
    To do this
    Disabled
    Do nothing related to cross-domain requests. Pass CORS requests exactly as set by the server.
    Remove all CORS headers
    Remove all CORS headers from the response. The response is sent to the browser, and the browser does not allow cross-origin requests.
    Replace CORS headers
    (HTTP URLs only)
    Replace the CORS header in the response with another header specified on the tab, including allowed origins, allowed methods, allowed headers, and so on. The browser enforces the policy. Then after
    Replace with
    specify the protocol, origin, and port for replacing CORS headers.
    Enforce on ASM
    Allow cross-origin resource sharing as configured in the
    Allowed Origins
    setting. CORS requests are allowed from the domains specified as allowed origins. ASM enforces the policy. Specify the protocol, origin, and port of allowed origins
    For maximum security, F5 recommends that you select
    Enforce on ASM
    .
    The tab now includes additional settings determined by the option you selected.
  7. For the
    Allowed Origins
    setting, add the origins that are allowed to share data returned by this URL.
    1. For
      Protocol
      , select the appropriate protocol for the allowed origin.
    2. For
      Origin Name
      , type the domain name or IP address with which the URL can share data.
      Wildcards are allowed in the names. For example:
      *.f5.com
      will match
      b.f5.com
      ; however it will not match
      a.b.f5.com
      .
    3. For
      Port
      , select the port that other web applications can use to request data from your web application, or use the * wildcard for all ports.
    4. If you want to allow sub-domains to receive data, select the
      Include Sub-Domains
      check box.
    5. Click
      Add
      to add the origins.
      The origins that can share data with the URL are included in the list.
  8. Click
    Update
    .
  9. To put the security policy changes into effect immediately, click
    Apply Policy
    .
The security policy allows requests for the HTTP or WebSocket URL to access the resources of other websites hosted in a different domain according to the enforcement conditions that you configured.
ASM extracts the Origin (domain) of the request from the Origin header. If the Origin header is missing or has more than one occurrence, ASM issues an
Illegal cross-origin request
violation if it is set to alarm or block. If the violation is set to block in the URL section of the Learning and Blocking Settings (and the Enforcement Mode of the security policy is set to blocking), the system blocks the request.
If a request comes from a domain that does not belong to the application and is not specified in the list of allowed origins, the system also issues an
Illegal cross-origin request
violation. If the violation is set to block (and the Enforcement Mode is set to blocking), the request is blocked.

Replacing CORS headers in requests

For this task, the security policy needs to have an allowed HTTP URL. Also, the OPTIONS method must be on the Allowed Methods list.
CORS headers are enforced by all popular browsers. The browser reads the allowed origins from the Access-Control-Allowed-Origin headers in the response. If the subsequent request from that page does not match any of the allowed origins, the browser will not place the request. In many situations, the servers do not populate those headers properly, so you can have ASM replace the CORS headers.
If you want ASM to replace CORS headers when enforcing HTML5 cross-domain requests, you can update an existing HTTP URL. This task does not apply to WebSocket URLs, only HTTP URLs.
  1. On the Main tab, click
    Security
    Application Security
    URLs
    .
    The Allowed HTTP URLs screen opens.
  2. In the
    Current edited security policy
    list near the top of the screen, verify that the security policy shown is the one you want to work on.
  3. From the Allowed HTTP URLs List, click the name of the URL you want to modify.
    The Allowed HTTP URL Properties screen opens.
  4. From the
    Allowed URL Properties
    list, select
    Advanced
    .
  5. On the HTML5 Cross-Domain Request Enforcement tab, for
    Enforcement Mode
    , select
    Replace CORS headers
    .
    The tab now includes additional settings where you define how to overwrite CORS response headers returned by the web server.
  6. In the
    Allowed Origins
    setting, add the origins that are allowed to share data returned by this URL.
    Select
    Replace with
    , then specify the origin names:
    1. For
      Protocol
      , select the appropriate protocol for the allowed origin.
    2. For
      Origin Name
      , type the domain name or IP address that you want to allow to share your data with.
      Wildcards are allowed in the names. For example:
      *.f5.com
      will match
      b.f5.com
      , but it will not match
      a.b.f5.com
      .
    3. For
      Port
      , select the port that other web applications can use to request data from your web application, or use the * wildcard for all ports.
    4. If you want to allow sub-domains to receive data, select the
      Include Sub-Domains
      check box.
    5. Click
      Add
      to add the origins.
      The origins that can share data with the URL are included in the list.
  7. Optionally, for
    Allowed Methods
    , specify which methods other applications may use when requesting this URL from another domain. Select
    Replace with
    , then move the methods to allow from the
    Available Methods
    to the
    Allowed Methods
    list.
    Any method you allow here must also be in the Allowed Methods list in the security policy (
    Security
    Application Security
    Headers
    Methods
    ).
  8. Optionally, for
    Allowed Headers
    , select
    Replace with
    , then type the headers that other applications can use when requesting this URL from another domain.
    Allowed headers
    are request headers sent by clients. For example, to allow clients to send Ajax requests, type
    X-Requested-With
    , and to allow XML requests, type
    Content-Type
    .
  9. Optionally, for
    Exposed Headers
    , select
    Replace with
    , then specify the headers that JavaScript can expose and share with other applications when requesting this URL from another domain.
    Exposed headers
    are the headers the server returns in the response. For example, to discover server side web application technology, type
    X-Powered-By
    .
  10. Optionally, for
    Allow Credentials
    , select
    Replace with
    , then specify whether requests from applications in another domain can include user credentials.
  11. Optionally, for
    Maximum Age
    , select
    Replace with
    , then specify the number of seconds that the results of a preflight request can be cached or use the default.
  12. Click
    Update
    .
  13. To add methods, such as OPTIONS, required to replace headers:
    1. Click
      Security
      Application Security
      Headers
      Methods
      .
    2. Click
      Create
      .
    3. In the
      Method
      setting, select
      OPTIONS
      .
    4. Click
      Create
      .
  14. To put the security policy changes into effect immediately, click
    Apply Policy
    .
The security policy passes the CORS request to the application server. ASM replaces the header of the response with the header you specified, and returns the response.
If this request is authorized by the web server, the browser allows the foreign domain to send its original request. If the request from that page does not match any of the allowed origins, the browser declines the request.

How cross-domain request enforcement works

If you enable cross-domain request enforcement, the system must authorize requests (typically AJAX requests) made from one domain to another. When a client makes a request to another origin, the browser sends a preflight request to determine whether JavaScript from another domain may access your resource.
When processing a modification request, the browser sends a preflight request if it has no previously cached allowed origins (that is, this is the first time the browser goes to the foreign domain for such requests). The preflight request uses an OPTIONS HTTP method and CORS-related headers to check whether the server authorizes that origin.
The CORS-related headers that are included in a preflight request are:
Header
Description
Origin
Determines requesting origin.
Access-Control-Request-Method
Indicates which methods are used in the actual request (other than simple methods).
Access-Control-Request-Headers
Indicates which headers are used in the actual request (other than simple headers).
In response to the preflight request, the system uses these CORS response headers:
Header
Description
Access-Control-Allow-Origin
List of origins the resource may be shared among (support wildcard).
Access-Control-Allow-Credentials
Indicates whether actual request may include user credentials (true/false).
Access-Control-Allow-Methods
Indicates which methods can be used during the actual request.
Access-Control-Allow-Headers
Indicates which request headers can be used during the actual request.
Access-Control-Max-Age
Indicates how long (in seconds) to cache the results of a preflight request in the browser.
Access-Control-Expose-Headers
Indicates which response headers are safe to expose to JavaScript.
The browser uses the response to determine whether to allow the JavaScript to make the actual request. If the cross-domain request is authorized, the server processes the actual requests by rechecking the origin and including another response header:
Header
Description
Access-Control-Expose-Headers
Indicates which response headers are safe to expose to JavaScript.
The browser then allows the foreign domain to send its original requests.
If you select
Enforce on ASM
as the CORS Enforcement Mode, ASM permits access according to the allowed origins. So, when using this option, there is no need for a preflight request because ASM itself checks the origin. Unlike using the
Replace CORS headers
setting, ASM, not the browser, does the enforcement.