Develop advanced Access Gateway policy
Advanced policy consists of one or more statements. Policy 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 to cease at that point.
- Support changing and returning HTTP status codes.
- Support URL rewriting.
Known issues
Editing and validation of previously created valid policy
Syntax errors in previously valid policy custom configuration may not be detected. Okta recommends validating any updated policy custom configuration statements in a new policy, which is only used for the purposes of policy code validation and later discarded.
Defining advanced policy
To define advanced policy:
- Sign in to the Access Gateway Admin UI console.
- Click the Applications tab.
- Click Edit.
- Select Policies.
- Click Edit.
- Expand Advanced.
- In the Custom Configuration box, enter the advanced policy.
For example:
set $TEST "some value";
proxy_set_header header_test $TEST; -
Click Not Validated (
) to validate the syntax of the custom configuration. If the validation is successful, the button change to Validated. If it doesn't, correct any syntax errors and re-validate.
- Click Okay to save the custom configuration.
- 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 always preceded by #.
#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. Usually, 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.
See Embedded variables for the complete list of embedded variables.
User variables
you can define variables within a custom configuration and can use them 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
See if statement for more information on if statements.
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 the custom configuration, which is similar to a function being called in various programming languages. Directives can, and mostly do, take parameters.
General format:
directive_name [parameter1 [parameter2 [parametern]]];
See Alphabetical list of all NGNIX directives.

Note
Custom Configuration only supports directives which specify the location context.
For example:
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 to 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
Access Gateway supported application and version information
Add a generic header application
Add a sample policy application
Advanced Access Gateway policy