Tuesday, October 14, 2014

Part 2: Custom Login and Logout with Detached Credential Collector (DCC)

INTRODUCTION

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 Part 1: Getting under the covers of Detached Credential Collector (DCC), I spent time talking about DCC in general and walked through a sequence diagram explaining what is happening with DCC, to try and explain how it works including contrasting it with ECC. So in this blog, Part 2, I want to expand into a more practical angle on the requirements of a totally custom login and logout. Creating a custom login and logout does not require the Perl scripts login.pl or logout.pl, though these are perfectly great options and can also be customized. If you do want to take the route of using the OAM out-of-the-box Perl scripts you can find more information about it and its implementation in the Oracle Developer Guide for OAM 11g (11.1.2) in section 4.4 Developing User the Detached Credential Collector or see Debasish Bhattacharya’s blog article Detached Credential Collector Configuration --- OAM 11gR2. Moving forward, and as promised, I am going to guide you on how to create a totally custom login and logout using DCC without requiring any hardcore developer skills --- I promise.

MAIN ARTICLE

Getting Started

To keep everything less confusing I am going to break out two main sections of this blog into the “Login” and “Logout”. I will provide enough detail for you to gain the knowledge of making a functional customized login and logout. The operative word is “functional”, which basically means I will show you the mechanics on how to make it work, but it is up to you to add the bling. Fair enough? So let’s get started.

How to Create a DCC Custom Login

Though DCC will work with several types of authentication schemes I want to keep everything simple so we can understand the basic concepts. Form Login is one of the most common types of authentication customers use, so this is a good one to cover. I want to cover a simple Custom Form Login authentication scheme, which coincidently is similar to an External Form Login authentication scheme. This should help understand the concepts and then give the foundation on how to expand into other authentication scheme options.

STEP 1: The DCC Custom Form Authentication Scheme Requirements

The foundation is to start with the authentication scheme itself. A good way to understand our authentication scheme for DCC is to compare how it is configured versus the OOTB (Out-Of-The-Box) ECC form authentication scheme. The table below compares the two authentication schemes and includes each parameter with some examples. I have highlighted DCC parameter values in red that stand out from ECC, so pay attention to the highlighted values; more details on the highlighted parameters coming up.

  Table 1 - DCC Custom Form Authentication Scheme Comparison
Authn Parameter ECC Authn Scheme DCC Authn Scheme
Authentication Level 2 2
Challenge Method FORM FORM
Challenge Redirect URL  /oam/server https://dcc_hostname: port e.g. https://sso.melander.us
Authentication Module <Select a Module> <Select a Module>
Challenge URL /pages/login.jsp  <Relative DCC Login Page URI> e.g. /sso/login.html
Context Type  default  <select blank>
 Context Value  /oam  <Not Available>
 Challenge Parameters  <empty>   <empty>

 As an additional visual aid I am including a screenshot of a DCC Custom Form Authentication Scheme from the OAM Console. You can compare the configuration in the screenshot to the table above to solidify how the scheme is defined and how it varies from a Form Login using ECC.

  Figure 1 – Example DCC Custom Form Login Authentication Scheme


Getting into the details of DCC vs ECC Authentication Scheme differences

I wanted to expand a little more on the more critical parameters that I highlighted in red to understand why the values are set that way and how you may want to change some of them for your own needs.

Challenge Redirect URL

The Challenge Redirect URL must hold the URL that includes the hostname and port of the DCC WebGate. In a High Availability (HA) configuration, the hostname would be a virtual IP of the load balancer, and of course the load balancer would then send requests back to all the DCC WebGate hosts. In my example sso.melander.us is the hostname of my DCC WebGate, and therefore in my case the actual value for this parameter is https://sso.melander.us. This is a big contrast from ECC because with ECC the hostname dynamically comes from the Access Manager Settings > Load Balancing > OAM Server Host and OAM Server Port values. I have mentioned this before, but to recap the reason we send the browser to the hostname and port of the DCC WebGate is because 1) we need to get the DCCCtxCookie, and 2) the credentials need to be posted to the DCC WebGate either directly or through the load balancer virtual host as I mentioned.

