54.4 Enabling Form-Fill Single Sign-On for an Application

You can enable form-fill single sign-on functionality for an application with the Access Portal Service.

The following topic describes how to enable form-fill single sign-on functionality:

54.4.1 Configuring a Form-Fill Application Policy

After you create the application policy, you must add a proxy-enabled application URL to the policy to enable form-fill functionality. Once configured, you must publish the policy to the repository and test it to ensure that form-fill single-sign on is functioning as expected.

The following topics describe how to configure a form-fill application policy:

54.4.1.1 Creating a Form-Fill Application Policy

You can create a Form-Fill application policy using Oracle Enterprise Single Sign-On Administrative Console.

To create:

  1. Launch the Oracle Enterprise Single Sign-On Administrative Console.

  2. In the left-hand tree right-click the Applications node and select New Web Application from the context menu.

  3. In the dialog that appears, enter a descriptive name and click Next. This will appear as the application policy name in Oracle Access Manager Console.

  4. In the screen that appears, select the desired form type and click OK.

  5. In the screen that appears, enter the URL of the target application.

  6. Click Detect Fields.

    The application's logon form appears in the window and the appropriate fields are automatically detected and configured. Verify that:

    1. The fields have been detected and configured correctly in the field list.

    2. A Submit Button is detected. If no Submit button is defined, Silent Credential Capture will not function.

    For more information on creating application policies (also known as templates), see the guide Creating and Configuring Logon Manager Application Templates.

  7. Click OK to save the application policy.

  8. In the General tab, provide optional metadata describing the application (this metadata will appear in the Access Portal reference application or another user interface of your choice, if parsed):

    • Description – a meaningful description of the application for the user.

    • Reference – internal reference describing the version/variant of the application template.

    • Category – the category under which the application will appear in the Access Portal reference application; for example, "Finance," "Development," and so on.

    • Icon Image URL – URL to the icon image that will appear next to the application entry in the Access Portal reference application.

    • Logo Image URL – URL to the full-size application logo image that will appear in the Access Portal reference application.

    • Vendor – the vendor of the application.

    • Administrator – contact information for the application's administrator within your organization.

  9. Select the desired users and/or user groups to whom this template will be available:

    1. Select the Security tab.

    2. Select the Access Portal Service repository from the Directory drop-down menu.

    3. Click Add.

    4. In the dialog that appears, enter the name of the target user or group.

    5. Click Check Names to verify the user or group exists in the directory; if you receive an error, re-enter the name and try again.

    6. Click OK to save your changes.

54.4.1.2 Adding a Proxy-Enabled URL to a Form Fill Application Policy

You can add a proxy-enables URL to a Form Fill application policy from the policy’s General tab.

To add:

  1. In the policy's General tab, double-click the target form.
  2. In the dialog that appears, select the Identification tab and click Add.
  3. In the dialog that appears, select the Regular Expression radio button and enter a launch URL in regular expression format for the target application.

    You must trim any session IDs or other session-sensitive parameters from the URL, as they will become invalid as soon as the session expires. For example:

    .*?https://otd_proxy_host\\.oracle\\.com:8282/target_webgate/login\\.jsp.*

  4. Click OK; then click OK in the parent dialog to save your changes.

54.4.1.3 Configuring Mock Credential Field Values

The Access Portal Service allows you to configure mock credential field values which will be displayed in the browser during injection for each configured field to prevent man-in-the-middle snooping.

To configure mock credential field values:

  1. In the policy's General tab, double-click the target form.
  2. In the dialog that appears, select the Proxy tab.
  3. In the Mock Fields list, select the desired field and click Edit.
  4. In the dialog box that appears, enter the desired mock value and click OK.

    To clear the mock values for all fields, click Clear All.

54.4.1.4 Configuring Form Masking

If you want to prevent the user from seeing or altering the injected credentials, you can configure the Access Portal Service to mask the entire form from view using an overlay (a solid color or an image of your choice).

Keep in mind that:

  • If no application credentials exist for the target form, the form will not be masked even if the mask has been configured, and the user will be able to enter their own credentials to continue with the form.

  • If more than one set of credentials exists for the target form, the Logon Chooser dialog will appear, allowing the user to choose the desired credentials to inject.

