LDSTechForumProjects

7.x Main Config file

Sample Config File

<?alias http-port=80?>
<?file-alias usr-src-xml="D:\Documents\wamulator\user-config.xml" default="<users/>"?>
<?file-alias policy-src-xml="D:\Documents\wamulator\policy-config.xml"?>

<config proxy-port="{{http-port}}" console-port="1776">
    <console-recording sso="true" rest="true" max-entries="100" enable-debug-logging='true'/>
    <sso-cookie name="wamulator" domain=".lds.org"/>

    <sso-traffic>
        <by-site host="local.ldschurch.org" port="{{http-port}}">
            <cctx-mapping thost="127.0.0.1" tport="8080">
                <policy-source>xml={{policy-src-xml}}</policy-source>
            </cctx-mapping>
        </by-site>
    </sso-traffic>
    
    <user-source type='xml'>xml={{usr-src-xml}}</user-source>
</config>

Contents


Overview


This document describes the syntax of the configuration file required when starting any V7.x version of the SSO Simulator, also known as the WAMulator. Many of the constructs described herein are based upon concepts described in SSO Environment Overview, Application Development with Single Sign-On, External Application Development with SSO, and Developing SSO Protected Applications. For information on simulator revisions see SSO Simulator Revisions.

Aliases and Macros


In the configuration elements described below some values need to be used in multiple places while others can't be included directly into the syntax without breaking it such as values that themselves contain XML content. Hence a macro pattern is supported and values for such macros are defined using three XML processing instructions <?system-alias ?>, <?classpath-alias ?>, and <?file-alias ?>.

Remembering that XML processing instructions start with <? and end with ?>; the formal definition of the alias declaration and macro references is defined in the Listing below. Any configuration attributes defined in this document indicating that they can accept an alias can have their entire value consist of a macro or can have one or more macros embedded within literal text and such macros will be replaced with the alias values. The notable exception is the condition attribute for <entitlements>'s child <allow> element which must have its entire value consist of a single macro.

All aliases defined via processing instructions are known as explicit aliases. There are two alias that are available implicitly under specific conditions. See the documentation for the <config> element's console-port and proxy-port attributes and their implicitly defined aliases for use in a restricted set of locations when auto-binding is used for the simulator such as when using the simulator in unit and integration tests.

The <?alias ...?> command: <?system-alias ?>, <?classpath-alias ?>, and <?file-alias ?> instructions allow for white space within values and support declaration of default values in the event that the resource indicated is not found. Their syntax is as follows:

Listing: Alias/Macro Syntax Defined

 [1] alias := ["<?system-alias " | "<?classpath-alias " | "<?file-alias "] <name-value> <default-value> "?>"
 [2] name-value := <name> "=" [""" <ref-with-spaces> """ | <ref> ]
 [3] default-value := "default=" [""" <def-with-spaces> """ | <def> | macro ]
 [4] name := <clean-text>
 [5] ref-with-spaces := <clean-text-with-spaces>
 [6] ref := <clean-text>
 [7] def-with-spaces := <clean-text-with-spaces>
 [8] def := <clean-text>
 [9] clean-text := << any alpha-numeric characters or [<>-_] >>
 [10] clean-text-with-spaces := << any alpha-numeric characters, [<>-_], or whitespace >>
 [11] macro := “{{“ <name> “}}”

Examples of valid versions of this processing instruction are:

 <?system-alias rest-port=rest.port?>  <!-- pulls the value from the rest.port system property -->
 <?system-alias console-port=rest-port default=1776?>
 <?file-alias is-bishop="is bishop.txt"?>
 <?system-alias user-account-id=user.acct.id default=1134560?>
 <?classpath-alias is-ip-moderator=is-ip-mod.xml default="<Attribute name='acctid' operation='equals' value='3431968674741880'/>"?>

