LDSTechForumProjects

SSO Simulator Configuration Files

This page covers Version 5.54 and prior versions configuration syntax. See 6.x Config File Syntax and 7.x Main Config file for configuring later versions.

Note: Plea to editors/developers: in the descriptions below as functionality is added and then documented here please indicate in which version of the simulator the feature was added and, if it supports a default value, the version in which that default is applicable. And don't forget to update the DTD. See <config>'s rest-version attribute as an example.


Overview

This document describes the syntax of the configuration file required when starting the SSO Simulator, also known as the WAMulator. The DTD for this document is outlined in SSO Simulator Configuration DTD. 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. Hence a macro pattern is supported and values for such macros are defined using two XML processing instructions. The first and most commonly used one has a name of: “alias”. This instruction defines a key and value pair enabling use of references to such values to be used in multiple places in the document. Prior to version 4.12 this instruction supported only two patterns for defining alias values; literal text and classpath file references.


Version 4.12 added support for system resource aliases whose value is prefixed with "system:". The immediately following characters are the key to a java.lang.System property whose value will be used as the value of the alias with any embedded aliases resolved. Resolving aliases from System properties was intended to support use of conditions during unit tests without requiring use files. Support of the <conditions> element in version 5.20 made this even easier.

Version 5.2 added a fourth, file references which used the java.io.File object to look for the file containing the value for the alias and hence can reference files relative to the runtime directory or fully qualified file paths. Note: Prior to version 5.20's support of the <conditions> element, File referenced macros had to be used for condition files when running the simulator via the executable jar using java -jar since that command does not honor the -classpath parameter and such condition files had to be added to the classpath. With conditions embedded within the configuration file there are no additional external files needed and hence running as an executable jar is perfect for most uses. Alternatively you can start the simulator with the executable jar referenced in the classpath and the class to start specified as with a regular application start up. In this approach you can then include any classpath based alias referenced files on the classpath and use classpath references. In all cases macro references for aliases defined previously in document order can be embedded within the text value of another alias regardless of the source from which that value originated be it text or file.

As already noted, version 5.20 added support for nesting conditions syntax within the configuration file alleviating the need for file references in most cases.

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 both <by-site>'s child <allow> element and <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.

<?alias ...> Deprecated

This processing instruction is deprecated. As noted from its history it supported value prefixes of "system:", "classpath:", and "file:". Such values indicated some other resource whose contents would become the value of the alias. This approach did not support white space in such resource names nor did it support default values in the event the resource was not found. As such it has been replaced by the #<?xxx-alias ...?>|<?xxx-alias ...?>]] commands. Its syntax is as follows:

Listing: Alias/Macro Syntax Defined

 [1] alias := “<?alias ” <name> “=” [<resource-ref> | <classpath-ref> | <file-ref> | +[<clean-text> | <macro>]] “?>”
 [2] name  := <clean-text>
 [3] clean-text  := << any characters except patterns “<?”, “?>”, “{{“, or “}}” >>
 [4] classpath-ref := “classpath:” + << path to file on classpath >> 
 [5] macro := “{{“ <name> “}}”
 [6] resource-ref :=  “system:” + << key of java.lang.System property to use as the value >>
 [7] file-ref := “file:” + << path to file on disk >> 

Examples of valid versions of this processing instruction are:

 <?alias rest-port=1776?>
 <?alias console-port={{rest-port}}?>
 <?alias rest-api={{rest-port}}/identity?>
 <?alias marks-lds-account-id=000111222333?>
 <?alias is-ip-moderator=classpath:is-ip-mod.xml?>
 <?alias is-bishop=system:is-a-bishop?>

<?xxx-alias ...?>

As of 5.32, there are three replacements for the <?alias ...?> command: <?system-alias ?>, <?classpath-alias ?>, and <?file-alias ?>. These replacements allow for white space within values and allow 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"?>
 <?classpath-alias is-ip-moderator=is-ip-mod.xml default="<HasLdsAccountId><LdsAccount id='3431968674741880'/></HasLdsAccountId>"?>

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 “1776/identity”. The fourth instruction uses a classpath file reference. Suppose that the contents of that file contained the following text. What this text means and why it is used will be explained in SSO Simulator Condition Syntax.

 <HasLdsAccountId>
    <LdsAccount id='3431968674741880'/>
    <LdsAccount id='{{marks-lds-account-id}}'/>
 </HasLdsAccountId>

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 the value of the is-ip-moderator alias will be:

 <HasLdsAccountId>
    <LdsAccount id='3431968674741880'/>
    <LdsAccount id='000111222333'/>
 </HasLdsAccountId>