To configure form masking:

  1. In the policy's General tab, double-click the target form.
  2. In the dialog that appears, select the Proxy tab.
  3. Select the Mask Form check box to enable form masking.
  4. Configure the form mask as follows:

    • Mask form – enable/disable masking for the form.

    • RED/GRN/BLUE – set the numerical value for the red, green, and blue components of the desired mask color.

    • HEX – enter the hexadecimal value for the desired mask color.

    • Select color – opens the color picker, allowing you to pick the desired mask color visually.

    • Image – relative path and filename of the desired mask image to be used instead of a solid color mask.

    • Timeout – number of seconds before the form mask is dismissed.

    • Close button – enable/disable the Close button on the form mask (allows user to remove the mask).

    • Opacity – percentage opacity of the form mask.

    • Default – reset all form mask options to default values.

54.4.1.5 Publishing a Policy to the Repository

You can publish a policy to the repository.

To publish a policy to the repository:

  1. In the left-hand tree, right-click the target application policy and select Publish from the context menu.
  2. If prompted to connect to the repository, fill in the fields in the "Connect to Repository" dialog as required.
  3. In the "Browse" dialog, navigate to the policies and credentials container you created in Preparing and Enabling the Access Portal Service on an Oracle Repository.

    For example: ou=CO,dc=us,dc=oracle,dc=com

  4. Click Publish.

54.4.1.6 (Optional) Importing the Policy in the Oracle Access Manager Console

Instead of publishing the policy to the repository, you can import it in the Oracle Access Manager Console to further edit its basic settings there.

If you have already published it to the repository, you can skip this step, as the Oracle Access Manager console will retrieve it from the repository and display it in its policies list. If you modify the policy in the Oracle Access Manager console and then decide to edit it in the Enterprise Single Sign-On Administrative Console, you will need to manually pull down the updated version from the Access Portal Service repository.

Note:

Oracle recommends creating and configuring the policy in the Enterprise Single Sign-On Administrative Console as not all Oracle Access Portal features can be configured in the Oracle Access Manager Console. Additionally, you must select the Unicode encoding when saving the exported .INI file; the Oracle Access Management console does not support importing non-Unicode files.

To optionally import a policy in the Oracle Access Manager:

  1. Start the Enterprise Single Sign-On Administrative Console and import the desired policy (template) from the repository.

  2. Export the policy to a file:

    1. From the File menu, select Export.

    2. In the "Export to .INI File" dialog that appears, select the policy from the list and click OK.

    3. In the dialog that appears, select Unicode from the Encoding drop-down list, provide the desired path and name for the exported file, and click Save.

  3. Import the template file into Oracle Access Manager:

    1. Log on to the Oracle Access Manager console.

    2. In the "Access Manager" section of the page that appears, click Applications.

    3. In the toolbar above the application list, click Import (blue down-arrow).

    4. In the "Import Applications" pop-up that appears, click Browse.

    5. In the dialog that appears, navigate to the policy file, and click Open.

    6. Click OK in the "Import Applications" pop-up.

    7. In the list of applications to import displayed by the pop-up, select the desired application and click Import.

    8. In the application configuration page that appears, verify that the configuration settings in each tab have been properly carried over and make any changes if necessary. When you have finished, click Save.

      The imported application policy appears in the application list.

54.4.1.7 Testing the Configuration of the Policy

You can test the configuration of the policy.

To test:

  1. In a Web browser, navigate to http://otd.hostname:8282/target_webgate and log on with your repository credentials.

    The logon form's fields will highlight indicating the Access Portal Service is ready to capture application credentials.

  2. Enter your application credentials into the logon form and submit them.
  3. Close the browser and access the application URL again.

    You are automatically logged on to the application.

If either the credential capture or automatic logon (after credentials have been captured) do not occur, check your configuration for errors.

54.4.2 Configuring the OTD EssoDirectSubmit Server Application Function

Configure the EssoDirectSubmit Server Application Function (SAF) to match with the URL path of the targeted application’s login page.

  1. Determine the URL path of the targeted login form.

    For example, /ComplexApp/login.jsp

  2. Edit the file /OTD11g/trafficdirector_Home_1/instances/targetInstance/config/targetOTDconfiguration.conf.
  3. In the targetOTDconfiguration.conf file, insert the following command before the line Service fn="proxy-retrieve" method="*": 
    <if $uri=~"/ComplexApp/login.jsp">
Service fn="EssoDirectSubmit" method="GET"
</if>

    Note:

    Optionally, you can add multiple application URLs to a single if block using the OTD Expression Syntax. See Using Variables, Expressions, Wildcards, and String Interpolation in Oracle Traffic Director Configuration File Reference.
  4. Run reconfig located in the bin directory of your OTD instance to apply these changes.

54.4.3 Configuring Proxy Rules for an Oracle Access Portal Application