The first four instructions use literal text values although the second’s values also contain a macro reference to the first alias. Hence, the console-port alias will have the same value as that of the rest-port alias and the rest-api value will be the value found in the System property 'rest.port'. The fourth instruction will have the value of the System property 'user.acct.id' or '1134560' if not found. The fifth instruction uses a classpath file reference. Suppose that the contents of that file contained the following text.

 <Attribute name='acctid' operation='equals' value='3431968674741880'/>
 <Attribute name='acctid' operation='equals' value='{{user-account-id}}'/>

Upon processing the is-ip-moderator instruction the file will be searched and loaded as the value for that alias. Additionally, if its contents contain any alias macros they will be resolved. Hence, assuming the user.acct.id system property were not found the value of the is-ip-moderator alias will be:

 <Attribute name='acctid' operation='equals' value='3431968674741880'/>
 <Attribute name='acctid' operation='equals' value='1134560'/>

<config>


This is the root element of the configuration file. It supports the following attributes:

Attributes

Attribute Name Type Elements
proxy-port Integer or 'auto' or Alias The port on which the simulated site will appear with all back-end applications mapped into its subdirectory space or 'auto' if the simulator should be started on any available port. If not 'auto' then the value must be an integer. The 'auto' feature was added in v4.13 to allow the simulator to be programmatically started more easily in unit tests. v5.3 added support for the auto-bound port value being used in the <by-site> element's port attribute.
console-port Integer or 'auto' or Alias The port on which the simulator’s console is located. If 'auto' is specified then the console will be started on any available port. If not 'auto' then the value must be an integer. The 'auto' feature was added in v4.13 to allow the simulator to be programmatically started more easily in unit tests. v5.3 added support for the auto-bound port value being used in the <cctx-mapping> element's tport attribute.
allow-non-sso-traffic [ 'true' | 'false' ] Indicates if the simulator should act as a forward proxy in addition to acting as a reverse proxy for the simulated site. See SSO Environment Overview. If allowed, then a browser can be configured to use the simulator's proxy-port as its http proxy. The default is false and causes the simulator to serve a 503 for any traffic that does not match the configured SSO traffic.
rest-version [ 'CD-OESv1' | 'openSSO' ] (As of v4.12)Indicates the rest interface that should be exposed by the simulator. CD-OESv1 is the Church Defined Oracle Entitlements Server. openSSO is the version that mimics the openSSO policy server. Defaults to CD-OESv1 in v4.12+, to openSSO in prior versions.


<console-recording>


Optional child of <config>. It supports the attributes shown below. The console’s SSO Traffic and Rest Traffic tabs respectfully expose traffic that has passed through the simulator if recording is turned on either via the links within those pages or by this declaration. Recording for each is turned off by default. It further enables activation of capturing and exposing the http request/response conversation contents passing through the proxy port.

Attributes

Attribute Name Type Description
sso [ 'true' | 'false' ] Indicates if the console should record in-memory the traffic that is hitting the http-proxy port and display it on the SSO Traffic tab. Defaults to false. Can be ‘true’ or any other value which is interpreted as ‘false’.
rest [ 'true' | 'false' ] Indicates if the console should record in-memory the traffic that is hitting the rest API and display it on the Rest Traffic tab. Defaults to false. Can be ‘true’ or any other value which is interpreted as ‘false’.
max-entries Integer or Alias Specifies how many traffic logs to keep.
enable-debug-logging [ 'true' | 'false' ] Indicates if the logs for the traffic are to be written for and available from the traffic page in the SSO Simulator admin. Defaults to false. Can be ‘true’ or any other value which is interpreted as ‘false’.
title Literal text (Optional) If not included then the simulator's name and version number is used. Allows for setting the html title of the wamulator's html console. This is a convenience for developers and serves only to change the name that shows up on an in-browser tab.


<proxy-timeout>


Optional child element of config. It supports the attributes describe below. This element allows for adjustment of the socket read timeouts for the proxy if default values are insufficient. If this directive is specified then both values must be included. As noted, specifying a value of '0' essentially disables timeouts causing reads to block forever until data is received which can be useful during development when using debuggers to step through code running in an application behind the WAMulator.

Attributes