Challenge URL

The Challenge URL will be the relative URI of the custom login page that is served up from the DCC WebGate. This is similar to how you would configure a custom external Form Login. I want to add that where the page is located is not as important as long as the URI goes through the DCC WebGate. For example the login page could be a JSP hosted on WebLogic, and the web tier OHS web server that has the DCC WebGate on it could be configured with the weblogic_module that points the URI back to the WebLogic application server. In my case I just used a simple static login.html page served up from the web tier OHS server. Basically what happens is the Challenge Redirect URL combines with the Challenge URL to point the browser to the login page. Using my example from the previous table values, the browser would be redirected to login at https://sso.melander.us/sso/login.html.

Context Type

DCC does not use this. This parameter tells OAM how to build the final URL after being redirected to the login page. Notice that with DCC, the selection is blank. This means that OAM will not do anything special to build the final URL except provide the original requested URL. If you refer to sequence 3 in my Part 1: Getting under the covers of Detached Credential Collector (DCC) notice that the URL is very clean on the final login destination, and only includes a single query string parameter “?resource_url=” which contains a URL encoded value of the original requested URL used to tell OAM where to send the browser back to its original requested HTTP resource after a successful login.

Context Value

DCC does not use this. Since nothing is selected for the Context Type, the authentication scheme will not even make this an available option.

Challenge Parameters

The Challenge Parameter field is to provide any required special credential input, but if this field is left blank, the default values for the login form minimally require username and password. In my authentication scheme I left this field blank, so the form login only included the minimum username and password as follows.

<input id="username" maxlength="25" name="username" type="text" />
<input id="password" name="password" type="password" />

STEP 2: The DCC Custom Login Form Page Requirements

Now that we have created the DCC authentication scheme, let’s create the DCC Form Login page.

Credential Input Fields

The credential input fields are actually similar to ECC in many ways. By default as mentioned earlier, username and password are minimally required if the Challenge Parameters field in the authentication scheme is left empty. However there are other special parameters options that can be used for various reasons. Please refer to the OAM Administration Guide for 11g Release 2 (11.1.2) section Table 16-22 User-Defined Challenge Parameters for Authentication Schemes, which lists a number of parameters, and some dedicated specifically to DCC like like “creds=” or “extracreds=”. However, in the context of this blog, I am keeping it simple (KISS --- Keep It Simple Stupid) to mitigate complexity and confusion. So my input fields for the login page are simply username and password. The following is an example of the HTML source code of the credential input fields for a login form.

<input id="username" maxlength="25" name="username" type="text" />
<input id="password" name="password" type="password" />

OAM_REQ Hidden Field

The OAM_REQ stores the OAM Server state. I am sure for those that have created custom logins before the OAM_REQ parameter is already something familiar. DCC is not much different, but if your custom login only uses username and password, the WebGate will not return an OAM_REQ parameter at all and therefore you need not bother to submit this input with the credentials. However, if the custom DCC authentication uses a multi-step authentication, the OAM_REQ will show up and therefore the login page needs to handle the OAM_REQ parameter and submit it with the form in order for authentication to work properly. The value comes across as a header, so you will need some way to dynamically grab OAM_REQ header whether it be JSP, ASP, PHP, etc. Then once retrieved the input field should then be hidden, the value populated in the hidden input field, and then submitted with the other credentials. The following is an example source code to retrieve the OAM_REQ using Java Server Pages (JSP).

