OAM 11g Single Sign-On and OAM 11g Cookies

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.

Our compatriot Eric Leach over at the Oracle Access Management Blog wrote a post describing how SSO works in OAM 11g. It's a great post and fills in all sorts of details about the cookies used, how they're named and how all of the parts fit together. OAM 11g supports a few different PEPs - OSSO, OAM 10g and OAM 11g and Eric discusses them all.

but...

I find a pretty picture much more understandable than a great big blob of text. Part of it is that I'm more of a visual person and part of it is that I tend to get distracted easily. Plus if you're already familiar with OSSO or OAM 10g you probably already know what their cookies look like. So for the purposes of this post I'm only going talk about OAM 11g Server and the 11g WebGate cookies when you do an "HTML form" style login.

Basically if you want the contents Eric's post in pretty pictures and simplified down to include only the 11g cookies then this post is for you!

Here's a very simple diagram of the communication between the user, one OAM Server, one WebGate and one Application:

Note: In this diagram I've separated out the WebGate and the Application, though in reality the WebGate is plugged into the OHS Server and the app could be something as simple as a .CGI running in the same server. I've also shown the user talking directly to the OAM Server; in the real world this interaction would likely be through an OHS server with mod_wl installed.

Before we jump into the actual flows here's a little UML-ish sequence diagram for those of you that love those sorts of things:

And the OAM docs have a GREAT diagram that covers the flow:

When the user first attempts to access a protected resource the WebGate will detect that the resource is protected and that the user needs to be redirected to the OAM Server to login. The WebGate stores some information about the user's request, generates a cookie as a key to this context and sends an HTTP response with this cookie and the URL of the OAM Server. Here's a sample:

GET /protected/ HTTP/1.1
Host: idm11g.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

HTTP/1.1 302 Found
Date: Sun, 10 Apr 2011 21:39:34 GMT
Server: Oracle-Application-Server-11g
Location: https://login.oracledemo.com/oam/server/obrareq.cgi?encquery%3DvAdYBjjl2VsVKd4BUocWvKLrTgh7O%2FulOsfaTcOtj%2FHCW0jI0WaKRY%2BUklaoED8x6IQ%2FtnktpR%2FNN2NvsLZJb3wTyUomlOxQgqX59aRla2LTQUIBsbO4Tw5PlFFsgDYdWoUUAA6HHTU4P1ZyloMzcbqn4mtXK6t5CAbOvEuB787m0VKOCPhvaO5OEibx5MEYtW1P0b1nqOeAlMUQdA6dg7BW8PbjgI7Ek3Esy4yJJN2EUBw90%2BjAJzLgQMUxtd%2FOc%2B6q60WFnZEMyRlmJW7moeoyPbMnookrb22WEd8pTsQ%3D%20agentid%3Didm11g%20ver%3D1
Content-Length: 608
Content-Type: text/html; charset=iso-8859-1
Set-Cookie: OAMAuthnCookie_idm11g.oracledemo.com:80=loggedoutcontinue;httponly; path=/;
Set-Cookie: OAMRequestContext_idm11g.oracledemo.com:80_316f33=1o3lYFHrBi/OSAW5bGkEgA==; Expires=Sun, 10-Apr-2011 21:44:34 GMT; path=/;
Connection: close

If you look in the HTTP response above you'll see 2 Set-Cookie headers - one deleting OAMAuthnCookie_something (well setting it to loggedoutcontinue) and another named OAMRequestContext_something with a short key. Don't worry about the former for the moment; the latter is how the WebGate can get back to the original request later.

The browser then follows the redirect and loads obrareq.cgi from the OAM Server. Despite the name obrareq.cgi isn't a CGI. The name is historical and we kept it for a few reasons, none of which really matter for this discussion.

When the user requests obrareq.cgi the server responds with another redirect - this time to the HTML login form defined in the Authentication Scheme. Here's my Authentication Scheme configuration:

and here's the HTTP transaction when the browser requests obrar.cgi:

GET /oam/server/obrareq.cgi?encquery%3DvAdYBjjl2VsVKd4BUocWvKLrTgh7O%2FulOsfaTcOtj%2FHCW0jI0WaKRY%2BUklaoED8x6IQ%2FtnktpR%2FNN2NvsLZJb3wTyUomlOxQgqX59aRla2LTQUIBsbO4Tw5PlFFsgDYdWoUUAA6HHTU4P1ZyloMzcbqn4mtXK6t5CAbOvEuB787m0VKOCPhvaO5OEibx5MEYtW1P0b1nqOeAlMUQdA6dg7BW8PbjgI7Ek3Esy4yJJN2EUBw90%2BjAJzLgQMUxtd%2FOc%2B6q60WFnZEMyRlmJW7moeoyPbMnookrb22WEd8pTsQ%3D%20agentid%3Didm11g%20ver%3D1 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

HTTP/1.1 302 Moved Temporarily
Date: Sun, 10 Apr 2011 21:39:34 GMT
Location: https://login.oracledemo.com/oam/pages/login.jsp?request_id=8909287934039423969
X-ORACLE-DMS-ECID: 11d1def534ea1be0:-4189cb25:12f40a0ec71:-8000-000000000000169c
X-Powered-By: Servlet/2.5 JSP/2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain; charset=UTF-8

Notice the "?request_id=" and a key? When the user requests obrar.cgi the OAM Server squirrels away the request information and generates a short identifier to remember the user's request. The value of request_id is how the OAM Server gets back to the original request information when the user POSTs their credentials.

Next, the user loads the login page (/oam/pages/login.jsp in this example).

GET /oam/pages/login.jsp?request_id=8909287934039423969 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

HTTP/1.1 200 OK
Date: Sun, 10 Apr 2011 21:39:34 GMT
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 3201
Content-Type: text/html; charset=UTF-8
Expires: 0
X-ORACLE-DMS-ECID: 11d1def534ea1be0:-4189cb25:12f40a0ec71:-8000-000000000000169e
X-Powered-By: Servlet/2.5 JSP/2.1
Connection: close

Finally! an HTTP 200 and we're done following redirects for a moment. This is the point where the user sees a login page. In this example I configured my Authentication Scheme to use the default JSP login page included with OAM. I'm sure you've seen it before, but that login page looks like this:

OK, so the user enters the username and password and hits the Login button. The browser does an HTTP POST to /oam/server/auth_cred_submit. Like so:

POST /oam/server/auth_cred_submit 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
Referer: https://login.oracledemo.com/oam/pages/login.jsp?request_id=8909287934039423969
Content-Type: application/x-www-form-urlencoded
Content-Length: 66
username=testuser&password=ABcd1234&request_id=8909287934039423969

HTTP/1.1 302 Moved Temporarily
Date: Sun, 10 Apr 2011 21:39:41 GMT
Location: https://idm11g.oracledemo.com/obrar.cgi?encreply=aHRPbw8cp0LjIHx9Dd6DaT1kcHzmbIUudciQui%2F7lC52miYo77nRNh8JtH1UKeJ5O%2B12QyAcNlEES0TFZW7zQ%2FtCnh9PKFD%2B1y%2BGLYsEbnfHrsnqFmT4R%2F15b8kGdSyUP5TatLW6X4oAc9B2n9qPF3YBPlwHK7rRXMmhKleJa6X%2FjSWB%2Ff3YeWz1xrGidkvUXekC75Kldmu%2FL6O9jgbxk0tksCTjumZINMFOREUjrBFdCIGNDJlKiXeqBPMMccQXp5gg%2Fh5gT2s7wycJeAgyNxSH75%2FiYb9fC4tlo3aNB8bQ0ExpUSx8%2BTdOTf%2B1CpCv8Ue%2BESOoxEJYCVeQ248Omjmj%2B2UML0A%2F3KvWZjSHJY%2FTaleo3mzVG64lbdJGGsp8cXpbwK6MNZEtS6aDPdq4rgmNNAhnJ8bvmIUrlm3FfFp66anpYkvSUCORoaN991YwgZ5tOQ5p%2BZqN6O9qL5T7XUS7HWPwixEy0zH1CHDrQzmf0GaN9x4BfY3EdyGVQIh04Sf2V3Tf3r3cF4aW6xJuNMiu24kZYJ3tF8%2BjmdAmb3GoXtwOrCOUcSc%2FKV9%2F4oIBoZH6b5GW047VF5NGgNfM17I0J%2Fe1epQE2%2Bs0iLXlBu0IhFkaYiyDI2dl8CXohgeoTjOD74EeZFBcDMZHAYEVNjfZg2BuTNn7qaUTJkUztbM%3D
X-ORACLE-DMS-ECID: 11d1def534ea1be0:-4189cb25:12f40a0ec71:-8000-00000000000016aa
X-Powered-By: Servlet/2.5 JSP/2.1
Set-Cookie: OAM_ID=PvUkA907xd81Jv/P53npTW0JOSDTacc3jdGiL3tMB87z/RfZP91Bh2dQmM8v71rQTCZnJ1isOaQeJw8dSjfo7kXMFA8URsmL9uiszpOQYEH7SuvHVr1IjVRY3pPAlYhUrfLwEW5lvKMY9MF3KYTzvfuUJLMKZb0sc70KxdmXcnJrAFOSVMALhUEaUVOTZVI3aQCqEVmdnkh0QlSBkz9tsqxE0/VTacEnhPg2DlPxC9uKnElAsByo+8wczYlBemiyMR9g0BWasN+uR4TMo9pLtky/B0TmA43uOQuFvItW6twFJH3wSu6XofKo/Cy4bS0i; path=/; HttpOnly
Connection: close
Transfer-Encoding: chunked
Content-Type: text/plain; charset=UTF-8