Attribute Name Type Description
inboundMillis Numeric Indicates the milliseconds for which a read of the input stream of a socket connecting to the proxy will block before throwing a SocketTimeoutException. Defaults to 20000 milliseconds which is 20 seconds. A value of 0 sets the timeout to infinity.
outboundMillis Numberic Indicates the milliseconds for which a read of the input stream of the socket used by the proxy to connect to the proxied server will block before throwing a SocketTimeoutException. Defaults to 20000 milliseconds which is 20 seconds. A value of 0 sets the timeout to infinity.


<port-access>


This is an optional child element of config. As of version 5.49 the WAMulator accepts connections only from the local machine by default unless that behavior is overridden by including this element in your configuration. This is true of all ports both proxy, tls proxy, and console/rest. The attributes supported by this directive are shown below. On a similar note there have been instances of outbound connections failing when the wamulator attempts to connect to the applications running behind it. These have consistently been seen when running under jdk1.7 which is a known issue. Try adding the VM parameter -Djava.net.preferIPv4Stack=true when starting the wamulator to get around this issue.

Attributes

Attribute Name Type Description
local-traffic-only Literal boolean or Alias Indicates if traffic to any WAMulator port should be allowed from hosts other than the machine on which the WAMulator is running. If not included then the default is to reject connections from other hosts by serving a suitable message page. Setting to 'false' allows for connections from other hosts to be accepted.


<proxy-tls>


HTTPS traffic portrayed
Optional child element of config. As seen in the SSO Environment Overview the WAM environment offloads TLS/SSL at the front load balancer freeing up application servers and centralizing the enabling X509 certificate. This directive causes such an https port to be opened by the simulator supporting RFC 2818 Http Over TLS. TLS is short for Transport Layer Security which is the standardized and improved version of Netscape's SSL (Secure Sockets Layer). Requests received through this proxy-tls port are handled just as requests received through the http proxy port but have an X-Forwarded-Scheme header injected with a value of "https" instead of "http" allowing applications to determine through which protocol they were accessed. The attributes supported by this directive are shown in the Attributes Table. When TLS is leveraged either on an incoming port via this directive or when proxying to the thost of a given <cctx-mapping> directive, the http console adds locks on the appropriate side of the path as shown in this image. The locks on the left indicate traffic hitting the wamulator came over the https port. Those on the right indicate that the wamulator connected to the target server via TLS. Note that enabling TLS/SSL will require changes to you <by-site> directives if you wish to hit those sites with HTTPS traffic. Specifically, you need to add or adjust by-site's scheme attribute to allow that site to handle https traffic.

Attributes

Attribute Name Type Description
https-port Literal numeric or Alias Indicates the port on which https traffic should be received. Unlike proxy-port and console-port this attribute does NOT yet support 'auto'
cert-host Literal text or Alias Indicates the fully qualified name of the host that will be represented by the auto-generated certificate used during the initial TLS handshake for an incoming request. For such a certificate to be accepted by browsers it must match the host to which traffic was going such as "localhost.lds.org". Alternatively, RFC 2818 Http Over TLS dictates that browsers should accept certificates with a wildcard such as "*.lds.org". But such will only be accepted for that level of the domain and not further subdomains. So such a certificate will be accepted for foo.lds.org but not more.foo.lds.org.

Note that the auto-generated certificate and its corresponding private key will be stored in the current directory in files with names of <host>-cert.pem and <host>-priv.pem respectively. For wildcarded hosts the wildcard character is specified in the filenames as two underscore characters. Upon restarting the wamulator these files are looked for and used if found so that the same certificate will continue to be used and not force you to have to accept a newly generated one in your browser the first time that you again access the proxy-tls port after restarting.


<sso-cookie>


This element declares the cookie name that the proxy-port of the simulator will look for to associate a request with a specific user. It also allows declaration of the domain for which the cookie will be set if using one of the simulator's sign-in pages. For setting the cookie in the browser it is important to note that the cookie will not be accepted by the browser if the request made that resulted in the cookie being set was not in the domain of the cookie. Hence, when using the simulator you must use a domain and it must resolve to the host on which the simulator is running. See Configure hosts file for SSO for configuring a local development box to have a domain such as localhost.lds.org resolve to the local machine.