You must adhere to some basic guidelines for creating any proxy rules that are necessary to intercept the user connections to the target application and redirect them to pass through the Webgate plugin.

For in-depth information on configuring Oracle Traffic Director, please see the Oracle Traffic Director Administrator's Guide.

Since the user connection requested is intercepted by Oracle Traffic Director and redirected to the origin server, all resources referenced within the page's code must have their path rewritten to point to the Oracle Traffic Director origin server instead of the original host; otherwise, those elements will not be loaded and the page will display improperly and likely not function as intended.The following topics provide guidelines for the types of resources that must be rewritten for the page to function properly after proxy redirection:

54.4.3.1 Adding an Oracle Access Portal Application to Oracle Traffic Director

You need to configure Oracle Traffic Director proxy rules for an Oracle Access Portal Application that resides on a single host server.

Any applications that are hosted on multiple servers are not covered. Working knowledge of Oracle Traffic Director concepts and configuration procedures is assumed. To add an Oracle Access Portal application to Oracle Traffic Director:

  1. Select the protocol(s) required by the origin server application pages (home, logon, post URL, landing page) from the following scenarios:

    • HTTP only. All of the application's pages are served over HTTP.

    • HTTPS only. All of the application's pages are served over HTTPS.

    • HTTP pre-logon/HTTPS post-logon. Home and login pages are served over either HTTP or HTTPS; however, the landing page for successfully authenticated users is served over HTTPS.

    • HTTP with POST over HTTPS. All of the pages are served over HTTP but the logon form POST transaction occurs over HTTPS.

    For proper security, Oracle highly recommends matching the proxy listener protocols with those of their respective origin server pages when configuring the proxy rules. For example, do not configure an HTTP proxy listener for a page that is originally served over HTTPS.

    On the other hand, if you want to configure an HTTPS listener for a page that is originally server over HTTP, you will need to configure additional proxy rules - for more information, see the Oracle Traffic Director documentation.

  2. Create the appropriate listeners for each protocol and assign them to the target virtual server.

  3. Create the corresponding origin server pools for each protocol. Include the protocol and URI of the origin application to clearly distinguish between each pool. For example:

    • URI: http://www.originapp.com

      Pool name: origin-server-pool-http-www-originapp.com

    • URI: https://www.originapp.com

      Pool name: origin-server-pool-https-www-originapp.com

  4. Create a route for the origin application using the New Route Wizard as follows:

    1. Select the origin server pool you created in step 3. If you created more than one origin server pool, select the HTTP (non-SSL) pool.

    2. Create a URI route condition for the application - this will be the path at which your application will be accessible. Oracle recommends setting this value to the name of your origin application or using the condition builder. This path will be called the PROXY_MAP later in this procedure.

      For example: $uri =~ "^/originapp"

    3. Complete the remaining steps in the wizard to finish creating the route.

  5. In the list of routes, select the route you created in step 4 and open the Advanced Settings section.

  6. In the Rewrite Headers field, add the host header for the origin application in the following format:

    location,content-location,host

  7. Apply the following route template and replace the variables as described below:

    • #PROXY_MAP# - path to the proxied application (reverse map of the From-URI value) from step 4b. For example: originapp.

    • #OTD_HTTP# - port of the application's HTTP listener.

      For example: 80

    • #OTD_HTTPS# - port number of the application's HTTPS listener.

      For example: 443

    • #ORIGIN_HOST# - host name of the origin server pool to rewrite.

      For example: www.originapp.com

    • #DOCUMENT-DOMAIN# - domain attribute in which cookie values can be specified.

      For example: originapp.com

      #Instructs OTD to map the incoming URI from the user's browser to the root path of the origin server. OTD also uses these values to create a reverse mapping to rewrite cookie paths. It is not usually necessary to change the value of the to parameter.

      NameTrans fn="map" to="/" from="/#PROXY_MAP#" #Rewrite the https referer header <If defined $referer and $referer =~ "https://.*?\\.us\\.oracle\\.com:#OTD_HTTPS#/#PROXY_MAP#/(.*)$"> AuthTrans fn="set-variable" set-headers="referer=https://#ORIGIN_HOST#/$1" </If> #Rewrite the http referer header <If defined $referer and $referer =~ "http://.*?\\.us\\.oracle\\.com:#OTD_HTTP#/#PROXY_MAP#/(.*)$"> AuthTrans fn="set-variable" set-headers="referer=http://#ORIGIN_HOST#/$1" </If> #Remove potential headers that may interfere with mixed proxy content <If defined $srvhdrs{'content-security-policy'}> Output fn="sed-response-header" name="content-security-policy" sed="s|script-src |script-src 'self' |g" </If> <If defined $srvhdrs{'access-control-allow-origin'}> Output fn="set-variable" remove-srvhdrs="access-control-allow-origin" </If> #rewrite the location header when origin server is redirecting from HTTP to HTTPS <If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~ "^https://#ORIGIN_HOST#(:\\d+)?(/?.*)" > Output fn="set-variable" $srvhdrs{'location'}="https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#$2" </If> <If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~ "^http://#ORIGIN_HOST#(:\\d+)?(/?.*)" > Output fn="set-variable" $srvhdrs{'location'}="http://$urlhost:#OTD_HTTP#/#PROXY_MAP#/$2" </If> #Insert the Dynamic Proxy Script parameters AuthTrans fn="set-variable" insert-vars="DYNAMIC-PROXY-ENABLE=on" insert-vars="DYNAMIC-PROXY-MAP-TO=/#PROXY_MAP#" insert-vars="DYNAMIC-PROXY-MAP-FROM=/" insert-vars="DYNAMIC-PROXY-HTTPS=#OTD_HTTPS#" insert-vars="DYNAMIC-PROXY-HTTP=#OTD_HTTP#" insert-vars="DYNAMIC-PROXY-IGNORE-PATHS=" #Map all src,href,action,background,data-li-search-action and data-li-advanced-link attributes found in html content to the proxied path Output fn="insert-filter" filter="sed-response" sed="s|\\( src=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( src=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" sed="s|\\( href=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( href=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" sed="s|\\( action=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( action=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" sed="s|\\( background=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( background=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" sed="s|\\( data-li-advanced-link=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( data-li-advanced-link=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" sed="s|\\( data-li-search-action=\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2 oap=\"true\"|g" sed="s|\\( data-li-search-action=\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2 oap='true'|g" append-newline-at-end="false" type="(text/html*|text/xml*)" #Map CSS attributes to the proxied path Output fn="insert-filter" filter="sed-response" sed="s|url(\"/\\([^/][^\"]\\)|url(\"/#PROXY_MAP#/\\1|g" sed="s|url('/\\([^/][^']\\)|url('/#PROXY_MAP#/\\1|g" sed="s|url(/\\([^/][^)]\\)|url(/#PROXY_MAP#/\\1|g" type="(text/css*|text/html*)" append-newline-at-end="false" #Rewrite full URL links to the OTD proxied host/port. These sed expressions keep the existing protocols in the URL. Output fn="insert-filter" filter="sed-response" sed="s|http://#ORIGIN_HOST#:80|http://$urlhost:#OTD_HTTP#/#PROXY_MAP#|g" sed="s|http://#ORIGIN_HOST#|http://$urlhost:#OTD_HTTP#/#PROXY_MAP#|g" sed="s|https://#ORIGIN_HOST#:443|https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#|g" sed="s|https://#ORIGIN_HOST#|https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#|g" sed="s|https:\\\\/\\\\/#ORIGIN_HOST#|https:\\\\/\\\\/$urlhost:#OTD_HTTPS#\\\\/#PROXY_MAP#|g" sed="s|http:\\\\/\\\\/#ORIGIN_HOST#|http:\\\\/\\\\/$urlhost:#OTD_HTTP#\\\\/#PROXY_MAP#|g" type="(text*|application*)" sed="s|//#ORIGIN_HOST#|https://$urlhost:#OTD_HTTPS#/#PROXY_MAP#|g" append-newline-at-end="false" #Sanitize any illegal javascript domain values for our proxied host Output fn="insert-filter" filter="sed-response" sed="s|\\(document.domain=\"\\)#DOCUMENT_DOMAIN#\"|\\1$urlhost\"|g" sed="s|\\(document.domain='\\)#DOCUMENT_DOMAIN#'|\\1$urlhost'|g" sed="s|\\(document.domain = \"\\)#DOCUMENT_DOMAIN#\"|\\1$urlhost\"|g" sed="s|\\(document.domain = '\\)#DOCUMENT_DOMAIN#'|\\1$urlhost'|g" type="(text*|application*)" append-newline-at-end="false" #Attempt to rewrite any javascript page redirects Output fn="insert-filter" filter="sed-response" sed="s|\\(location.replace(\\)\"/\\([^/][^\"]*\"\\)|\\1\"/#PROXY_MAP#/\\2|g" sed="s|\\(location.replace(\\)'/\\([^/][^']*'\\)|\\1'/#PROXY_MAP#/\\2|g" sed="s|\\(location.href =\"\\)\\(/[^/][^\"]*\"\\)|\\1/#PROXY_MAP#\\2|g" sed="s|\\(location.href ='\\)\\(/[^/][^']*'\\)|\\1/#PROXY_MAP#\\2|g" type="(text*|application*)" append-newline-at-end="false" #Attempt to rewrite any JSON objects that appear as URI paths.Output fn="insert-filter" filter="sed-response" sed="s|\\(:\"\\)\\(/[^/][^\"]*\"\\)|\\1/#PROXY_MAP#\\2|g" sed="s|\\(:'\\)\\(/[^/][^\']*'\\)|\\1/#PROXY_MAP#\\2|g" type="application/json*" append-newline-at-end="false" #rewrite any javascript page redirects common in ADF applications Output fn="insert-filter" filter="sed-response" sed="s|\\(redirect url=\"/\\)|\\1#PROXY_MAP#/|g" sed="s|<redirect>/\\([^/][^<]*\\)|<redirect>/#PROXY_MAP#/\\1|g" type="text/xml*" #Remove any domain attributes from the cookie header. This will force the browser to use the otd host name as a default Output fn="sed-response-header" name="set-cookie" sed="s|domain=#DOCUMENT_DOMAIN#||g" sed="s|Domain=#DOCUMENT_DOMAIN#||g" sed="s|domain=.#DOCUMENT_DOMAIN#||g" sed="s|Domain=.#DOCUMENT_DOMAIN#||g" sed="s|domain=.#ORIGIN_HOST#||g" sed="s|Domain=.#ORIGIN_HOST#||g"

  8. Paste the generated template into the target route (e.g. originapp) section in the $SERVER-obj.conf file.

  9. If you created one or more HTTPS listeners in step 2, make the following changes in the target route (e.g., originapp) section of the $SERVER-obj.conf file:

    1. Locate the following statement:

      Route fn="set-origin-server" origin-server-pool= "origin-server-pool-http-www-originapp-com" rewrite-host="true"

    2. Add the following security rule directly above the statement listed in step 9a:

      <If $security>

      Route fn="set-origin-server" origin-server-pool="origin-server-pool-https-www-originapp-com" rewrite-host="true"

      </If>

  10. Reconfigure the server.

