Advanced Access Gateway policy examples

This topic provides advanced policy configuration examples. These examples are for illustration and educational purposes only.

Fix the case of all URI strings

Description

Convert all URI strings to lower case.

Scenario

Some systems may interpret the upper and lower case versions of a character as different letters. Enter all letters in lower case to avoid this situation.

Configuration

Configure a protected rule that applies this setting to the root '/' policy and change the root policy to an Adaptive Rule policy. See Policy types.

Example

 
#set all URIs to lower case
if ($request_uri ~ "/.*/.*$") {
    set_by_lua_block $request_uri_temp {
        return string.gsub(ngx.var.request_uri, "?.*", "")
	}
	set_by_lua $request_uri_low "return ngx.arg[1]:lower()" $request_uri_temp;
	rewrite ^ https://$host$request_uri_low;
}

Select the fields to send to specific URLs

Description

Specify the fields to include in a request to a specific URL.

Scenario

You want to send only the fields that are needed for processing a request. This lets you avoid sending unneeded information, save bandwidth and storage, and so on.

Configuration

Click the pencil icon beside the name of an attribute. To include the attribute, turn on the toggle switch so that it says Send. To exclude the attribute, turn off the toggle.

Example

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

Set a timeout for large file uploads and downloads

Description

Set the timeout limit for uploading and downloading large files.

Scenario

Access Gateway returns network failed error messages when uploading or downloading large files.

Configuration

Open a protected or default rule for a resource and specify the timeout period in Advanced > Custom.

Example

 
# Specify a longer timeout for file uploads/downloads to the backend protected resource
send_timeout 5m;

Send a specific error code and URL to a URI

Description

Return a specific return code and URL for a given URI.

Scenario

You don't want users to see the default error message and you want to redirect them to a custom HTML page.

Configuration

Configure a protected rule that specifies the return code and URL.

Example

 
# Regardless of the behavior,
# for the given protected resource
# return 301
return 301 https://www.okta.com;

Specify a behavior based on query arguments

Description

You want to configure dynamic responses for different situations.

Scenario

You want to skip authentication when testing configurations.

Configuration

Configure protected rules that determine what happens when certain conditions exist.

Example

 
#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

When URL rewrites are enabled in the gateway, some links and redirects point the browser to the wrong URL.

Scenario

You have a public domain called gw.okta.com and an internal resource called app1.okta.com. You want to direct your links only to app1.okta.com.

Configuration

Configure protected rules for redirecting requests from one URL to another.

Notes

By default subs_filter only works with text/html documents. This example doesn't work with compressed data. See HTTP Substitutions Filter.

Example for a single redirect

 
# replace source (gw.okta.com) with destination (app1.okta.com)
subs_filter http://gw.okta.com https://app1.okta.com;

Example for multiple redirects

 
# specify the types of files to process
subs_filter_types text/html text/css text/xml;
#
# replace source (internal....) with destination (app1...) using flags ig
# i: ignore case
# g: replace all matched strings
subs_filter internaldomain1.okta.com app1.okta.com ig;
subs_filter internaldomain2.okta.com app1.okta.com ig;

Redirect non-Chrome agents to a different location

Description

Redirect all users not using a specific user agent (in this case, Chrome) to a different URL.

Scenario

You want to prevent bots and other automatic requests from sending requests to your servers.

Configuration

Configure a protected rule where Access Gateway redirects requests from non-Chrome agents to a specific URL and returns 301 (moved permanently).

Example

 
# Replace Chrome with the desired user agent and configure the error and redirect URL
if ($http_user_agent !~* Chrome ) {
    return 301 https://www.okta.com;
}

Don't protect certain file types

Description

You don't want to protect certain file types, like images and style sheets.

Scenario

Your previous platform allowed unrestricted access to images, style sheets, and similar files. You want to do the same with Access Gateway.

Configuration

Configure a protected rule for each file type that you don't want to protect.

Example

 
if ($request_uri ~ "^.*.png$") {
   set $policy_type "NO_AUTH";
}
if ($request_uri ~ "^.*.jpg$") {
   set $policy_type "NO_AUTH";
}
if ($request_uri ~ "^.*.css$") {
    set $policy_type "NO_AUTH";
}