The OAM Server validates the username and password ("testuser" and "ABcd1234" in this case) and since they're correct it generates an OAM_ID cookie. This is the first cookie we've seen so far that identifies the user! If you look carefully you'll notice a couple of interesting things about the cookie: The first is that it doesn't have a domain= setting; as a result the OAM_ID cookie will only be sent by the browser to the OAM Server; no WebGates will ever see the OAM_ID cookie. The second interesting thing to notice is that the cookie is marked "HttpOnly"; the HttpOnly marker tells the browser that the cookie should NOT be accessible to Javascript or browser plug-ins.
(note: in an earlier version of this post I accidentally said "host=" instead of "domain=". My apologies for the error!)

The OAM Server redirects the user back to obrar.cgi (this time on the application) with encreply= and a big long encrypted string. The encreply that the OAM Server includes in that redirect contains enough information to allow the WebGate to pick up the user's session from the OAM Server. And so it does:

GET /obrar.cgi?encreply=aHRPbw8cp0LjIHx9Dd6DaT1kcHzmbIUudciQui%2F7lC52miYo77nRNh8JtH1UKeJ5O%2B12QyAcNlEES0TFZW7zQ%2FtCnh9PKFD%2B1y%2BGLYsEbnfHrsnqFmT4R%2F15b8kGdSyUP5TatLW6X4oAc9B2n9qPF3YBPlwHK7rRXMmhKleJa6X%2FjSWB%2Ff3YeWz1xrGidkvUXekC75Kldmu%2FL6O9jgbxk0tksCTjumZINMFOREUjrBFdCIGNDJlKiXeqBPMMccQXp5gg%2Fh5gT2s7wycJeAgyNxSH75%2FiYb9fC4tlo3aNB8bQ0ExpUSx8%2BTdOTf%2B1CpCv8Ue%2BESOoxEJYCVeQ248Omjmj%2B2UML0A%2F3KvWZjSHJY%2FTaleo3mzVG64lbdJGGsp8cXpbwK6MNZEtS6aDPdq4rgmNNAhnJ8bvmIUrlm3FfFp66anpYkvSUCORoaN991YwgZ5tOQ5p%2BZqN6O9qL5T7XUS7HWPwixEy0zH1CHDrQzmf0GaN9x4BfY3EdyGVQIh04Sf2V3Tf3r3cF4aW6xJuNMiu24kZYJ3tF8%2BjmdAmb3GoXtwOrCOUcSc%2FKV9%2F4oIBoZH6b5GW047VF5NGgNfM17I0J%2Fe1epQE2%2Bs0iLXlBu0IhFkaYiyDI2dl8CXohgeoTjOD74EeZFBcDMZHAYEVNjfZg2BuTNn7qaUTJkUztbM%3D HTTP/1.1
Host: idm11g.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
Referer: https://login.oracledemo.com/oam/pages/login.jsp?request_id=8909287934039423969
Cookie: OAMAuthnCookie_idm11g.oracledemo.com:80=loggedoutcontinue; OAMRequestContext_idm11g.oracledemo.com:80_316f33=1o3lYFHrBi/OSAW5bGkEgA==