54.4.3.2 Path Rewriting Guidelines for HTTP Request/Response Headers

HTTP request and response headers contain parameters that must be rewritten to point to the Oracle Traffic Director origin server. Oracle Traffic Director can rewrite basic location headers that contain the origin server host name and exact protocol, or a relative path.

A typical HTTP request header appears as follows:

GET /web/en-US/default.aspx HTTP/1.1

Host: www.oracle.com

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101 Firefox/23.0

Accept: text/html, application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate

Referer: http://www.oracle.com/web/en-US/default.aspx ?root=1

Connection: keep-alive

This example header contains the following parameters that require path rewriting:

  • GET - contains the path of the requested page relative to the Web root, plus HTTP protocol version.

    For example: GET /web/en-US/default.aspx HTTP/1.1

    An example proxy rule for rewriting the GET parameter:

    NameTrans fn="map" to="/" from="/myLocalPath"

  • Host - contains the URL of the page host.

    For example: www.oracle.com

    An example proxy rule for rewriting the Host parameter:

    Route fn="set-origin-server" origin-server-pool="myoriginserverpool" rewrite-host="true"

  • Referer - contains the URL of the page that referred the request. For example: http://www.oracle.com/web/en-US/default.aspx ?root=1

    An example rule for rewriting the Referer parameter:

    <If defined $referer and $referer =~ "https://myoriginserver.oracle.com/myLocalPath/(.*)$">

    AuthTrans fn="set-variable" set-headers="referer=https://www.oracle.com/$1"

    </If>

