Troubleshooting SSO Traffic - the Console
When things go wrong... :-)
The WAMulator is an http proxy that enforces access policies. But via its http console it is also meant as a tool for you to see the http requests hitting your application including WAMulator injected headers. See Column 9 Requested Path below for more detail. (Note: clicking on any of the console images below shows a larger version of that image)
- 1 Simulator Console
- 2 Accessing the Console
- 3 SSO Traffic Tab Features
- 4 Summary
The WAMulator listens on two ports specified via the configuration file's <config> element. (See the figure on SSO_Environment_Simulator.) The proxy-port is the port used to simulate some internet site (ie: your application and the WAM environment fronting it) by acting as a reverse proxy and passing traffic onward to back end applications as instructed via the configuration file constructs. The console-port is an application fulfilling two functions. First, it provides an implementation of the CD-OES Rest Service used by applications for fine-grained permissions.
The second function provided is a browser accessible console with several tabs. The Users & Sessions tab exposes the configured set of users and any currently active sessions based upon users signed-in via a simulator sign-in page. The SSO Traffic tab exposes all requests passing through the proxy port that represents the simulated site. The actual http traffic for each such request is also available if configured appropriately. The Rest Traffic tab exposes all http requests made of the CD-OES Rest Service and the returned responses.
These last two tabs are indispensable troubleshooting aids when attempting to track down problems with your use of the WAMulator to simulate the WAM (SSO) environment. For example, take a moment to get the dual debug page example running. Notice on line 6 that we have turned on recording for both the SSO Traffic and Rest Traffic tabs and restricted the number of entries kept to 1000 before having newer traffic overwrite older entries in the queue. More importantly, we have set enable-debug-logging to true. This causes each http request/response cycle passing through the proxy port to be logged to file and be accessible via a link in the SSO Traffic tab. Lets give this a try.
Accessing the Console
Access the console by pointing your browser to http://localhost:1776/. This will redirect to the Users & Sessions tab. Select the SSO Traffic tab. If you have just started the WAMulator prior to going to this tab and have not yet attempted access of the simulated site URLs then the contents of the tab will appear as shown in the following image.
Listing: SSO Traffic Tab prior to any proxy port traffic
In a different browser or tab select the first of the two site URLs. Then go back to the SSO Traffic tab and refresh the browser. The tab now appears as shown in the following image.
Listing: SSO Traffic Tab after hit to /public/debug.jsp
SSO Traffic Tab Features
In the image at right we see the results of our request to /public/debug.jsp. But the traffic shows two calls passing through the proxy. Browsers often hit a site that they have not hit before with an additional request for the favicon.ico resource. This is the small icon that browsers often place on the tab in their interface holding the content for a site and also in the address bar of the browser.
Second, each column in the page generates a pop-up when the mouse is placed over it giving an indication of the contents of that column. Here is how each column is identified and what it means. Note also that the last column showing the resource that was requested is actually a link. This link allows you to see the http traffic for that request. See Column 9 Requested Path below for more detail.
Column 1: Request Timestamp
This first column is the request timestamp which is the timestamp of when the traffic passed through the simulator. Note that the newest request is a the top of the screen. Older requests are further down. Hence why our request for the debug page is at the bottom of the list.
Column 2: Connection ID
This column indicates the simulator connection id for a request/response conversation. For each request passing through the simulator a header is injected into both the incoming request passed onward to the back end application and into the response passed back to the browser. If your browser shows the headers received for a particular response you can see this header and its value. It is the X-connId header and it corresponds to the value of this column for that request/response conversation. You can also see this in the http traffic content accessed from this tab as described below. [TBD]
Column 3: User Name
This column holds the username of the user represented by each request as identified to the simulator by the cookie included with the request. We haven't signed-in yet so the ??? and the pop-up indicate there was no simulator cookie in these requests. Upon signing-in, the value shows the username of the user and the pop-up indicates that this is a cookie user.
Column 4: Response Source
This column contains a P or a - character. The pop-up for each indicates simulator response code or server response code respectively indicating the source of the http response and its corresponding http response code shown in column six is the proxy itself or the back end application.
Column 5: SSO vs. Non-SSO Traffic
This column will always contain a dash character, -, unless the simulator is also being used as a forward proxy by a browser. Forward proxying is where a browser is told not to go to web resources directly but to go through a proxy in situations such as being located on an internal network and not having a direct route to external internet resources without using a proxy. Forward proxying is disabled by default in the WAMulator. To enable it you must firt tell the proxy to allow forward proxying by setting the allow-non-sso-traffic attribute of the config element to true and then configure your browser to use the WAMulator's proxy port as its proxy. Upon doing so, any traffic to hosts other than those declared via your by-site elements will now be allowed through the proxy and will be accessible in the SSO Traffic tab. Without allowing such traffic the simulator will reject such requests returning the response shown in the following image.
Listing: Browser Page After Attempting Disallowed Forward Proxying
When any non-sso-traffic passes through the proxy, whether allowed or not, this fifth column will contain an exclamation mark character, !, thus making non-sso-traffic readily distinquished from sso traffic. Note the attempt to go to www.google.com with FireFox configured to use localhost port 80 for its proxy but our current configuration not including the allow-non-sso-traffic attribute in our <config> element on line 5 of our configuration file.
Column 6: HTTP Response Code
This column shows the http response code of the response sent to the browser for that request. The pop-up in this case gives the http message generally associated with that response code as defined in RFC 2616 section 10. An exception to this rule is when the proxy is the source of the response as noted by a P character in column four. When the proxy provides the response the message is altered to give some indication as to why the proxy returned that response. For example, the requests for /favicon.ico resulted in response codes of 501. The pop-up shows the message CCTX-MAPPING Not Found in config file. If you point your browser to this URL directly via this link, http://localhost.lds.org/favicon.ico you'll receive a page similar to that in the image below. This indicates that no <cctx-mapping> element for our by-site host of localhost.lds.org matched the "/favicon.ico" path and hence the proxy did not know where to route the request. Hence the response.
Listing: Path for Configured host Request Did Not Match a cctx-mapping
Columns 7 & 8: HTTP Method and Host Header
The 7th column indicates the http method of the request while the 8th column indicates the content of the request's Host header. The Host header is used by the proxy to match a request with a specific <by-site> directive this associating such a request with SSO traffic and causing other directives to be applied to enforce access and inject headers.
Column 9 Requested Path
This column shows the request URI of the http request's request line as defined in RFC 2616 section 5.1.2. With enable-debug-logging of the SSO Simulator Configuration Files#<console-recording> element set to true, these URIs are links. Selecting that link will expose the contents of the http traffic for that transaction as outlined on Troubleshooting: Deciphering Http Traffic Detail
The SSO Traffic tab in the Simulator's console should usually be the first place to go when you have problems running applications behind the WAMulator. It provides clarity as to how many redirects occurred, if responses were from the simulator itself or from the back end applications, and even if traffic his the simulator at all as manifest by that traffic NOT appearing in the SSO Traffic tab. And the further details available in the http content payload exposes what header values were injected and passed to those applications. So put it to use for you.