Example: dual debug page (SSO Simulator)

Overview and Requirements

NOTE: This example was written for the 5.x version of the wamulator.

The example leverages a debug page that is available in the Simulator's console port to simulate a back end application to which to proxy requests. Assuming that the console port has been set to 1776 in the config element of the configuration file the debug page is accessible to a browser directly at the following link and is shown in the /admin/debug.jsp Page image.
/admin/debug.jsp Page

Listing: Debug page in Simulator

Lets expose that page in a single site at two different URLs. For our site we choose the domain of for our local box. We must choose some domain. Using localhost or will not work since the cookie with domain set by our sign-in page will not be submitted with requests to these non-domain URLs. (See Configure hosts file for SSO for more information on using the host name on your local machine.)

Simulated Site URLs

The two URLs at which we will cause the debug page to appear are shown in the listing URLs for our Site. The first one will be unenforced or publicly accessible without signing in. The second one will be enforced requiring the user to be signed-in before proxying is allowed to the back-end application. Now look at the path in listing Debug page in Simulator and compare it to the paths in URLs for our Site. Since /public and /secure do not match /admin our configuration will also perform request URL rewriting prior to proxying to the back-end debug page. And finally, it will portray the impact of the /* and ?* URL matching patterns.

Listing: URLs for our Site


The configuration that exposes our debug.jsp page at these two paths is shown in Listing: Dual Debug Page Site Example. The line numbers are to facilitate discussion and are not part of the file. Lines 1, 2, and 3 defined three aliases; rest-port and console-port will both have a value of 1776 while http-port has a value of 80.

Line 5 contains our required root element <config> with which we declare on what ports the simulator will listen for the simulated site (the proxy-port) and its own console and rest pages (the console-port). Although this example does not use the console-port-embedded rest service, declaring one is mandatory so we have selected the CD-OESv1 REST interface.

Line 6 tells the console's SSO Traffic tab and Rest Traffic tab to be logging and hence exposing all traffic. The default is to not log. And it indicates that log entries should be limited to 1000 so that we don't grow unbounded and run out of memory. It also records in files on the local hard drive the contents of each SSO traffic request and thence provides links in the SSO Traffic tab to view the full http traffic for each request passing through the proxy-port.

Line 7 defines the name of the cookie that will represent the SSO session and the domain for which it will be submitted. Note that this matches our chosen site domain of

Line 8 is optional for versions 5.20 and later. See SSO Simulator Configuration Files#<sso-sign-in-url>. It is left here for those using older versions of the simulator. It specifies which of the simulator's provided sign-in pages will be used for authenticating users. Note that our chosen site domain is used in conjunction with the port for the console page. This is necessary so that when the set-cookie header is received by the browser after successful sign-in the cookie being set matches that of the domain of the request and hence will be accepted by the browser. Although if desired, a domain of will work as well. However, such a change will require that the value of the by-site element's host attribute (see below) be changed to as well and that be used in the URL in the browser. Support of is useful for unit tests run on build servers where modification of the etc/hosts file is impractical. Note: should already be defined in these situations and testing with this hostname does not require modification to etc/hosts.

Line 9 really is unnecessary for new versions of the simulator since it is injected automatically but it is left in for users of older versions of the simulator.

The <sso-traffic> element starting on line 11 and extending to line 28 defines which requests hitting the proxy-port are considered SSO traffic, how they get routed to a back-end application with or without URLs rewritten, and how they are protected or not. We only have one site being simulated and it is defined with the <by-site> element in line 12. This element dictates what host and port will be looked for in a request's Host header to cause that request to be handled by the <by-site> element's nested directives. The directive in line 12 will match traffic for both and since if no port is included in the host header the simulator understands that port 80 is the default for http traffic.

Routing, Restricting, and Allowing URLs

For site traffic to get routed to a back-end application, there must be a minimum of two directives: a matching directive either <cctx-mapping> or <cctx-file> and a permission directive either <unenforced> or <allow> directive. The matching directive determines who handles the request. The permission directive determines if the request will be handled or not. Without a permission directive that matches for a given request the request will result in a 403 forbidden response.

The first cctx-mapping directive matches any request with a top-level subpath of "/public/". The asterisk character matches on any additional path whether or not a request has query parameters. Any requests matching this directive will be routed to the local machine port 1776 if allowed for by a permission directive. The second cctx-mapping directive matches any request for "/secure/" and routes them to port 1776 as well. Since the back-end application, the debug page, has its resource at "/admin/debug.jsp", the tpath attribute in both directives has "/admin/*" which will cause the portion of the URL that matches the value of the cctx pattern, either "/public/" or "/secure/", to be rewritten, replaced really, with "/admin/" before routing to the the back-end application.

Lines 18, 25, and 26 contain the permission directives. Line 18 uses the <unenforced> directive allowing requests for "/public/debug.jsp" to be routed to the back-end application. Note that there is no asterisk in the canonical path attribute, cpath. This means that the request must match exactly without any additional path or query parameters. If such are included then access will be denied.

Lines 25 and 26 use the <allow> directive. The first allows for any request to "/secure/debug" plus additional path like ".jsp" to pass only after forcing the user to authenticate. If query parameters are include this directive will not match which is different from the pattern matching for the <cctx-mapping> and <cctx-file> directives. For matching a request with query parameters line 26 is necessary. This matches any additional path but also matches any set of query parameters. If a request may or may not have query parameters and both should be acceptable then both lines 25 and 26 are necessary as shown here.

Finally, the <allow> directive distinguishes between allowed and disallowed http methods or accessing the resource. In this case both GET and POST are allowed and all other http methods would result in a 403 forbidden response.


Lines 30 through 37 define a set of users and headers that should be injected for all requests associated with them as a user via inclusion of the SSO cookie. The first user has a preferred language of Russian while the second user has a preferred language of English. The simluator will list these users in its "sign-in" page which really is more of a "select user" page. Upon selecting a user in that page the cookie will be set for that user and requests from then on will be associated with that user.

The Config File

Listing: Dual Debug Page Site Example

 1 <?alias rest-port=1776?>
 2 <?alias console-port={{rest-port}}?>
 3 <?alias http-port=80?>
 5 <config proxy-port="{{http-port}}" console-port="{{console-port}}" rest-version="CD-OESv1">
 6   <console-recording sso="true" rest="true" max-entries="1000" enable-debug-logging="true"/>
 7   <sso-cookie name="lds-policy" domain=""/>
 9   <sso-traffic>
10      <by-site host="" port="80">
11         <cctx-mapping 
12                  cctx="/public/*" 
13                  thost="" 
14                  tport="{{console-port}}" 
15                  tpath="/admin/*"/>
16         <unenforced cpath="/public/debug.jsp"/>
18         <cctx-mapping 
19                  cctx="/secure/*" 
20                  thost="" 
21                  tport="{{console-port}}" 
22                  tpath="/admin/*"/>
23          <allow action="GET,POST" cpath="/secure/debug*"/>
24          <allow action="GET,POST" cpath="/secure/debug*?*"/>
25       </by-site>
26    </sso-traffic>
28    <users>
29       <user name="ngia" pwd="pwda">
30           <sso-header name="policy-preferred-language" value="ru"/>
31       </user>
32       <user name="ngib" pwd="pwdb">
33           <sso-header name="policy-preferred-language" value="en"/>
34       </user>
35   </users>
36 </config>

Running the Example

Create a text file with the contents above. A line-less version is available below. (See Config without Line Numbers). Then download the simulator and place its jar in the same directory as the config file. Assuming a config file name of dualDebug.xml and a simulator jar filename of SSOSim-5.14.jar the simulator can be started with the following line:

java -cp SSOSim-5.14.jar dualDebug.xml

After starting up, point your browser to the first URL in URLs for our Site. You are presented with the debug page at /public/debug.jsp as shown in the Results table below. This page presents all headers and parameters received by the page and is a very useful debugging tool with the SSO environment. Note that in addition to our policy-service-url general header that policy-signin and policy-signout headers are also injected for simulator versions 5.8+.

Now add a query parameter onto the URL or some additional path and see what happens. The browser is redirected to the console port, 1776, to a simulator-provided sign-in page, selectUser.jsp, as shown in SSO Simulator Sign-In Pages. Users defined in our config file are listed and upon selecting one a session is started and the browser is redirected back to the original target, our debug page with the query parameter. And the result for this request with query parameters or even additional path like "/public/debug.jsp/more" is shown in Results below. This "forbidden" page is shown when a users attempts to access a forbidden resource. Note that since the simulator didn't match on an unenforced directive it forced authentication before trying again.

Now select the second link in URLs for our Site. Recall that you are currently signed in if your session hasn’t expired. If it has expired you are again presented with the sign-in page and upon selecting a user you are taken to the secure version of the debug page, "/secure/debug.jsp", as shown in Results. Note the user specific headers that are now appearing due to being injected as the request passed through the proxy port of the simulator. All standard user headers injected by the real SSO environment are known by the simulator and are always injected whether or not they have be declared with an <sso-header> directive within a user. If not declared then they have an empty value. But our declared preferred language of Russian for user ngia (as identified by the cookie value) is indeed being injected. Note also that even when including a query parameter we were taken to the page and the query parameter shows at the bottom as in the figure. This time we weren’t forbidden.

This concludes this example.


URL Description Image
/public/debug.jsp The result of hitting the publicly accessible page without a session.
Resulting View
/public/debug.jsp/more The result of hitting the public page but with additional path which does not match the declaration in line 18 of Listing: Dual Debug Page Site Example.
Resulting View
/secure/debug.jsp The result of hitting the secured page after being authenticated including use of query parameters.
Resulting View

Config without Line Numbers

If you want to copy and paste the configuration for this example into a dualDebug.xml text file using the version below will allow you to do so without having to strip our the line numbers.

<?alias rest-port=1776?>
<?alias console-port={{rest-port}}?>
<?alias http-port=80?>

<config proxy-port="{{http-port}}" console-port="{{console-port}}" rest-version="CD-OESv1">
  <console-recording sso="true" rest="true" max-entries="1000" enable-debug-logging="true"/>
  <sso-cookie name="lds-policy" domain=""/>

     <by-site host="" port="80">
        <unenforced cpath="/public/debug.jsp"/>
         <allow action="GET,POST" cpath="/secure/debug*"/>
         <allow action="GET,POST" cpath="/secure/debug*?*"/>

      <user name="ngia" pwd="pwda">
          <sso-header name="policy-preferred-language" value="ru"/>
      <user name="ngib" pwd="pwdb">
          <sso-header name="policy-preferred-language" value="en"/>

Example with Conditions

If you need to further restrict access to resources by specific user characteristics such a the user's ecclesiastical position you must add into the configuration file conditions. Another example that adds such conditions to what we have done here is also available.

This page was last modified on 11 March 2016, at 17:29.

Note: Content found in this wiki may not always reflect official Church information.