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
- Select the fields to send to specific URLs
- Set a timeout for large file uploads and downloads
- Send a specific error code and URL to a URI
- Specify a behavior based on query arguments
- Rewrite URL strings
- Don't protect certain file types
- Extend AJAX session handling
- Reject requests with certain characters
- WebSocket security
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. You need all letters in lower case to avoid this situation. |
Configuration |
Configure a protected rule that applies this setting to the root '/' policy. You must also 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 . |
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:
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-2.2.4.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-2.2.4.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 applications. 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:
|
Example |
proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; |