Developing Advanced Access Gateway Policy

Writing Advanced Policy

Advanced policy consists of one or more statements.
Statements:

  • Are executed in the order specified.
  • Are terminated using semi-colons.
  • Can define variables.
  • Can read and write Access Gateway and HTTP session variables.
  • Support if/then style conditional constructs.
  • Support grouping statements into blocks.
  • Support short circuiting, causing execution cease at that point.
  • Support changing and returning HTTP status codes.
  • Support URL rewriting.
  • And more.

Defining Advanced Policy

To define advanced policy:

  1. Sing in to the Access Gateway Admin UI console.
  2. Click the Applications tab.
  3. Open an application for edit by clicking the pencil icon.

    Click the pencil icon next to any application to open for update.
  4. Select the Policies sub-tab.
    Select the policy tab.
  5. Open a policy for edit by clicking the edit icon
    Click the pencil to open a policy for edit.
  6. Expand Advanced.
  7. In the Custom Configuration text box enter the advanced policy.
    For example:
    set $TEST "some value";
    proxy_set_header header_test $TEST;
  8. Click the not validated button () to validate the syntax of the custom configuration.

    On success the button will turn green. Otherwise, correct any syntax errors and re-validate.

  9. Click Okay to save the custom configuration.
  10. Click Done to complete the application editing session.

Custom Configuration

Custom Configuration is composed of comments, one or more statements session data, performing various tests and executing follow up actions on those tests. The following constructs are supported.

Comments

Comments are any content following the hash symbol (#).

#This is a comment
#This comment, preceded by a space
set $TEST "some value"; #this is also a valid comment

Embedded or Predefined Variables

Embedded variables include all HTTP session, cookie, query and request header fields as well as more then 50 named variables. Commonly these variables are accessed using prefixes. Common prefixes include:

Prefix

Use

Example
arg_

Access query arguments

arg_name where name represents a query variable.

cookie_

Access cookie fields

cookie_name where name represent some cookie field..

http_

Access arbitrary header field

http_email where email represents some field in the header.
sent_http_

Response header field

sent_http_email where email represents some field in the response header.

A partial list of variables, includes:

  • $args - All arguments in the request.
  • $request_uri - complete original request URI (with arguments).
  • $uri - Content URI in request.
  • $request_body - Request body.

For complete list of embedded variables see Embedded variables in the NGINX guide.

User Variables

Variables can be defined within a custom configuration, can be used in assignments, as well as conditional(if) statements.

General format:

set $variablename value;

Example:

#create a variable TEST, containing the value "test value"
set $TEST "test value";

Conditionals

Conditionals allow for making decisions based on variable state and then conditionally executing a code block.

General format:

if (condition) { statement1; statement2; . . . statementn; }

Where condition is:

  • variable name, false if empty or 0., otherwise true
  • Comparison between two variables using =(equals) and != (not equals) operators.
  • Matching of a variable against a regular expression.

Example:

# If the query parameter 'test' contains the value 'demo'
# then no authorization required.
if ($arg_test = "demo") { set $policy_type "NO_AUTH";}

In addition, the break directive stops further statement execution.

Example:

if ($arg_test = "demo") {
    set $policy_type "NO_AUTH";
    break;
}
#Statements after break not executed if condition is true

For more information on if statements see if statement.

Return codes

Stops processing and returns the specified code to a client.

General format:

return numericReturnCode [optional url];

Example:

#Stop executing and return a 404
return 404;

Directives

Directives are a set of built in functionality that can be called from custom configuration much like a function can be called in various programming languages. Directives can, and mostly do, take parameters.

General format:

directive_name [parameter1 [parameter2 [parametern]]];

For an alphabetical list of directives see the NGINX documentation here.

Info

Note

Custom Configuration only supports directives which specify the location context.
For example:
An example of a directive which supports location.

Directives examples might include:

Proxy hide header

By default certain header fields are hidden. The proxy_hide_header field directive can be used to hide other headers. 

General format:

proxy_set_header field value;

Value can contain text, variables and their combinations.

Example:

proxy_set_header Host $proxy_host;
Proxy set header

Allows redefining or appending fields the request header.

General format:

proxy_hide_header field;

Example:

proxy_hide_header secondaryEmailAddress;
Proxy Redirecting

Specifies the values that should be changed in the Location and Refresh header fields of a proxied server response. 

General format:

proxy_redirect redirect replacement;

Example:

proxy_redirect http://general.domain.tbd/abc http://abc.domain.tld;

Next Steps