Note:

Since Web applications vary widely, in addition to the above examples, you must examine your HTTP headers to account for any other parameters referencing a URL or a relative path.

A rewritten version of our example header would then look as follows:

GET /myLocalPath/web/en-US/default.aspx HTTP/1.1

Host: myoriginserver.oracle.com:8484

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:23.0) Gecko/20100101 Firefox/23.0

Accept: text/html, application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate

Referer: https://myoriginserver.oracle.com:8484/myLocalPath/ web/en-US/default.aspx?root=1

Connection: keep-alive

Oracle Traffic Director can not handle location redirects to another origin server. For example, if a logon page hosted on one host redirects the user to a page on another host upon successful logon, you must configure the rewriting rules for this remapping manually. For example:

<Object name="route-oracle-travel-sso">

<If defined $srvhdrs{'location'} and $srvhdrs{'location'} =~ "(http|https)://portal.myapplication.com(.*)$">

Output fn="set-variable" $srvhdrs{'location'}="https://myoriginserver.oracle.com:8484/travel-portal$2"

</If>

Output fn="sed-response-header" name="set-cookie" sed="s|path=/travel-sso/|path=/|g"

</Object>

<Object name="route-travel-portal">

Route fn="set-origin-server" origin-server-pool="origin-server-portal-oracle-travle" rewrite-host="true"