HTTP/1.1 302 Found
Date: Sun, 10 Apr 2011 21:39:41 GMT
Server: Oracle-Application-Server-11g
Location: /protected/
Content-Length: 209
Content-Type: text/html; charset=iso-8859-1
Set-Cookie: OAMRequestContext_idm11g.oracledemo.com:80_316f33=; Expires=Thursday, 01-Jan-1970 01:00:00 GMT; path=/;
Set-Cookie: OAMAuthnCookie_idm11g.oracledemo.com:80=BSMcTDP6bI93Nv7mrpH77ESezwe9OJJEvlB3Y7Bir3%2FrcwvB8j8xZj2tc0mzQKUJYfNEjnRB%2BJWg3EQw%2BAei51dq7IhVJQ4xZhfv9eKqB1f0BMwc%2BOMt9ADJ7wZ47rGqEp85DYTRIeXPE6wMSJMkRFIvEzh2zKmeZoBv7x2G2DsepKXwAsgv2OZqmXvISu4gzDweUbcY6N8%2B4KuYAqCd1FAHO6aMKlj6ak05cdAVtzGXBcc3y%2FdRW1Yhjer9oZEBBcW73e9uhrfwOq6lZHE0BHoPZT5YWrXQRUJH3VBxj7gPAMQASwQh6wUyvvC%2BN4Zm;httponly; path=/;
Connection: close

This is the second cookie we've seen that identifies the user. Again, this cookie is host-specific and HttpOnly. There's another interesting thing about the cookie - notice the cookie name "OAMAuthnCookie_idm11g.oracledemo.com:80"? The WebGate figures out the cookie name automatically.

The user follows the redirect back to the original resource - /protected/.

GET /protected/ HTTP/1.1
Host: idm11g.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
Referer: https://login.oracledemo.com/oam/pages/login.jsp?request_id=8909287934039423969
Cookie: OAMAuthnCookie_idm11g.oracledemo.com:80=bQ%2Bx9MCKyEjON3nOt5d7niWgbSEksG4qCEPaGF82blgf76HBAgmnEy3gkGoPzTBs8Ac1zTBNSnvHS8EmubYuZR0I4spgrchEtuuKdKJHPkWXQg9S1RRoycAys%2F8GDa6rRbvWJNRFc11yfK0X3g3Buxb6MvpDmsEGraleqKtdBSjtRG1PS8zl4Mijd7Tu1a3NFMgONgdoHKnoNyF3T13HjFbILIvLVuTdjE6t9EyomX4XXijXxqUZtTrZB%2BjRzy3jVLUeKKHhcNn7CTZrKhMJYtDVd8Z4d34vyyGgE%2BlJd%2BdkKGQr1sstpfpVVlyivvo4

HTTP/1.1 200 OK
Date: Sun, 10 Apr 2011 21:39:41 GMT
Server: Oracle-Application-Server-11g
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/html; charset=ISO-8859-1
Content-Language: en
Connection: close
Transfer-Encoding: chunked

So a quick summary:

• The OAM Server gets and sets a cookie named OAM_ID.
• Each WebGate gets and sets a cookie named OAMAuthnCookie_ + the host name and port.

Eric gave a couple of other details about the OAMAuthnCookie -

the contents of the cookies are:

• Authenticated User Identity (User DN)
• Authentication Level
• IP Address
• SessionID (Reference to Server side session – OAM11g Only)
• Session Validity (Start Time, Refresh Time)
• Session InActivity Timeouts (Global Inactivity, Max Inactivity)
• Validation Hash

These cookies are updated periodically using an algorithm of 1/4 of idle session timeout. There are two main differences between the 10g and 11g cookies:

Eric also mentioned that the 11g OAMAuthnCookie is encrypted with a key that is specific to the Webgate that issued the cookie. That means that if someone somehow compromises one web server and gets a copy of the OAMAuthnCookie for that server it isn't useable on any other web server and WebGate.

One other note: Because the OAMAuthnCookie is a "per host" cookie and the only communication channel in the redirects is the obrar.cgi URL single sign on works across domain names. So in my case I have both the OAM Server and the application in .oracledemo.com, but I could just as easily have them in two completely different domains. Like oracle.com and oracleateam.com.

In the next post I'm going to talk about how logout works so stay tuned!