Notice in the Attributes table below that the default cookie name returned from the simulator is “app-wrap-token”. The cookie used in the openSSO nextgen environment was lds-policy while the cookie used by OAM is ObSSOCookie. WARNING: if the application being served through the simulator has references to resources located in the real OAM environment and not served from the simulator like javascript or css files then the cookie name used by the simulator must not match that used by the OAM environment since the OAM environment will set a cookie value even for publicly accessible resources and will clobber the cookie being set by the simulator.

Attributes

Attribute Name Type Description
name Literal text or Alias Indicates the name of the SSO token that will be returned from the getCookieNameForToken REST API call and looked for they the simulator’s proxy when performing URL enforcement and user header injection. Defaults to “app-wrap-token”.
domain Literal text or Alias Indicates the domain of the cookie that will be set by the simulator in the select user page. Defaults to “.lds.org”.
session-timeout-seconds (optional) Integer or Alias Defaults to 300 seconds which is five minutes. If specified it defines how long a user session lasts without either sso or REST traffic activity before expiring. Any traffic resets the session’s counter.


<conditions>


As of v7.0 this is no longer valid. This is configured in the Policy Exposee Export file.


<condition>


As of v7.0 this is no longer valid. This is configured in the Policy Exposee Export file.


<sso-traffic>


Since the simulator is both a forward and reverse proxy it must be told which requests passing through its proxy port should be considered SSO Traffic, have headers injected, be subject to access restrictions, and optionally be proxied to a back-end application. Its nested elements are the mechanisms where-by we identify such traffic to the simulator and thereby subject that traffic, both requests and responses, to SSO features.

<by-site>


The by-site element is used to declare the host, port, and scheme that packets must match to be subject to the policies of its nested elements and allows for sub paths of that “site” to be routed to one or more applications and have policies applied. It supports the attributes listed below.

See the dual debug page example for a sample of how this element is used.


Attributes

Attribute Name Type Description
scheme Optional Literal text One of 'http', 'https', or 'both'. Defaults to 'http'. Indicates if this directive applies to traffic on the http or https proxy port or both.
host Literal text or Alias The value that will be compared to the host portion of the host header to determine if the packet matches this site and should be subject to its policies.
port Integer, Explicit Alias, or "proxy-port" implicit alias The value that will be compared to the port portion of the host header to determine if the packet matches this site and should be subject to its policies. Explicit aliases are those defined in the configuration file. As of v5.3 when "auto" is used as the value of the <config> element's proxy-port attribute, an implicit alias is available allowing the auto-bound proxy port value to be used in this attribute. This is mostly for use in unit tests.


<cctx-mapping>


Directive used to match requests made to the simulator's proxy port and proxy them to a host and port elsewhere adjusting portions of that request if needed. Proxying will only occur after applying access policies as defined in the Policy Exposee Export file.

The supported attributes are shown below.

Attributes

Attribute Name Type Description
cctx Literal text or Alias The cctx attribute was used as part of the URL matching mechanism prior to version 7.0. Version 7.0 and above now have this functionality as part of the "policy" that is configured in the Policy Exposee export configuration file.
thost Literal text or Alias The target host to which the traffic will be proxied. This can be by IP address or dns name.
tport Literal text, Explicit Alias, or 'console-port' Implicit Alias The port on the targeted host. This must be an integer, an explicit alias the resolves to an integer, or, as of v5.3, the implicit alias 'console-port' that is available when the config element's console-port is specified as "auto" allowing any available port to be used. See <config>.
tpath Literal text or Alias This functionality is not representative of functionality that is provided in the production WAM environment. In order to make the WAMulator more closely emulate our production WAM solution, this functionality has been removed as of version 7.0 of the WAMulator.
cscheme 'http' or 'https' or 'both' (Optional). Defaults to http. 'both' is only applicable if the containing <by-site> directive's scheme attribute has a value of 'both' otherwise only one type of traffic will make it to this directive. Indicates the protocol to be used when matching incoming requests. For https traffic the wamulator automatically trusts the certificate offered by the target host during the TLS handshake. In other words, certificates for targeted hosts do not need to be loaded into a local java trust store.
tscheme 'http' or 'https' or 'same' (Optional). Defaults to http. 'same' is used only when cscheme is set to 'both' meaning that this directive routes both http and https traffic to the same back-end server and a secured request will be followed by a secure line to the server using the port indicated by tSslPort.
tSslPort Numeric port numer Required when tscheme is 'https' or 'same' to indicate the target port on the application server for SSL traffic connections.
preserve-host 'true' or 'false' Optional attribute in v5.3+. Defaults to true. When 'true' or not specified the host header is not changed when proxying to an application. To force the host header to be changed to be the values of thost + ':' + tport add this attribute and set it to false. This would be necessary if the back end application to which traffic is being proxied used virtual hosts different from the host specified by the containing by-site element.