</Object>

54.4.3.3 Path Rewriting Guidelines for Browser Cookies

The path and domain parameters in cookies need to be rewritten to point to the Oracle Traffic Director origin server instead of the target application host.

For example:

Set-cookie: v1st=1666B5EACC906D6; path=/; expires=Wed, 19 Feb 2020 14:28:00 GMT; domain=.www.oracle.com

Must become:

Set-cookie: v1st=1666B5EACC906D6; path=/myLocalPath/; expires=Wed, 19 Feb 2020 14:28:00 GMT; domain=.myoriginserver.oracle.com

When configuring cookie rewriting rules, note the following:

  • Oracle Traffic Director cannot rewrite wildcarded domains, such as .oracle.com. A target host name must be specified, for example: .www.oracle.com.

  • If your application shares cookies across multiple domains, you must create separate cookie rewriting rules for each domain.

  • You must strip out the Oracle Authentication Manager cookie from the cookie set request, as it interferes with certain Web applications, such as Dropbox.

    Example rule for stripping out the Oracle Authentication Manager cookie:

    AuthTrans fn="sed-request-header" name="cookie" sed="s|OAMAuthnCookie[^;]*;| |g" sed="s|OAMRequestContext[^;]*;| |g"

  • You must strip out Oracle Authentication Manager headers before sending them to the application host.

54.4.3.4 Path Rewriting Guidelines for Page Content

Oracle Traffic Director does not directly provide the means to rewrite host names and resource paths within the HTML code of the target page.

You must use sed expressions to rewrite those values. Common HTML elements whose values will require rewriting include src, href, and action.

Example sed rule set for rewriting the src, href, and action elements:

Output fn="insert-filter" filter="sed-response" sed="s|\\(src\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g" sed="s|\\(src\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g" sed="s|\\(href\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g" sed="s|\\(href\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g" sed="s|\\(action\\)=\"/\\([^\"|^/]\\)|\\1=\"/myLocalPath/\\2|g" sed="s|\\(action\\)='/\\([^'|^/]\\)|\\1='/myLocalPath/\\2|g" type="text/html*"

Example rule for rewriting hardcoded host names:

Output fn="insert-filter" filter="sed-response" sed="s|https://www.oracle.com|https://myoriginserver.oracle.com:8484/myLocalPath|g" type="(text*|application*)"

Example rule for rewriting path references within CSS elements:

Output fn="insert-filter" filter="sed-response" sed="s|url(\"/\\([^\"|^/]\\)|url(\"/myLocalPath/\\1|g" sed="s|url('/\\([^'|^/]\\)|url('/myLocalPath/\\1|g" sed="s|url(/\\([^) |^/]\\)|url(/myLocalPath/\\1|g" type="text/css*"

Note the following when creating host name and path rewriting rules:

  • You must include the "Content-Type" attribute values for content types used by the target page in your Oracle Traffic Director configuration file to provide maximum content compatibility when rewriting.

  • Compressed content is not directly supported by sed; you must configure Oracle Traffic Director to decompress compressed HTML content before applying sed rewriting rules to the content, and recompress it afterwards.

    Example rules for decompressing and recompressing HTML content:

    Output fn="insert-filter" type="(text*|application*)" filter="http-decompression"

    Output fn="insert-filter" type="(text*|application*)" filter="http-compression"

  • In some cases, you may be able to strip out the "Accept Encoding" parameter in the request header to prevent the application host from sending compressed data in the first place.

    Example rule for stripping out the "Accept Encoding" header:

    AuthTrans fn="set-variable" remove-headers="accept-encoding"

  • JavaScript code varies widely in complexity and must be examined on a case-by-case basis in order to create clean, compatible rewriting rules.

54.4.4 Configuring the Webgate Request Filtering

You can configure Webgate Request Filtering using HTTP request filtering mechanisms.

