OAM 11g Logout Part One (of two)

This post is part of a larger series on Oracle Access Manager 11g called Oracle Access Manager Academy. An index to the entire series with links to each of the separate posts is available.

In my last two posts on OAM I discussed OAM 11g login and cookies and OAM 11g session management and in both I cover the logout process next.

There's an entire chapter dedicated to the subject of logout in the OAM documentation. The following by no means replaces that chapter. Instead, like the rest of the series of posts, it is intended to give you a simpler to understand recap of the most important points in that chapter in a more understandable form.

To quickly recap what I covered previously: when you log into OAM you get two different kinds of cookies:

• one called OAM_ID one for the OAM servers
• one for each Web Server + WebGate you access (OAM_AuthnCookie_hostname:port)

In addition to those cookies a session gets created in the OAM server cluster's Coherence cache. The simplest way to logout would be to simply mark the session as invalid in the Coherence cache but it would be "better" to clean up all of the cookies in the user's browser.

OAM offers you a few different user interaction flows to log the user out and delete all of the cookies they've been issued by OAM and the WebGates. I don't know if there are official names for these, but here's what I call them:

1. Simple central logout with default final page
2. Simple central logout with custom final page
3. WebGate initiated logout

I'll walk you through all of these options after the break.

Simple central logout with default final page

The simplest form of logout is the one that is included with OAM. To kick this logout process off all you need to do is provide a link to /oam/server/logout on the OAM server. In my test environment the OAM server is reachable at login.oracledemo.com so I have an a href to https://login.oracledemo.com/oam/server/logout. When the user loads that URL three things happen:

1. Terminate the session in the session store
2. Delete the OAM_ID cookie
3. Delete any OAMAuthn cookies (one per WebGate you've used)
4. Show the user a "you've logged out" page

The first two are trivially easy for OAM, and they happen basically as soon as you reach /oam/server/logout. Here's an example:

GET /oam/server/logout HTTP/1.1
Host: login.oracledemo.com
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.0.18) Gecko/2010021717 Oracle/3.0.18-1.0.1.el5_4 Firefox/3.0.18
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Cookie: OAMAuthnCookie=ZALnmUS+w8CtIEXbftDxOPyo2dTu/0Srz4DGpLP/x5ZKcmMPDdPrhQGgzZGRuaxehCkuC4wWMuC5LWc0ttFnoCSY/vWHRmQjkJtFx6OhBQaJ9Yzcvl1sgUazlhU8js3KPsyjpt7yNsXefIXI1HRcrz3zx0DBLIPc8dTUF/2lphSTouDQSiZKl70v2pw+WrTs52SpqNV1La3WbBy0KsWthU+CshDmCOTfRIx9MvhujiOQ0rbJHufHyQEgj9+JUHpPWgpBL5H9f3HYqWNKH2cXQJyBCfubxWjGcsxas52Vkg4R4VUoqL77xVubbeneE8Fo; OAM_ID=Eay3scCS9ouQ0IJPrD25Pve/StVV7IBGoTYgjIf23v9C70Bw2aupGt2LcI7ov8S2l0ZwnvvTPSnE1bnB7OYnBaGa7LfZNTi2ZexCFWEjvO/G9Iys+p7V8CeBsWhB/4g8SFFk0CD2OnYnlKg5POPkPp386uBYv27IMfC+LzG+W/ihQIVwF9gmnQx7wZqfiyw/ZJG256G0vyD3FXY/vMiITUUG+dRlZdlY95jI8Nhy2+e6BePVpgHuKs1pw5/OmvS960Hyqas+KMyzVF9IcVvUmRg40A5ZN2j5BKx0BGh+KPOvwrBwFV+AaDtS6Lqb1k5D

HTTP/1.1 200 OK
Date: Sun, 17 Apr 2011 20:20:52 GMT
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 2356
Content-Type: text/html; charset=UTF-8
Expires: 0
X-ORACLE-DMS-ECID: 11d1def534ea1be0:7169714a:12f595119e5:-8000-0000000000002b9d
X-Powered-By: Servlet/2.5 JSP/2.1
Set-Cookie: OAM_ID=; path=/; HttpOnly; expires=Thu, 01-Jan-1970 01:00:00 GMT
Connection: close

You can that the HTTP response contains a Set-Cookie to remove the OAM_ID cookie. But how does the OAM server tell the browser to delete any of the OAMAuthnCookies which individual WebGates may have issued?

The trick is a bit of HTML and Javascript in the page that the OAM server serves up when you start a logout. When you first load /oam/server/logout you will see a page that looks like this:

The clock is an animated gif that spins while something happens. But what?

    <BODY>
        <FORM NAME="RedirectForm" METHOD="GET" ACTION="/oam/pages/logout.jsp">
        </FORM>
        <CENTER>
            <BR/>
            <IMG src="/oam/pages/images/wait.gif" border="0" ALT=""/>
            <BR/>
                    <img border=0 width=0 height=0 src="https://app.oracledemo.com/oam_logout_success" alt ="" 
                        onload="imageLoadedHandler()" onerror="imageErrorHandler()"/>