The last alias is only valid in version 4.14+ of the simulator. Any use of the "is-bishop" macro will look in java.lang.System for a property named "is-a-bishop" whose value will then be used as the value of the alias after resolving any embedded alias.

<config>

The root element of the simulator’s XML configuration is the config element. It supports the four attributes defined in the Attributes Table. It also supports a number of nested elements as shown in the Child Elements Table . Note that the type for the port attributes must be an integer or an alias. Aliases are discussed in the section on Aliases and Macros. The rest-version attribute was introduced in version 4.12 along with a new CD-OESv1 REST interface. Prior to 4.12 only the openSSO REST interface was available.

Listing 5: Simple Config to Show Console Pages

<?xml version="1.0" encoding="UTF-8"?>
<config proxy-port="80" console-port="1776" allow-non-sso-traffic="false">
   <console-recording sso="true" rest="true"/>
</config>

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.

Child Elements

Child Elements Description
<console-recording> Specifies that the traffic that is being proxied by the SSO Simulator is to be recorded
<sso-cookie> Specifies the SSO Cookie name
<sso-header> Specifies a header value to be injected into each request as it passes through the SSO Simulator
<sso-sign-in-url> Specifies what url the SSO Simulator will redirect an attempt to access a protected URL for authentication
<conditions> (v5.20+) Allows for embedding condition syntax in the configuration file
<sso-traffic> Main element used for configuring routing to protected or unprotected services
<sso-entitlements> (v4.12+) Element used for configuring rest interface CD-OESv1 entitlements
<users> Allows for configuration of users. Users configured here will be available every time the SSO Simulator starts

<console-recording>

This is an optional child element of config. It is an empty element and supports the attributes shown in the Attributes Table . 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’.

<proxy-timeout>

This is an optional child element of config. It is an empty element and supports the attributes shown in the Attributes Table . 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 running code.

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>

Introduced in version 5.49, this is an optional child element of config but is associated with a change in the way the WAMulator behaves by default when receiving connections from hosts other than the one on which it is running. Prior version 5.49 remote connections were treated just like local connections. version 5.49 now blocks them 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 in the Attributes Table. 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
Introduced in version 5.45, this is an 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. And via nested cdsso elements supports cross domain single sign-on with the <sso-cookie> domain being the master.

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 that generated the response containing the set-cookie header 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.

We can configure the name of the cookie with the sso-cookie element which is an optional child of the config element. It is an empty element and supports the attributes shown in the Attributes Table. The values used to match the cookie used in the nextgen SSO environment is show in Listing: Declaring our SSO Cookie Name and Domain.

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”.

Listing: Declaring our SSO Cookie Name and Domain

<sso-cookie name="lds-policy" domain=".lds.org"/>

<sso-header>

This element supports no nested child elements but does support the attributes defined in the Attributes Table below. This element can be a child element of both the <config> element and the <user> element as noted in the table. As a child of the <config> element it is known as a general-header and is injected with every request. As a child of the <user> element it is known as a user-specific header and is only injected for requests made by that user as identified by a valid cookie for that user passed with the request. This tag is used to simulate the headers that get injected by the SSO Environment.

Attributes

Attribute Name Type Description
name Literal text or Alias The name of a header to be added to a request. If a child of <config> element the header is a global header and will be added to each sso related request passing through the simulator. If the child of the <user> element then the header is only injected for traffic for the corresponding authenticated user as defined by the sso cookie in the request.
value Literal text or Alias The value of the header.

<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 as is done in line 8 of the dual debug page example. 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 localhost.lds.org resolve to the local machine.

<conditions>

As of version 5.20, the simulator allows for embedding condition syntax within the configuration file to facilitate more clear communication between application developers and administrators of the church SSO environment into which their applications will be deployed. Prior to version 5.20, configuration files and condition files all had to be conveyed together. By adding support for embedding condition syntax, a single file can now convey all information needed in the run-time environment. See conditions example which shows both ways of specifying conditions.

