Advanced Policy


The purpose of this guide is to walk through the process of creating and managing advanced policy.
Advanced policy configuration allows Access Gateway application administrators to create policy tailored to a specific URI, and need.


Access Gateway includes the ability to configure one or more access policies per application. Policies are applied to URI resources within an application and can be set to achieve the following:

See the Administration User Policy Guide for details of creating and managing access policies.


The Access Gateway supports customized scripting within a given policy. These scripts can be used to extend the basic policy mechanism to meet specific customer requirements.

Advanced policies are:

Working with Advanced Policy

Advanced policy consists of one or more statements.

  • Are executed in the order specified.
  • Are terminated using semi-colons .
  • Can define variables.
  • Can read and write AccessGateway and HTTP session variables.
  • Support if/then style conditional constructs.
  • Can be grouped into blocks.
  • Can be short circuited, causing execution cease at that point.
  • Can change and return HTTP status codes.
  • Can rewrite URL strings.

Entering Advanced Policy

To enter advanced policy:

  1. Log in to the Access Gateway Administration 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 pencil 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.


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:




Access query arguments

arg_name where name represents a query variable.


Access cookie fields

cookie_name where name represent some cookie field..


Access arbitrary header field

http_email where email represents some field in the header.

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;


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


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.


# 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.


if ($arg_test = "demo") {
    set $policy_type "NO_AUTH";
#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 clientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. .

General format:

return numericReturnCode [optional url];


#Stop executing and return a 404
return 404;


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.



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.


proxy_set_header Host $proxy_host;
Proxy set header

Allows redefining or appending fields the request header.

General format:

proxy_hide_header field;


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;


proxy_redirect http://general.domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https)..tbd/abc http://abc.domain.tld;


The following are examples of custom configuration:

Only send field on specific URI requests

Description: Passing all fields to all URLs is often unnecessary. Using custom configuration, a policy can be created to send specific fields on specific requests

Protected rule exists for a given resource.
Configure attribute 'do not send'
Set attribute Don't Send.


Add a variable to a header

set $TEST " ";   # Set a value for later use
proxy_set_header header_name $TEST;  #Add a value to the HTTP Header

Force a return on a different URL and error code

Description: Sometimes its required to return a specific return code and URL for a given URI
Protected rule exists for a given resource.
# Regardless of the behavior, 
# for the given protected resource
# return 301 
return 301;


Specify a behavior based on query arguments

Description: Behavior for a given URI can depend on incoming query values.  For example to skip authentication for test data.
Protected rule exists for a given resource.
#If the query argument test is equal to demo 
#then set the policy type field to NO_AUTH
if ($arg_test = "demo") {
    set $policy_type "NO_AUTH";

Rewrite URL Strings

Description: Despite turning on url re-writing in the gateway, some links and redirects are pointing the browser to the wrong place.


Gateway is
Protected server is
Some links/redirects point to instead of

Protected rule exists for a given resource.

Next Steps