For example, suppose that you want to place the simulator in front of a test server to perform some integration tests but that server has apache fronting the servlet container and that box can be accessed directly by a DNS name of test.lds.org. If apache is using a virtual host of test.lds.org but the simulator is using a host of localhost.lds.org then apache will return an error since that host does not match its defined virtual host. In such a case, specifying thost="test.lds.org" and preserve-host="false" would cause the host header to be rewritten to the thost + ":" + tport value allowing apache to accept and process the request.

host-header Literal text or Explicit Alias Optional attribute in v5.23+. Specifying forces preserve-host to be "false" whether specified or not. When specified, the value of this attribute becomes the full value of the host header as a request is passed to the application.

For example, suppose in the example for preserve-host that a load balancer were sitting in front of the test server and that test.lds.org resolved to the IP address of the load balancer. In such a scenario thost must be the IP address of the serve. But apache must have the host header be "test.lds.org" or it won't accept it. Specifying thost="IP of test server" and host-header="test.lds.org" will route requests to the IP but rewrite the host header to be test.lds.org as needed.

policy-service-url-gateway Literal text or Explicit Alias Optional attribute in v5.23+. Used to alter the host and port of the policy-service-url header that gets injected by the simulator to tell applications where its rest service resides for fine grained permissions. Why this would be needed is illustrated with the following example.

For example, suppose in the example for preserve-host that a firewall prevented the application on test.lds.org from calling back to the rest service or DNS was unable to resolve your by-site host since you are using etc/hosts to override DNS to point to your local box. You could use a reverse proxy running between your local box and the test server and specify policy-service-url-gateway="127.0.0.1:tunnelPort" and the policy-service-url header would be rewritten with that host and port allowing the application to connect locally but have the reverse tunnel route it to the locally running port of the simulator.

scheme-header-name Literal text or Explicit Alias (Optional) Allows for overriding the name of the header that conveys to the application what scheme was used when the WAMulator received the request. The default is X-Forwarded-Scheme which apparently causes tomcat some problem.
inject-scheme-header Literal text or Explicit Alias (Optional) Allows for preventing any scheme header from being injected. Default is 'true' if not specified.

See the dual debug page example for a sample of how this element is used.


<policy-source>


Declares a source for the configuration file that is exported from Policy Exposee. The format is a string of characters starting with xml= followed by a macro construct as defined in the Aliases and Macros section above. The resolved content of the macro's alias should be XML content in exposee format. For example, a file-alias could be used to load the XML from a file and make it available in any macro that specified that alias. The exposee xml format is the format of export and import files defined by the Policy Exposee tool and includes definitions for policies, headers, etc.

<headers>


As of v7.0 this is no longer valid. This is configured in the Policy Exposee Export file.


<fixed-value>


As of v7.0 this is no longer valid. This is configured in the Policy Exposee Export file.


<profile-att>


As of v7.0 this is no longer valid. This is configured in the Policy Exposee Export file.


<purge-header>


This is no longer supported.


<cctx-file>