The Webgate plugin provides the following HTTP request filtering mechanisms:

  • JavaScript tag injection into incoming (to the user browser) HTML pages

  • Mock credential substitution in outgoing POST requests

  • HTTP Basic Authentication credential injection and credential capture

  • Sanitization of outgoing HTTP requests to remove OAM/ESSO cookies and headers before the request is forwarded to the origin server

The Webgate plugin requires the following Init directives in magnus.conf:

  • To load NSAPI filters and SAFs:

    Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="webgate.so" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir"

    Init fn="OBWebGate_Init" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir" Mode="PEER"

  • To enable HTTP Basic Authentication:

    Init fn="EssoBasicAuthInit" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir" Mode="PEER"

where:

Parameter Description

shlib

="webgate.so"

Full path to the webgate.so module.

obinstalldir

="WebGate_Home_Dir"

full path to the target Webgate installation directory.

obinstancedir

="WebGate_Instance_Dir"

full path to the Webgate instance directory.

ESSOEnable

="On|Off" , default "On"

Enable or disable all plugins.

54.4.4.1 JavaScript Injection Filter

The JavaScript injection filter provides tag injection into pages incoming into the target user's Web browser.

The following table describes the supported parameters.

Parameter Description

ESSOEnable

="on|off", default "on"

Add to either magnus.conf or obj.conf

Enable or disable the JavaScript injection filter. Specifying this directive in magnus.conf disables all ESSO plugin features.

ESSOSearchTag

="str", default "</head>"

Add to obj.conf

HTML tag to match on for JavaScript injection.

ESSOInjectTag

="before|after", default "before"

Add to obj.conf

Determines whether to inject the JavaScript tag before or after the ESSOSearchTag parameter.

ESSOSearchCaseSensitive

="yes|no", default "no"

Add to obj.conf

Determines whether the match is case sensitive.

ESSOScriptPath

="path", default "/oamsso/columbiaWeb.js"

Add to obj.conf

Passed through to JavaScript as "src"

ESSOConsoleLoggingLevel

="n", default "0", "5" is trace.

Add to obj.conf

Passed through to JavaScript as "essoConsoleLoggingLevel"

ESSOPartnerId

="str"

Add to magnus.conf

Partner ID value. Passed through to JavaScript as "oam_partner". If present, takes precedence over the "id" value in .../webgate/config/ObAccessClient.xml

For example, adding the following to obj.conf

AuthTrans fn="set-variable" insert-vars="DYNAMIC-PROXY-ENABLE=on" insert-vars="DYNAMIC-PROXY-MAP-TO=/myTarget" insert-vars="DYNAMIC-PROXY-MAP-FROM=/" insert-vars="DYNAMIC-PROXY-HTTPS=18484" insert-vars="DYNAMIC-PROXY-HTTP=18282" insert-vars="DYNAMIC-PROXY-IGNORE-PATHS=/ignoreMe"

will produce the following result:

Output fn="insert-filter" type="text/*" filter="esso_webproxy" ESSOSearchTag="</title>"

54.4.4.2 Dynamic Proxy Support

Dynamic Proxy can be enabled and JS Injection Filter Parameters can be inserted into your route as Oracle Traffic Director server variables. To configure the dynamic proxy behavior, the non-null values of the parameters passed to the JavaScript tag.

When dynamic proxy support is enabled (via the DYNAMIC-PROXY-ENABLE parameter), the following parameters are inserted into your route as Oracle Traffic Director server variables and passed down as JavaScript attributes to configure the dynamic proxy behavior.

Only non-null values will be passed to the JavaScript tag. If either DYNAMIC-PROXY-MAP-FROM or DYNAMIC-PROXY-MAP-TO value is not specified, an error ("Dynamic proxy enabled but missing mapTo/mapFrom") will be logged. Add these parameters to obj.conf.

Parameter Description

DYNAMIC-PROXY-ENABLE

="on|off", default "off"

Enables or disables the dynamic proxy functionality. When disabled, the parameters listed in the remainder of this table are not passed to the JavaScript injection filter.

DYNAMIC-PROXY-MAP-TO

Destination URI. Default is null (empty string).

DYNAMIC-PROXY-MAP-FROM

Source URI. Default is null (empty string).

DYNAMIC-PROXY-HTTPS

HTTPS port number. Default is null (empty string).

DYNAMIC-PROXY-HTTP

HTTP port number. Default is null (empty string).

DYNAMIC-PROXY-IGNORE-PATHS

URIs that should be ignored. Default is null (empty string).

For example:

<script type='text/javascript' id='MyProxy' src='/myjavascript/myJavaScript.js'essoConsoleLoggingLevel='5' ... mapTo='/myTarget' mapFrom='/' ignorePaths='/ignoreMe' otdHttps='18484' otdHttp='18282'></script></head>

54.4.4.3 Configuring the Mock Credentials Filter

The Mock Credentials filter provides substitution of ESSO mock credentials in the outgoing POST request.

By default, OAM headers are stripped before the request is passed on to the origin server, but they can be forwarded with the pass-oam-headers parameter.

To enable, add a directive with the parameter to your directive in obj.conf as follows:

pass-oam-headers="true|false", default "false"

This includes the following headers (by default, they are omitted):

  • OAM_IMPERSONATOR_USER

  • OAM_REMOTE_USER

  • OAM_LAST_REAUTHENTICATION_TIME

  • OAM_IDENTITY_DOMAIN

For example:

Input fn="insert-filter" type="application/x-www-form-urlencoded" filter="esso_webproxy_input" pass-oam-headers="true"

54.4.4.4 Configuring HTTP Basic Authentication

You can configure the HTTP Basic Authentication that provides the ability to capture and inject credentials from and into Web browser basic authentication (modal) dialogs.

Configure HTTP Basic Authentication in the magnus.conf as follows:

  • Add the EssoBasicAuthInit and EssoBasicAuth functions to the load-modules Init directive (explained in Configuring the Webgate Request Filtering).

  • Add a standalone Init directive that loads the ESSOBasicAuthInit function:

For example:

Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="webgate.so" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir"

Init fn="EssoBasicAuthInit" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir" Mode="PEER"

Note:

HTTP Basic Authentication is enabled by default when you install the Access Portal Service. To disable it, remove the EssoBasicAuthInit and EssoBasicAuth functions from the load-modules Init directive and delete the fn="EssoBasicAuthinit" standalone directive from the magnus.conf file.

Then, add one or more of the following parameters to obj.conf for the header injection SAF and the credential capture filter:

Parameter Description

policy

="policy name"

Required. Name of the ESSO policy (application template) to use for authentication.

realm

="realm name"

Optional. The desired authentication realm of the target website, if more than one realm is in use.

For example:

NameTrans fn="EssoBasicAuth" policy="BasicAuth1" realm="realm1"

Output fn="insert-filter" filter="esso_output_capture" policy="BasicAuth1" realm="realm1"

54.4.4.5 HTTP Request Sanitizer

The HTTP request sanitizer strips the proxied HTTP request of any cookies and headers added by Oracle Access Manager and the Webgate plugin before the request is forwarded to the origin server.

The sanitizer removes cookies with the following names:

  • OAM_Partner

  • OAMAuthnCookie_*

  • OAMRequestContext*

  • OAMAuthnHintCookie

  • OAM_*

  • ESSO_BAH* (Basic Authentication Hint, caches policy, realm, and credential GUID)

Request-specific cookie names (for example, containing the server name) are matched using a wildcard, indicated above by the trailing asterisk.

The sanitizer removes the following headers:

  • OAM_IMPERSONATOR_USER

  • OAM_REMOTE_USER

  • OAM_LAST_REAUTHENTICATION_TIME

  • OAM_IDENTITY_DOMAIN

Note:

The Mock Credentials filter also provides this sanitization, but only while processing HTTP POST requests that contain mock credentials. The Webgate HTTP request sanitizer performs this function unconditionally on all requests.

To enable the sanitizer, add the EssoClean function to the load-modules Init directive in the magnus.conf file. For example:

Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response,EssoBasicAuthInit,EssoBasicAuth,EssoClean" shlib="webgate.so" obinstalldir="Webgate_Home_Dir" obinstancedir="Webgate_Instance_Dir"

Then, add the following to the obj.conf file:

<If not $uri =~ "/oamsso">

NameTrans fn="EssoClean"

</If>

Note:

The HTTP Request Sanitizer is enabled by default when you install the Access Portal Service. To disable it, remove the EssoClean function from the load-modules Init directive in the magnus.conf file, and remove the above code from the obj.conf file.

The Webgate plugin passes the target credential's GUID value in the proxied URL to the origin server. If the target application does not function properly due to this value being passed, add the following rewrite rule to the Oracle Traffic Director configuration to strip out the GUID value:

<If defined $query and $query =~ "(.*?)(ESSOCredGuid={.*?})(.*)$">

AuthTrans fn="set-variable" set-reqpb="query=$1$3"

</If>