...            
        </CENTER>
    </BODY>

What's happening here is that the OAM server is telling your browser to load an image from each WebGate. When you load that image the WebGate has an opportunity to delete your cookie... and it does just that:

GET /oam_logout_success HTTP/1.1
Host: app.oracledemo.com
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.0.18) Gecko/2010021717 Oracle/3.0.18-1.0.1.el5_4 Firefox/3.0.18
Accept: image/png,image/*;q=0.8,*/*;q=0.5
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Referer: https://login.oracledemo.com/oam/server/logout
Cookie: OAMAuthnCookie=ZALnmUS+w8CtIEXbftDxOPyo2dTu/0Srz4DGpLP/x5ZKcmMPDdPrhQGgzZGRuaxehCkuC4wWMuC5LWc0ttFnoCSY/vWHRmQjkJtFx6OhBQaJ9Yzcvl1sgUazlhU8js3KPsyjpt7yNsXefIXI1HRcrz3zx0DBLIPc8dTUF/2lphSTouDQSiZKl70v2pw+WrTs52SpqNV1La3WbBy0KsWthU+CshDmCOTfRIx9MvhujiOQ0rbJHufHyQEgj9+JUHpPWgpBL5H9f3HYqWNKH2cXQJyBCfubxWjGcsxas52Vkg4R4VUoqL77xVubbeneE8Fo; OAMAuthnCookie_app.oracledemo.com:80=Or1CRVLW%2FKrEtmm%2Bebu9TPM8gg3oK4PM5PGFnK4m%2F9Q9JccW2EaZQRlNg7hyC9x5r0JCl00qH%2FreUjUjTEbnN9HiMr8cmUUKrwOF00UcRmz00%2BY6d7B4HwAXq41GtnnI8GbwGGXoqIz5a%2FFb0aG0hl2%2BzC2l0INw7iVs%2BJTVpwXILQgBRVW0Vz9SEBNdEEPmIxz%2FYDylN%2FNYMTx9UWhJer0uDQIVHk8IgHCgK5qLlV%2BP%2FFpiP6vFu6PAut0cGXj9TNR3WOCpZP4%2BDR11uhvIW5J%2BVX%2BG81T64G8aWuq%2BRk7F0qXLPlDFO4hb3UKIwyvq

HTTP/1.1 200 OK
Date: Sun, 17 Apr 2011 20:20:52 GMT
Server: Oracle-Application-Server-11g
Pragma: no-cache
Expires: -1
Cache-Control: no-cache, no-store
Content-Type: image/gif
Set-Cookie: OAMAuthnCookie_app.oracledemo.com:80=;expires=thursday, 01-jan-1970 01:00:00 gmt; httponly; path=/;
Connection: close
Transfer-Encoding: chunked

The image file itself is a checkbox, but you never actually see it because the height and width are zero pixels. When the picture finishes loading the JavaScript onload event fires and a counter is incremented. When the counter reaches the expected number of images (again one per WebGate that has issued you a cookie) the JavaScript function sends you on your way to the default final page - /oam/pages/logout.jsp which looks like this:

The actual URL of the hidden image is a configurable value called the Logout Callback URL. By default OAM Server will construct the URL for the hidden image as http:// or https:// followed by the DNS name it redirected the user to when they logged on, followed by the string in the Web Agent's Logout Callback URL setting, which defaults to "/oam_logout_success". You can change this behavior by putting a different string in the setting (I prefer /oam_logout_callback). If you find that the OAM Server is using the wrong hostname for the redirect you can provide an entire URL - just enter the entire URL beginning with http or https in the field.

Simple central logout with custom final page

For most OAM customers the flow and user experience above probably meets 99% of what you want - if only you could change that final page. Of course we anticipated that!

Instead of linking to /oam/server/logout just like to /oam/server/logout?end_url= and add on the (URL encoded) URL you want the user to go to when logout is complete.

So for example if you want the user to go to https://app.oracledemo.com/logoutcomplete.html after logout you would link to /oam/server/https%3A%2F%2Fapp.oracledemo.com%2Flogoutcomplete.html

When you do that the flow is exactly the same as above - the OAM_ID cookie gets deleted, the user sees the little spinning clock, all of the OAMAuthnCookies are deleted, but at the end instead of being redirected to /oam/pages/logout.jsp the user gets redirected to the URL you specified in end_url.

So if that's all you want to do you should stop here. There's no reason to go further.
Seriously.

WebGate initiated logout

The alternative to the above flow is to have a URL on the WebGate kick off logout. That process builds on top of the above flows and I'll discuss that in another post soon.