There are many times when files need to be served up during development of an application but it is not desired that they be served up as part of the application. For example, some applications separate their cache-able resources out and place them on a Content Delivery Network or CDN. Such resources typically are located in a separate project from the application yet need to be served up and available during development and testing. Additionally, applications may have URL dependencies on other applications are not running on the local box or are not yet available. For both situations the simulator allows for responses to requests to be served directly from files on the local box via this directive. For example, lets suppose that the application being developed locally includes a javascript based calendar widget that gives a summary of calendar events from the calendar application. But the calendar application is something that we do not wish to have running locally or is under development and not yet available. If we know the contract or structure of the AJAX responses or we can capture such calls we can paste that content into a file on the local box and then map the call into our site and have the local file served up for that request. Furthermore, the apache mime.types file has been included making the The cctx-file declaration is the element that enables this functionality.

Note: This functionality is purely for convenience while using the WAMulator. The production WAM environment does not provide this same functionality.


Attributes

Attribute Name Type Description
cctx Literal text or Alias The top level sub-path ending with an asterisk that URLs for the site must start with to match this rule and be served via a local file. Ex: “/images/*”. This is a prefix match independent of if the URL contains query parameters. The terminating asterisk is required and omitting it will result in an error. Be careful about having a terminating slash for the last path element if using relative file paths. See the example in the description of the file attribute indicating how this can result in 404 Not Found.
file Literal text or Alias An indication of the file or files to be served for matching requests. If prefixed with "classpath:" then the file or files are looked for relative to the classpath. Otherwise the java.io.File() constructor is used and the path can be a fully qualified one, even specific to the operating system if needed, or it can be relative to the current directory.

If the value does NOT end with an asterisk, '*', then the value represents a fixed path for a single file that will be returned for all matching requests regardless of the URL paths beyond the matching cctx part.

If the value ends with an asterisk, '*', then this indicates a relative path and the full path for the file to be served for any specific request is created using a portion of the requested URL. In such a case, the path is determined by taking the value of this attribute, stripping off the "classpath:" prefix if any, and removing the terminating asterisk character, '*'. To this value is appended the portion of the request URL following the matching cctx portion. For this relative case, any occurrence of the character sequence '../' is removed preventing access to files above the relative path specified in this attribute.

In all requests, if the indicated file is not found then an http 404 Not Found response is returned.

Example, suppose that I want to serve all files in the current run-time directory at a URL of host:port/file/relative. To do so I would specify a 'file' attribute value of '*' and a 'cctx' value of '/file/relative/*'. Note the terminating slash character, '/'. Suppose that I mistakenly left off the terminating slash character and assigned cctx='/file/relative*'. When a URL of '/file/relative/textfile.txt' were requested the cctx matching portion would be stripped leaving '/textfile.txt'. To this is prepended the value of the 'file' attribute up to but not including the asterisk leaving a path of, '/textfile.txt'. The file looked for is fully qualified and not relative. Hence, it won't be found by java.io.File() and will result in a 404 response code.

content-type Literal text, or Alias (Optional) If not specified then the mime.types file is consulted to determine the type from the file's extension. If specified then this is the value that set for the Content-Type response header when serving the file.

<cctx-unenforced>


Note: This feature was added in version 7.0.3


There are times when requests from different contexts need to be handled by different application servers. It is possible that an application server will need to be unenforced (not protected by WAM). This element is added for convenience of supporting this scenario.

Note: This functionality is purely for convenience while using the WAMulator. The production WAM environment does not provide this same functionality.


Attributes

Attribute Name Type Description
cctx Literal text or Alias The top level sub-path ending with an asterisk that URLs for the site must start with to match this rule and be served via a local file. Ex: “/images/*”. This is a prefix match independent of if the URL contains query parameters. The terminating asterisk is required and omitting it will result in an error. Be careful about having a terminating slash for the last path element if using relative file paths. See the example in the description of the file attribute indicating how this can result in 404 Not Found.
thost Literal text or Alias The target host to which the traffic will be proxied. This can be by IP address or dns name.
tport Literal text, or Alias The port on the targeted host. This must be an integer, an explicit alias the resolves to an integer.

Example of a configuration that would allow all requests coming in that start with the context /bc to be forwarded to the application server listening on port 8500:

 <cctx-unenforced cctx="/bc*" thost="localhost" tport="8500"/>

<unenforced>


As of v7.0 this is no longer valid. This is configured in a Policy Exposee Export file applied with the <policy-source> element within a <cctx-mapping> element.

<allow>


As of v7.0 this is no longer valid. This is configured in a Policy Exposee Export file applied with the <policy-source> element within a <cctx-mapping> element.

<rewrite-redirect>


This feature is not supported in the WAM environment and hence has been removed in v8.0+ of the Wamulator. For configuring previous releases the following content is being left in place for now but will be removed at some point in the future.

Applications should be designed as much as possible to be cognizant of running in an environment where there is a difference between canonical and application URL space and and ensure that any redirects issued by it are canonical. But sometimes that is not possible when using third party libraries. In such cases a rewriting proxy like apache or its IBM variant IHS can be used to fix application space redirects that have no meaning in the canonical space where the browser is running. Section 14.30 of RFC 2616 defines the “Location” response header used to convey a redirect instruction to the browser. It states that, “The field value consists of a single absolute URI.”

Accordingly, the servlet specification dictates that servlet containers must convert relative URIs passed to the sendRedirect method of HttpServletResponse to absolute values. As noted in the 1.4 version of this method’s javadoc, “If the location is relative without a leading '/' the container interprets it as relative to the current request URI.” This means that it will prefix its path as needed including using the java context root. If the canonical space is different from the application space this can be a problem.

Lets look at an example. Suppose we have some bishop application written in java and having a java context of nextgen-bishop. We have taken care to ensure that we always issue absolute redirects that are cognizant of canonical space. But suppose further that it uses a third party ajax library that has embedded relative redirects over which we have no control. These will result in Location headers like so:

Location: http://labs-local.lds.org/nextgen-bishop/some/resource.html

But suppose that our application has been deployed at a canonical space of /bishop since we do not wish to have the “nextgen” identifier showing up in the browser. This will require that our Location header be modified to appear as follows:

Location: http://labs-local.lds.org/bishop/some/resource.html

The mechanism for achieving this in apache and IHS is the proxyPassReverse directive. The simulator supports this feature with its rewrite-redirect directive. There is no limit tn the number of such directives. They must be declared as a child of the sso-traffic element and have the following structure:

<rewrite-redirect from='from-value' to='to-value' />

Although it performs the same functionality as apache’s proxyPassReverse it varies in its declaration syntax by requiring fully qualified prefixes including the scheme, host, and port of the URI. Specifically, the Location header value will only be rewritten if it starts with the from-value. Further, only the the from-value portion of the Location header value will be replaced with the to-value portion. For example, to fix the improper redirect above to the correct value also shown above the following directive would be declared as a child element of the sso-traffic elements:

<rewrite-redirect from='http://labs-local.lds.org/nextgen-bishop/' 
    to='http://labs-local.lds.org/bishop/' />

<rewrite-cookie>


This feature is not supported in the WAM environment and hence has been removed in v8.0+ of the Wamulator. For configuring previous releases the following content is being left in place for now but will be removed at some point in the future.

Related to redirects are path based cookies. The java servlet specification dictates that the name of the session tracking cookie be “JSESSIONID”. Let suppose that we have two distinct java applications implementing different portions of our site at labs.lds.org. One will reside at /bishop in the canonical space with a java context root in the application space of /nextgen-bishop and traffic routed with suitable URL rewriting of requests as shown in ???? and Location header rewriting on redirect responses as shown in Rewriting Redirects. The other application will reside at /mls/mbr in the canonical space with a java context of /mls-membership in the application space with similar rewrites for requests and responses. Now consider that both make use of java’s HttpSession functionality. When /bishop is accessed a JSESSIONID cookie is set in the browser to track the user’s session. If the user then accesses /mls/mbr the JSESSIONID cookie is submitted for the domain but does not match a session in that application. Accordingly, the application sets a new JSESSIONID cookie in the browser and any information in the /bishop application is now orphaned. Upon returning to /bishop the application sees a JSESSIONID that does not match any of its sessions and hence starts a new session and sets the JSESSIONID cookie accordingly in the browser orphaning the session from /mls/mbr. To resolve such a problem typically the container specific functionality must be relied upon to set a path for the cookie which usually is the servlet context of the application. That means that for the /bishop application the JSESSIONID path will be /nextgen-bishop and that for the /mls/mbr application will be /mls-membership. Since the applications will be accessed from the browser using their canonical paths the cookie will never be submitted for either application. Apache and IHS support directives for rewriting such cookie paths. The simulator provides a similar mechanism through its rewrite-cookie directive. It is similar in form to rewrite-redirect and must also be declared as a child of the sso-traffic element. It has the structure as shown in the example below which would handle the cookie path rewrites needed for our two applications:

<rewrite-cookie from-path='/nextgen-bishop' to-path='/bishop' /> 
<rewrite-cookie from-path='mls-membership' to-path='/mls/mbr' /> 

It is important to note that these again are prefix values. If a container supported setting a multi-level path like /mls-membership/app-1 then the rewriting only rewrites the matching portion and leaves the unmatched portion unchanged. For such a case the resulting cookie path of “/mls/mbr/app-1” would result.

<user-source>


Declares a source for WAMulator users. Supports the attributes shown below. If there is more than one user source declaration, at sign in the simulator looks through each in document order until it finds a user with the given username. If the source requires authentication then authentication is attempted. Upon failure the user is returned to the sign-in page. If no user if found in any source the browser will be redirected back to the sign-in page with a suitable message. If the user is found in the source and successfully authenticates if required then a user object is generated and injected into the WAMulator's User Manager container with all available attributes for that user from that store. If a store provides no attributes for the user there will always be one attribute injected automatically by the User Manager; the cn attribute will contain the username of the user unless injected from a store with some other value.

There are two supported sources: XML User Source, and LDAP User Source. Each source is configured via a set of java.util.Properties. The content of the <user-source> element is character content in the java.util.Properties file format with one name=value pair per line. If the complete content minus surrounding whitespace is a macro then it will be resolved prior to loading of the Properties object. The name of each property is literal text. The value of each property can be either literal text, a macro, or a combination of literal text and macros. Property value macros are not resolved until after the Properties object is loaded. Therefore, a property can use a macro to inject the complete contents of an XML file as in the case of the XML User Source.

Attributes

Attribute Name Type Description
type One of xml, or ldap. Provides the set of users that can authenticate via the WAMulator's sign-in page for accessing applications under test fronted by the WAMulator.

<sso-sign-in-url>


To declare URLs that require authentication prior to access by-site's <allow> element is used. When requests are received by the simulator that do not contain a valid SSO cookie the user agent must be redirected to a sign-in page. As of version 5.20 the simulator uses the selectUser.jsp page by default provided at least one by-site element is defined since it must identify the domain of the site that must be used for the browser to correctly get to the page and accept the cookie set by the page. This means that as of version 5.20 this directive is optional. Alternatively, this element can be used prior to 5.20 and afterwar to convey the location of a sign-in page that will allow the user to authenticate, will cause the cookie specified via the <sso-cookie> element to be set for the user, and will redirect the browser back to wherever the user was going. This page must be in the domain of the site although it can be on a different port. If not in the same domain as that of the cookie being set the browser will not accept the cookie. See SSO Simulator Sign-In Pages for the set of available pages that can be declared. See Configure hosts file for SSO for configuring a local development box to have a domain such as local.lds.org resolve to the local machine. Alternatively, localhost.lds.org is mapped by church DNS servers both inside and outside of VPN to resolve to 127.0.0.1. So you can use that for local development without having to modify your etc/hosts file.

Attributes

Attribute Description
value The fully qualified URL of the sign-in page to which the wamulator should redirect for protected resources. May including the console-port or proxy-port aliases.
formAction The action that should be used in the wamulator's sign-in pages for overriding where the form gets posted.

This page was last modified on 31 March 2016, at 14:02.

Note: Content found in this wiki may not always reflect official Church information. See Terms of Use.