Extend AJAX session handling

Description

Apps that use AJAX calls hang or require a refresh after a session timeout.

Scenario

An app makes AJAX calls. It's idle for a period and the session times out. When the app makes a follow-up AJAX call, it fails because the session is now inactive.

Configuration

Configure a protected rule to extend the session.

Notes

The example scripts run at the defined interval to check if a user session is inactive. When a user session expires, the script alerts the user and refreshes the page. The user then gets a new session if an Okta session exists. Otherwise, the user must reauthenticate.

The scripts accept three parameters:

  • oagSMTimeoutSeconds: Required, no default. The frequency, in seconds, that the script runs to check the session.
  • oagSMAlertEnabled: The default value is false. Show an alert if this parameter is set to true.
  • oagSMAlertMessage: The message that appears in the alert. The default message is Session timed out due to inactivity.

If the app page includes the JQuery library, follow the examples that include JQuery.

Example 1

The app uses JQuery. Replace the sample message with a customer-facing message.

proxy_set_header Accept-Encoding "";

Example 2

The app doesn't use JQuery. Replace the sample message with a customer-facing message.

proxy_set_header Accept-Encoding "";
subs_filter "</head>"
"<script type=\"text/javascript\">
	window.oagSMParams={\"oagSMTimeoutSeconds\" : 60, \"oagSMAlertEnabled\" : true,
			\"oagSMAlertMessage\" : \"Your message to be displayed\"};
</script>
<script type=\"text/javascript\" src=\"/AQUNAAsIAAM/dist/jquery.min.js\">
</script>
<script src=\"/AQUNAAsIAAM/js/sessionTimeout.js\"></script></head>";

Example 3

The app uses iFrame and JQuery. Identify a tag to replace, represented by <tag-to-replace>, in one of the iFrame pages.

proxy_set_header Accept-Encoding "";
subs_filter "</tag-to-replace>"
"<script type=\"text/javascript\">
	window.oagSMParams={\"oagSMTimeoutSeconds\" : 60, \"oagSMAlertEnabled\" : true,
			\"oagSMAlertMessage\" : \"Your message to be displayed\"};
</script>
<script src=\"/AQUNAAsIAAM/js/sessionTimeout.js\"></script></tag-to-replace>";

Example 4

The app uses iFrame and doesn't use JQuery. Identify a tag to replace, represented by <tag-to-replace>, in one of the iFrame pages.

proxy_set_header Accept-Encoding "";
subs_filter "</tag-to-replace>"
"<script type=\"text/javascript\">
	window.oagSMParams={\"oagSMTimeoutSeconds\" : 60, \"oagSMAlertEnabled\" : true,
			\"oagSMAlertMessage\" : \"Your message to be displayed\"};
</script>
<script type=\"text/javascript\" src=\"/AQUNAAsIAAM/dist/jquery.min.js\">
</script>
<script src=\"/AQUNAAsIAAM/js/sessionTimeout.js\"></script></tag-to-replace>";

Reject requests with certain characters

Description

Reject requests that contain risky characters.

Scenario

Certain characters are used in attacks on back-end web apps. Rejecting requests that contain these characters removes a potential attack surface.

Configuration

Configure a protected rule that contains the characters you want to block.

Example

 
header_filter_by_lua_block {
-- add characters inside the brackets
reBadChars = '[><]'
  if string.match(ngx.var.uri, reBadChars) then
    ngx.log(ngx.STDERR, "Bad chars found in URI")
    return ngx.exit(403)
  end
}

WebSocket security

Description

Translate HTTP calls to WebSocket (WSS) calls.

Scenario

You use WSS as a communications protocol. Access Gateway must tell the back-end server that it's translating calls from HTTP to WSS.

Configuration

Create a protected rule for each WSS resource:

  • Name: WebSocket
  • Resource: /uri/to/websocket
  • Type: Protected
  • Add the two script elements in the example for each resource.

Example

 
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";