This element does not support any attributes but does support from one to many nested <condition> elements which each define a condition alias and its value. Prior to version 5.24 the location of this element was critical and had to be located prior to its sibling <sso-traffic> element which contained references to the condition aliases defined. As of version 5.24 its order is inconsequential. Hence it can just as easily appear above or below the <sso-traffic> element.

Child Elements

Child Elements Description
<condition> See description for element.
<condition>

(V 5.20+ only) Allows for defining an alias whose value is the condition syntax for a single condition rule that can be used to protect resources. See using conditions for an example of how to use this element or convert older constructs to its use. This element supports only one attribute as shown in the Attributes table. All content within this element is mostly opaque to the simulator's configuration parser but must be well formed XML and can include XML comments. Upon loading, the parser only captures nested elements and character content and regenerates these as a single String to be passed into the condition syntax evaluation engine. In doing so it does not distinguish between an empty element like <HasLdsApplication value='sign-in'/> and one that has no content like <HasLdsApplication value='sign-in'></HasLdsApplication> and hence the latter is used. So if exceptions occur and condition syntax is shown in log entries, be aware that empty elements will be expanded to the longer form and this is not an error.

Attributes

Attribute Name Type Description
alias Literal text The name of the alias to be referenced in condition attributes of both <by-site>'s child <allow> element and <entitlements>'s child <allow> element.

Child Elements

Child Elements Description
...condition syntax... Content is opaque to this element but must be valid SSO Simulator Condition Syntax.

<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. The <sso-traffic> tag supports no attributes but its nested elements listed in the Child Elements table are the mechanisms where-by we identify such traffic to the simulator and thereby subject that traffic, both requests and responses, to SSO features. The <by-site> element is for mapping back end applications into a site’s sub-paths. The <by-resource> element has been replaced by the <sso-entitlements> element and is no longer supported. The other two items act on responses as they pass back through the simulator.

Attributes

Attribute Name Type Description
strip-empty-headers "false" Indicates if the proxy should strip empty headers including those injected by the proxy. Defaults to false allowing empty headers to pass through. This was added for a bug in Mark Logic where its get-request-header() and get-request-header-names() fails to see any other headers beyond the first empty header incurred in an http request. Applications should be able to handle empty headers and this feature should not be relied upon as a feature of the full SSO environment once the Mark Logic bug is fixed.

Child Elements

Child Elements Description
<by-site> See description for element.
<by-resource> No longer supported. Use <sso-entitlements> instead.
<rewrite-redirect> Rewrites the Location header in responses from an application.
<rewrite-cookie> Rewrites the path attribute of a set-cookie application response header.

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

<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 in the Attributes table and the child elements listed in the Child Elements table.

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.

Child Elements

Child Elements Description
<cctx-mapping> Routes site requests for a specific path to a back end application.
<unenforced> Specifies unenforced URLs for a site.
<allow> Specifies enforced URLs.

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


<cctx-mapping>

This directive is used to match requests made to the simulator's proxy port and route them to a back end application on a specific host and port and adjust portions of that request if needed. (tpath attribute enables inbound URL rewriting, preserve-host and host-header affect the request's Host header value, and policy-service-url-gateway enables some customization of the injected policy-service-url header.) The cctx attribute indicates which incoming URLs will match. The targeted host and port to which the requests will be proxied are indicated by the thost and tport attributes respectively. Routing will only occur after applying access policies for such URLs defined using the <unenforced> and <allow> directives. The declaration order of cctx-mapping elements is significant. If two cctx-mapping elements have cctx values where one is subsumed by the other then the subsumed one must be declared first in document order, otherwise, an exception will be thrown at load time indicating that the second will never be used since all traffic will be handled by the first declaration.

For example, suppose that we had the following two declarations:

<cctx-mapping cctx='/a/b/c*' thost='127.0.0.1' tport='2000' tpath='/a/b/c*'/>
<cctx-mapping cctx='/a*' thost='127.0.0.1' tport='3000' tpath='/a*'/>

A request for http://host:port/a/b/c/some/resource will match on the first cctx-mapping element and be routed to port 2000 of the local host while a request for http://host:port/a/b/another/resource will match on the second and get routed to port 3000. Now consider reversing the declaration order of these two directives:

<cctx-mapping cctx='/a*' thost='127.0.0.1' tport='3000' tpath='/a*'/>
<cctx-mapping cctx='/a/b/c*' thost='127.0.0.1' tport='2000' tpath='/a/b/c*'/>

In this order both URLs will be matched by the first cctx-mapping directive and no requests will ever be handled by the second. Therefore, when such a situation is detected by the simulator at start-up the simulator will throw an IllegalArgumentException indicating the problem and preventing such erroneous configuration.

The cctx-mapping element does not support any nested elements. Its supported attributes are defined in the Attributes table below.

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 routed to the targeted host and port. Ex: “/temples/*”. This is a prefix match independent of if the URL contains query parameters. The terminating asterisk is required and omitting it will result in error. Additionally, the simulator injects a request header of cctx with the value of this attribute minus the terminating asterisk. This header is used by the SSO client library for Java to facilitate canonical URL generation with its CanonicalHelper class also exposed to JSP and JSF facelets tags via a request attribute of c7l which is short for canonical with '7' representing the number of letters between the letters 'c' and 'l'.
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 The top level sub-path ending with an asterisk that URLs should have when hitting the targeted host and port. In the request passing through the simulator, if this pattern is different from the value of cctx, then it replaces the cctx value in the requests URL thus “rewriting” thereby implementing translation between the canonical and application URL space.
scheme 'http' or 'https' Optional attribute added in v5.45. Defaults to http. Indicates the protocol to be used when connecting to the target host and port. For 'https' 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.
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.

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

<cctx-file>

Applications using the simulator are typically running in isolation on a developer's box. If applications have URL dependencies on other applications chances are good that those applications are not running on the local box. For such scenarios, the simulator allows for responses to requests to be served directly from files on the local box simulating the other application. 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 a separate application developed by a separate group and is not running on the local box. If we can acquire the contents of the AJAX calls using something like firebug we can paste that 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. The cctx-file declaration is the element that enables this 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 The value that should be set for the Content-Type response header when serving the file.
<unenforced>

This element supports only one attribute as shown in the Attributes table below. This element defines URLs that should be allowed through the simulator regardless of being authenticated or not. There is no restriction on the number of such unenforced declarations. Ordering is significant as of v5.15 meaning that if the cpath value matches on a previously declared <unenforced> or sibling <allow> declaration then any URLs being compared against it will be caught by the preceding declaration and will never take effect. If such is detected an IllegalArgumentException is thrown during startup to force minimalistic policies without unnecessary or ineffectual portions.

Ordering of <unenforced> and <allow> elements enables URLs nested within other URLs to have different enforcement applied. For example, I may want "/" to be unenforced but have "/secure/..." restricted to authenticated users. Declaring the second with an <allow> element followed by the first with an <unenforced> element would provide such functionality.

 <by-site host=...>
  <allow cpath='/secure/*' action='GET,POST'/>
  <unenforced cpath='/*'/>
 </by-site>

Note the use of the asterisk wild-card character. There are three wild-card patterns available for use at the end of the cpath value: "*", "?*", and "*?*". If a cpath value ends with "*" then it will match on any additional path but will not match if such a URL has any query parameters. If a cpath value ends with "*?*" then it will match on any additional path that has query parameters. If a cpath value ends with "?*" then it will only match on a URL whose path is the same as that preceding the "?*" characters if it has query parameters.

In the code above the URL, /some/path would be unenforced. But /some/path?a=b would result in a forbidden response after signin in since it does not match on either the unenforced or the allow cpath value. To ensure that it will be allowed the additional entries must be added allowing for query strings to be included.

 <by-site host=...>
  <allow cpath='/secure/*' action='GET,POST'/>
  <allow cpath='/secure/*?*' action='GET,POST'/>
  <unenforced cpath='/*'/>
  <unenforced cpath='/*?*'/>
 </by-site>

Attributes

Attribute Name Type Description
cpath Literal text or Alias Indicates what portions of a site’s subpaths match for this element and should be unenforced. If the value does not contain an asterisk then it is an exact match without query parameters. The asterisk is greedy up to the query string and does not match on the query string when matching in the path. In other words, line 20 will not match on a url of /public/debug.jsp?some-param=some-value. To match on this URL requires a cpath having the form shown in lines 27 and 28 for the <allow> element’s cpath attribute. Line 27 matches on additional path but no query string. Line 28 matches on both additional path and a query string. Both must be present for 28 to match. If the query string is missing then line 27 will match. Line 20 on the other hand will only match on additional path.

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

<allow>

This supports the same cpath attribute of the <unenforced> element and three more as shown in the Attributes table below. At a minimum, URLs matching the cpath of this element require that a user be authenticated before request packets will be proxied to the back end application. If a condition attribute is specified then the user must also meet requirements in the associated file or resource string via the syntax outlined in section SSO Simulator Condition Syntax. As noted, the value of the condition attribute itself must be a classpath-ref, resource-ref, or file-ref alias as defined in Listing: Alias/Macro Syntax Defined that points to the file or resource string. Note: as of v5.15 ordering of <unenforced> and <allow> elements is significant and the first declaration that matches in declaration order is how enforcement for that URL is handled. See <unenforced> for more detail.

Attributes

Attribute Name Type Description
cpath Literal text or Alias Identical to the cpath definition in Table 9 but indicates what portions of a site’s subpaths should be restricted to authenticated users and optionally to user meeting certain conditions. See the definition in that table.
action Literal text or Alias A comma separated list of http methods that should be allowed for that URL or the asterisk character, *, if it should match any method. When specifying a list of methods if the method for a request does not match those in the list then the request will not be forbidden. Methods will only match if they are in upper case.
condition Single classpath-ref, resource-ref, or file-ref Alias An optional attribute that must be an alias matching the production [4], [6], or [7] in Listing: Alias/Macro Syntax Defined above.

See the dual debug page example for a sample of how this element is used. For examples of how to specify conditions see the conditions example.

<entitlements>

(Version 5.17+) Enables declaration of fine grained permissions that can be queried via calls to the REST interface specific to the containing <by-site> element. As of version 5.17 the SSO environment strategy is to have a REST service implementation be bound to only one policy-domain meaning it can only answer fine grained permission queries for policies in a single policy-domain. To accommodate this strategy each declaration of <by-site> gets its own instance that can answer queries for entitlements declared within that <by-site> element. The list of instantiated interfaces is now visible in the Rest Traffic console tab. Additionally, the policy-service-url is now automatically injected appropriately for requests routed through <cctx-mapping> declarations for that <by-site> element. This element does not support any attributes but does support the nested <allow>.

Child Elements

Child Elements Description
<allow> See description for element below.
<allow>

(Version 5.17+) This directive is used to define entitlements or fine grained permissions which are identified by an action, a URN, and the conditions that a user must meet to be granted that action for that URN. Conditions are defined using the embedded <condition> directive as of version 5.20 or via external files. See Aliases and Macros on how to specify external sources of condition syntax.

Attributes

Attribute Name Type Description
urn Literal text or Alias A URN of form "/x/y/z" used to protect a resource within an application like /leader/navigation/calendar-widget. These URNs will usually only be known and used by the application that defines them.
action Literal text or Alias An action or comma separated list of actions for the resource.
condition Single Alias Required attribute that must be an alias for a condition either embedded via the <condition> element or via the production [4] in Listing 8. The contents of this attribute must be a single macro reference as defined in Aliases and Macros. The contents of the alias must conform to the condition syntax defined in SSO Simulator Condition Syntax.
<rewrite-redirect>

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 proxyPassRevers 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>

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.

<sso-entitlements>

Removed in Version 5.17 and replaced with <entitlements>. The comments below only apply to version 4.12 to and including 5.16.

With the CD-OESv1 REST interface introduced in version 4.14 of the simulator there is a distinction made between URLs protected from browser access and resources protected within an application like a widget or region of an html page restricted to users with certain characteristics. Prior to version 4.12 only the openSSO solution was supported and the openSSO REST interface and its implementation provided by the simulator allowed applications to ask if URLs were accessible to the current user. Hence fine-grained permissions and URL access permissions were one and the same. Not so with OES. The arePermitted call implemented in the CD-OESv1 service only answers entitlement questions. The sso-entitlements element and its child element "allow" are used to configure such entitlements.

Policies for entitlements are organized hierarchically in the OES server via URNs. All policy decisions available by the CD-OESv1 service a bound to points in that hierarchy reflective of the domains where those applications will be located like lds.org, ldschurch.org, and mormon.org. Request made to the arePermitted method of the CD-OESv1 must include the domain for their policies followed by the canonical path for the application followed by the resource within that application being accessed and protected. To simplify configuration of such protections in the simulator a domain attribute is specified on the sso-entitlements element and the resource path within the application is specified with the nested allow element.

Attributes

Attribute Name Type Description
domain Literal text or Alias Indicates the domain under which resource policies are stored in the OES server like "lds.org" or "mormong.org".

Child Elements

Child Elements Description
<allow> See description for element below.
<allow>

(Version 4.12+) This allow tag supports any adhoc string since entitlements mimic the OES server and actions are any string that can be defined to represent activities suitable for the resource being configured. If a condition is specified then the user must also meet the conditions specified in the condition’s associated file via the SSO Simulator Condition Syntax. See Aliases and Macros on how to specify condition file locations.

Attributes

Attribute Name Type Description
urn Literal text or Alias Indicates the resource within the application to be granted like /leader/navigation/home.jsf, /mls/mrb/some/path/*, and /scriptures/path/with/query*?*.
action Literal text or Alias A comma separated list of actions defined in the OES server for the resource being configured.
condition Single classpath-ref Alias An optional attribute that must an alias matching the production [4] in Listing 8. The contents of that file must conform to the custom syntax used in the Next Gen SSO environment as defined in Aliases and Macros.

<users>

The final elements left to be discussed from Listing 12 is the <users> tag and its nested child element shown in Table 12, the <user> element. The <users> element declares where user attributes are obtained. If there is no source attribute then nested user elements are the only source of user information. If a source attribute is specifi… TBC Dynamic users versus static users, Dynamic attributes versus static values Which takes precedence?

Child Elements

Child Elements Description
<user> Page 27.

Attributes

Attribute Name Type Description
source (optional) URL of source for user header attributes If included must be the URL of a source that can return XML containing the user attribute values to be injected for SSO policy header. The URL can contain a macro of %%username%% that will be replaced with the user id of the currently signed-in user. Attributes are cached for the duration of the user’s session and reloaded each time they log in.
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.
<user>

Without specifying an external source of user attributes via the <users> element on page 26 the only way to define users that can authenticate in the simulator is by declaring them with the <user> element. Table 14 indicates its only supported child element and Table 15 defines it supported attributes. TBC… 1) why have pwd for external sign-in app for example. 2) Username shows in sign-in pages provided by shim.

Child Elements

Child Elements Description
<sso-header> Used to specify user specific headers to be injected prior to proxying a request to a back end application.
<ldsApplications> Used to specify an ldsApplications value for a user.

Attributes

Attribute Name Type Description
name Literal text or Alias The username of the user.
pwd Literal text or Alias The password of the user if necessary at all. Can be left blank.


<att>

This element supports no nested child elements but does support the name and value attributes defined in the Attributes Table below. This element is a child element of the <user> element. Each occurrence of this element within a <user> element contributes that attribute's name and value to the set of attributes for a user. For attributes that support multiple values, define additional copies of this element with the same name but with each having a corresponding additional value. The <Attribute> condition directive allows for policy and entitlement enforcement based upon this value. Injected values are visible in the simulator's listUsers.jsp console page. Availability:[ coming soon to a wamulator revision near you. :-) ]

Attributes

Attribute Name Type Description
name Literal text The name of the attribute whose value is to be set or whose set of values is to be added to.
value Literal text The value of the attribute or if more than one the value to be added to the set of values for this attribute.
<ldsApplications>

This element supports no nested child elements but does support the value attribute defined in the Attributes Table below. This element is a child element of the <user> element. Each occurrence within a <user> element adds its value to the list of ldsApplications values granted to the user. The <HasLdsApplication> condition test allows for policy and entitlement enforcement based upon this value. This tag is used to simulate the ldsApplications LDAP attribute for users in the OAM/OES environment. Injected values are visible in the simulator's listUsers.jsp console page.

Attributes

Attribute Name Type Description
value Literal text or Alias The value of the ldsApplications attribute.


Previous Page: SSO Environment Simulator

Next Page: Starting the Simulator and Accessing the Console

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

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