<input name="OAM_REQ" type="hidden" value=”<%= request.getHeader("OAM_REQ”) %>“>

Form Method

The form method is almost always POST. There may be cases where POST could be a GET, but from a security stand point POST is generally always used. My simple example uses the POST method. I mentioned this earlier, it is important that the form be submitted whether POST or GET to the DCC WebGate. This could either be directly to a single web server that has the DCC WebGate or the Load Balancer virtual host that sends the requests to the DCC WebGates, but the main point is the form has to be submitted to the DCC WebGate(s). The following is an example HTML source code of the form action. Maybe mention SSL here….

<form action="/oam/server/auth_cred_submit" method="post" name="form">

Form Action

The ACTION URI can be the default “/oam/server/auth_cred_submit”. This is exactly what an external custom form login uses. However if you do not want to use the default ACTION URI, there is a special parameter “action=” that is specifically designed for DCC that can be added in the “Challenge Parameters” field of the Authentication Scheme to change it; for more details on this parameter and others see the OAM Administration Guide for 11g Release 2 (11.1.2) section Table 16-22 User-Defined Challenge Parameters for Authentication Schemes. The following is an example of the HTML source code of the form action.

<form action="/oam/server/auth_cred_submit" method="post" name="form">

TempStateMode

Last but not least I want to mention a parameter named “TempStateMode”. This User-Defined parameter can be configured in the Authentication Scheme “Challenge Parameters” field. Oracle provides details on this parameter in the OAM Administration Guide for 11g Release 2 (11.1.2) section Table 16-22 User-Defined Challenge Parameters for Authentication Schemes. TempStateMode controls how the DCC stores the OAM server state, whether it is cookie or form depending on what serverRequestCacheType is configured. The serverRequestCacheType parameter is found in the oam-config.xml configuration file of the OAM Server. Basically the TempStateMode can tweak how the DCCCtxCookie stores the OAM Server state. The relevance of this parameter is in case the server state cookie value size explodes beyond its limit, which in that case the default value TempStateMode=form should prevent this. If this parameter is not set in the User Defined Parameters the default is “form” and should be fine for nearly every case.

Example Login Form

So to put it all together the following is an example JSP Login Form. Remember if you are doing a very simple login form that does not use multi-step authentication, you can exclude the input field OAM_REQ.

Code Example 1 – My Simple DCC Custom JSP Login Form
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head></head>
<body>
<h2> Enter your credentials </h2>
<form action="/oam/server/auth_cred_submit" method="post" name="form">
Username: <input name="username" type="text" maxlength="25">
Password: <input name="password" type="password">
<input name="OAM_REQ" type="hidden" value=”<%= request.getHeader("OAM_REQ”) %>“>
<input type="image" name="login" src="images/login.png" onclick="document.form.submit();"/>
</form>
</body>
</html>
 

STEP 3: Applying the Custom DCC Login Form

Now that the authentication scheme has been created, and the login page has been built, all that remains is to change the authentication scheme in the Application Domain and test it. So go into the OAM Console > open the Application Domain > Authentication Policy > Protected Resource Policy and change the authentication to the new DCC Authentication Scheme. Once changed give it a test to see if everything functionally works as expected. If authentication it is not working please refer to my first blog on DCC, Part 1: Getting under the covers of Detached Credential Collector (DCC), and read through the sequence diagram to understand what should be happening. You may want to install or use some HTTP Trace on your browser to make sure you are getting the right cookies, redirected to the correct hosts, etc. Another troubleshooting tip is to set the WebGate oblog to TRACE along with setting the OAM Server module “oracle.oam.proxy.oam“ to TRACE. This pretty much covers it for DCC login; it is fairly straightforward. I hope this helps understand the special needs of DCC Login. Now let’s continue to the logout, which is a bit more complicated. We need to make sure the login form is unprotected, too?

How to Create a DCC Custom Logout

The logout is often neglected because, well, it is not quite as sexy as single sign-on (SSO). In fact sometimes it can be even more complicated that the login. For example with multiple domains there are OAMAuthnCookies that need to be terminated, there could be backend application sessions that also need to be terminated, and don’t forget about session timeouts. If an application session ends before the OAM session, the user could experience a partial logout, which can create odd unwanted behavior. Unfortunately it is outside the scope of this article to answer all the logout nuisances and recommendations, so minimally I want to focus on the DCC logout requirements only. There are two distinct types of WebGates in the context of this article, the DCC and the Resource WebGates. Each WebGate profile will require slightly different logout configurations. We already know about the “Allow Credential Collector Operations” option in the WebGate Agent profile to make it a DCC WebGate. However when it comes to logout there are also special considerations when it comes to a DCC WebGate. As a quick preview summary, the following table shows the difference between the DCC and Resource WebGate logout configurations.

  Table 2 - DCC vs Resource WebGate Profile Logout Configuration
Agent Parameter DCC WebGate Resource WebGate
Logout URL e.g. /sso/signout.jsp /sso/logout
Logout Callback URL /oam_logout_success /oam_logout_success
Logout Redirect URL <dcc_host:port>/ e.g. https://sso.melander.us/sso/signout.jsp
Logout Target URL end_url end_url

 As you can tell from the above table the DCC WebGate includes the URI of the logout page, /sso/signout.jsp, where as the Resource WebGate contains a different URI all together and actually not even a real location. Also the DCC WebGate does not even contain a value for the Logout Redirect URL where the Resource WebGate does, and points the absolute URL of the DCC Logout page. So let’s get into the differences and explain the configurations.

STEP 1: The DCC WebGate Agent Profile Logout Setting Requirements

The following table lists the parameters and values required for the DCC WebGate. I have provided important comments in, you guessed it, the “Comments” column. In the next step for the Resource WebGate Agent profile I will tie together how important the DCC WebGate Agent logout configurations are and why it is really important that the settings all be intelligently configured to work together and successfully make the logout work properly.

  Table 3 - DCC Agent Profile Logout Configurations
Agent Parameter Agent Value Comments
Logout URL e.g. /sso/signout.jsp This should be the URI only that points directly to the logout page, which would be coming from the DCC WebGate host or Load Balancer virtual hostname.
Logout Callback URL /oam_logout_success Use this value. This is a constant value used to terminate all domain sessions.
Logout Redirect URL DCC does not use this. The purpose of the DCC WebGate is for central login and logout, so no value is required here; leave it empty.
Logout Target URL end_url OPTIONAL: This is a query string parameter, which can hold a URL to redirect the browser after the logout process is finished.

 The following screenshot shows my DCC WebGate Agent profile.

  Figure 2 - DCC WebGate Agent Profile


STEP 2: The Resource WebGate Agent Profile Logout Setting Requirements

The Resource WebGate is all other WebGates that do not use the “Allow Credential Collector Operations” checked like with the DCC WebGate; this was mentioned in my Part 1: Getting under the covers of Detached Credential Collector (DCC) blog.  The following table lists the parameters and values required for each Resource WebGate.

  Table 4 - Resource Agent Profile Logout Configurations
Agent Parameter Agent Value Comments
Logout URL /sso/logout This URI is not a real page, it is only used to trigger the logout process and terminate the OAMAuthnCookie for this WebGate.
Logout Callback URL /oam_logout_success Use this value.  This is a constant value used to terminate all domain sessions.
Logout Redirect URL <dcc_host:port>/<logout page>e.g. http://sso.melander.us/sso/signout.jsp The absolute URL to the same logout page set in the DCC WebGate profile Logout URL. The logout page URI must match exactly. This is where the browser will be sent after triggering the Resource WebGate Logout URL, i.e. /sso/logout.
Logout Target URL end_url OPTIONAL: This is a query string parameter, which can hold a URL to redirect the browser after the logout process is finished.

 The following screenshot shows what my Resource WebGate Agent profile looks like.  Notice the Logout Redirect URL points directly to the same DCC WebGate Logout URL; e.g. the absolute URL is https:/sso.melander.us/sso/signout.jsp; this is important to understand how this works.

  Figure 3 - Resource Agent Profile

  So for example the logout link is on the application page, the HREF link is really just the URI defined in the Resource WebGate Agent Logout URL, in my case it is “/sso/logout”.  When the user clicks on the logout link or button, the browser requests the relative URI “/sso/logout”.  The WebGate knows about this special URI, which triggers the logout process.  The Resource WebGate will then expire the OAMAuthnCookie for that domain, and next send the browser to the Logout Redirect URL https://sso.melander.us/sso/signout.jsp defined in the Resource WebGate Agent.  Once the browser lands on the logout page https://sso.melander.us/sso/signout.jsp, it also expires the OAMAuthnCookie for the DCC WebGate host.  However, if we have gone to multiple domains, the show is not over.  We still need to deal with all the other domain cookies to complete our logout because at this point we are only logged out of the DCC WebGate and the Resource WebGate domain we clicked the logout link or button from.  This is where the Logout Callback URL comes in, and I want to spend time talking about this next in its own section.  

STEP 3: Using the Logout Callback URL to terminate remaining OAMAuthnCookies

Normally when using ECC, OAM automatically makes a call back to one of the OAMAuthnCookie domains with a special URI named “/oam_logout_success”; remember this value defined in the Logout Callback URL parameter of the WebGate profile?  When a logout process is requested using ECC, OAM begins to make callback requests to all the domains a browser accessed in the form of a HTTP request; e.g. request 1) http://app.domain1.com/oam_logout_success, request 2) http://app.domain2.com/oam_logout_success, and so forth until all the OAMAuthnCookie hosts are expired.  If this were not done, the browser would only be logged out of the current domain it clicked the logout from. The DCC WebGate is unique because it puts all the interaction with the browser at the front end where normally with ECC the browser can have all this interaction with the OAM server to make all these callbacks to terminate the session.  So DCC does it a little differently.  Let’s take a look at a WireShark TCP trace taken from the DCC WebGate to better understand what is going on.

  Figure 4  - WireShark Trace showing HTTP_OAM_LOGOUT_CALLBACK_URLS Header

  The above WireShark trace was captured when using the out-of-the-box logout.pl configuration.  So what we find is during the logout using DCC there is a special HTTP Header called “HTTP_OAM_LOGOUT_CALLBACK_URLS“ that shows up at the point of accessing the logout.pl.  The header HTTP_OAM_LOGOUT_CALLBACK_URLS can hold multiple callback URLs that come from all the domains the browser has been to (see the highlight in yellow).  Notice the header value http://acme.melander.us/oam_logout_success? In the next WireShark screenshot trace we see that the logout.pl uses this header to dynamically build an image tag and uses the Logout Callback URL from the header as the source of the image.  But WAIT, this is not really an image is it!! Cleverly even though this source is not an image, it forces the browser to load what it thinks is an image, but in reality makes the browser do a HTTP request to the Logout Callback URL, which ultimately expires the OAMAuthnCookie session for that domain.

  Figure 5 - Dynamic Invisible Image Tag


Notice there is only one image tag for the Logout Callback URL in the WireShark trace?  If the browser accessed multiple domains the OAM_LOGOUT_CALLBACK_URLS header would store a delimited list of Logout Callback URLs and the logout.pl is designed to iterate through them to build multiple image tags.   Making multiple HTTP requests using these invisible image tags expires all the OAMAuthnCookie domains; pretty clever right? If there is a case where only one of which should be many Logout Callback URLs AKA Partners are not presented in the OAM_LOGOUT_CALLBACK_URLS header, the Partner logouts may not be complete.  Meaning, post DCC logout, the OAMAuthnCookies for the other domains may not get cleared.  However, not to worry, because on the server side these sessions get cleared as a result of the logout leaving the uncleared OAMAuthnCookies obsolete.  So if this happens the risk is low and the browser will ultimately be logged out.

How to Leverage the OAM_LOGOUT_CALLBACK_URLS Header

I spent all this time to help you understand the importance of the Logout Callback URL and how the logout.pl leverages the OAM_CALLBACK_URLS header so that I can now show you how to use this same trick to complete your logout successfully using a custom logout page.  So the question is, how do we take advantage of this magical OAM_LOGOUT_CALLBACK_URLS header?   There are four things;
1. Configure the Logout URL URI value in the DCC WebGate profile to point to the final logout page; e.g. /sso/signout.jsp.  This is very critical!!
2. Make sure the Logout Redirect URL value for the Resource WebGates point directly to the DCC WebGate host and Logout URL; e.g. https://sso.melander.us/sso/signout.jsp.  This is also very critical!!!
3. Based on #1 above, the header OAM_LOGOUT_CALLBACK_URLS we are looking for will show up the first time the browser hits the signout.jsp (Or whatever name you give the logout page), and will contain a list of all the absolute Logout Callback URL values like what we observed in the WireShark trace.
4. We will then leverage Java Server Pages to get the header and dynamically build the same clever invisible image tags in the logout page we saw the logout.pl script do in the WireShark trace.  You could also do this with PHP, ASPX, or some other dynamic web programing language.
  To help kick start you, the following is an example Java Server Pages logout page to do the job.  So when you are redirected to the signout.jsp, it grabs the OAM_LOGOUT_CALLBACK_URLS header, iterates through the Logout Callback URLs, and dynamically inserts invisible image tags in the logout page.

  Code Example 2 - Java Server Pages signout.jsp page
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<!-- COPYRIGHT (c) 2014 ORACLE A-TEAM -->
<!-- THIS SAMPLE CODE IS PROVIDED FOR EDUCATIONAL PURPOSES OR     -->
<!-- TO ASSIST YOUR DEVELOPMENT OR ADMINISTRATION EFFORTS AND     -->
<!-- PROVIDED "AS IS" AND IS NOT SUPPORTED BY ORACLE CORPORATION. -->
<%@ page contentType="text/html;charset=UTF-8"%>
<%@ page import="java.util.Enumeration" %>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>OAM DCC Logout</title>
  </head>
  <body>
       
    <h1 align="center">
      You have successfully logged out!
    </h1>
    <% 
    String imgBeg="<img border=\"0\" width=\"0\" height=\"0\" src=\"";
    String imgEnd="\"/>";
    Enumeration e = request.getHeaders("OAM_LOGOUT_CALLBACK_URLS");
    while (e.hasMoreElements()) {
        String headerVal = (String) e.nextElement();
        out.write(imgBeg+headerVal+imgEnd);
    }
    %>
  </body>
</html>

 

Based on the Java Server Pages signout.jsp page above, you can see in the figure below an example of what the HTML source output of the page would look like after it renders.  As the page loads the Logout Callback URL are requested, cleverly as invisible images, but despite not being a real image it makes the necessary HTTP request for each Logout Callback URL domain and completes the expiration of the remaining cookies --- Nifty right?

  Code Example 3 - HTML source output of the signout.jsp page
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 
<!-- COPYRIGHT (c) 2014 ORACLE A-TEAM --> 
<!-- THIS SAMPLE CODE IS PROVIDED FOR EDUCATIONAL PURPOSES OR     --> <!-- TO ASSIST YOUR DEVELOPMENT OR ADMINISTRATION EFFORTS AND     --> <!-- PROVIDED "AS IS" AND IS NOT SUPPORTED BY ORACLE CORPORATION. -->   <html>
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
     <title>OAM DCC Logout</title>
   </head>
   <body>
        
     <h1 align="center">
       You have successfully logged out!     </h1>
          
<img border="0" width="0" height="0" src="http://acme.melander.us/oam_logout_success"/>
   </body>
 </html>
Note if you are using Java Server Pages, you will need to configure your web server for the WebLogic module.  Of course if you are using some other dynamic web programming language, the same would apply per your choice of web technology.  In my example I modified the following Oracle HTTP Server (OHS) mod_wl_ohs.conf file though your configuration would be a little more robust to also include a cluster.
<IfModule weblogic_module>
      WebLogicHost weblogichost.com
      WebLogicPort 7001
      WLLogFile /tmp/weblogic.log
      MatchExpression *.jsp
</IfModule>

What if I don’t have a dynamic logout page to get the HTTP header?

Since the OAM_LOGOUT_CALLBACK_URLS does only show up on the server side, getting the header can present a big challenge if you don’t have some type of dynamic web language technology. If this is your situation and you don’t have a way to use a web technology like Java Server Pages (JSP), PHP Hypertext Preprocessor (PHP), Active Server Pages eXtension (ASPX) or something similar for any reason; not to worry, you can still get the logout job done, but at a cost. Let’s say you know that you will only have two domains a browser will ever be accessing, say portal.acme.com and sales.oceanicair.com, then you can hard code the two invisible image tags in the page as follow. Code 

Example 3 - Example HTML source output of a static logout page
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 
<!-- COPYRIGHT (c) 2014 ORACLE A-TEAM --> 
<!-- THIS SAMPLE CODE IS PROVIDED FOR EDUCATIONAL PURPOSES OR     --> <!-- TO ASSIST YOUR DEVELOPMENT OR ADMINISTRATION EFFORTS AND     --> <!-- PROVIDED "AS IS" AND IS NOT SUPPORTED BY ORACLE CORPORATION. -->   <html>
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
     <title>OAM DCC Logout</title>
   </head>
   <body>
        
     <h1 align="center">
       You have successfully logged out!     </h1>
          
<img border="0" width="0" height="0" src="http://portal.acme.com/oam_logout_success"/>
<img border="0" width="0" height="0" src="http://sales.oceanicair.com/oam_logout_success"/>

   </body>
 </html>

 

Let’s say you know that you will only have two domains a browser will ever be accessing, say portal.acme.com and sales.oceanicair.com, then you can hard code the two invisible image tags in the page as follow.

First, the bad news…each time a domain changes whether it be added, changed, or removed, you will need to update the logout page across all environments.  Something to keep in mind, if your WebGate preferred hostname is say “.acme.com”, then if you go to portal.acme.com and sales.acme.com, both are different OAMAuthnCookie domains, so a Logout Callback URL will be required for both.  The earlier approach would take care of this automatically, but the approach of hard coding the image tags in a static logout page as you can see will become unwieldy.  This approach can be error prone and additional administration overhead is required to manage changes each time one is made.  The good news, although not the most elegant method, it will get the job done and you can be sure your logout is successful from all domains.

 


WARNING: THE LOGOUT PAGE NAME IS IMPORTANT If by any chance you use logout.jsp, this is a special logout page name that OAM looks for.  If the name of your logout page is logout.jsp, OAM will probably catch this,  and OAM will cough it up and act like the normal ECC logout process and send you to the default out-of-the-box logout page.  This is probably not what you would like to happen.  Therefore to be safe, use some other logout page name other than logout.jsp, and for insurance host it on some other application server other than the one OAM is using.  You may have noticed in my example I used signout.jsp.  In my example I happen to host my JSP on the same WebLogic server OAM was hosted, but in the AdminServer instance.  However, I only did this for development and experimentation.  I would recommend hosting the login and logout pages in either a completely different WebLogic instance or at minimum a different managed domain.
 

Summary

So now you have some idea of the requirements that encompass how to create a custom login and logout page that works with DCC.   For those that want to use the DCC feature, I hope this article alleviates the concern of thinking you are stuck using the Oracle OAM DCC Perl scripts, login.pl and logout.pl.  The Perl scripts are certainly a viable option, but I would think most customers are more oriented to creating their own customized branded login and logout pages.  Good luck!

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.