External Custom Login Forms with Oracle Access Manager 11g

This is the 2nd post in my OAM 11g Academy series. To view the first post in the series which will be updated throughout to contain links to the entire series, click here: http://fusionsecurity.blogspot.com/2011/02/oracle-access-manager-11g-academy.html

While my intent was to make the first few posts on the topic of the OAM 11g policy model, I’ve been getting a ton of requests for help on how to do form based logins using a custom, externally hosted login form with OAM 11g. So, I’ve decided to take a short break from the policy model to tackle that topic.

It is very common for customers to want to redirect users to their own custom login form to authenticate into OAM. There are actually several sub-scenarios to this use case that I will address in a broader post about authentication in OAM 11g, but the thing I want to focus on today is the case of redirecting the user to a login page or application that is “externally” hosted outside of the OAM managed server.

The idea is that when it is time to authenticate the user, the user will be redirected to your own page or application that can be built using whatever technology you like including JSP pages, ASP/.net, perl, PHP, etc.. You can render the form to look like whatever you want and even potentially do some pre-processing of the users submission (POST) before sending the credentials along to OAM.

The information on how to do this can be divided into two sections: the authentication scheme configuration and the login.jsp itself.
The Authentication Scheme

You want to create a new authentication scheme that you will use in your authentication policy. You can give it whatever name you want.

The settings should be as follows, this is basically what is in the 11g documentation on authentication schemes that can be found here except that there is a bug in the documentation that puts a “/” in the front of the challenge URL. You do not want the “/”.

Challenge Method: FORM

Challenge Redirect URL: /oam/server/ (note that you do not want to change this from the value used for the default OAM form)

Authentication Module: LDAP (or whatever you had before for the default OAM form scheme)

Challenge URL: The full URL starting with http or https of your login form which can be hosted wherever you like

Context Type: external

The Process


When you set up a form based authentication scheme with challenge type external, the webgate redirects the user first to the obrareq.cgi url which then redirect the user to the login page specified in the authentication scheme “challenge url”.

On the redirect to the login page it adds two things to the query string: request_id and redirect_url as in the following query string ?request_id=5092769420627701289&redirect_url=http%3A%2F%2Fateam-hq61.us.oracle.com%3A7777%2Fscripta%2Fprintenv

The Form/App

Again, the form or login application can be written using any technology you care to use to process the redirect from the user and render the HTML. The following is what you need to know about what is required in the login form you create. Beyond these three items, the login page can take whatever shape you’d like it to. These items are also documented in the “About custom login pages” section of the doc:

• You need to post back to the OAM server to the URI: “/oam/server/auth_cred_submit”. Note that in my sample, I’m on the same machine so I just have the URI and not the full URL, but if you are on a different server you’ll need the full URL.
• You need to post variables “username” and “password”
• You need code that will grab the request_id off of the query string and post it (as a hidden form variable) as well

Here is code from a sample login.jsp page that works as a external login form for OAM 11g.

Sample login.jsp:

<%@ page contentType="text/html; charset=iso-8859-1" language="java" %>
    <%
    String error=request.getParameter("error");
    if(error==null || error=="null"){
    error="";
    }
    String paramName = "request_id";
    String reqId  = request.getParameter( paramName );

    %>
    <html>
    <head>
    <title>User Login JSP</title>
    <script>
    function trim(s)
    {
    return s.replace( /^\s*/, "" ).replace( /\s*$/, "" );
    }

    function validate()
    {
    if(trim(document.frmLogin.sUserName.value)=="")
    {
    alert("Login empty");
    document.frmLogin.sUserName.focus();
    return false;
    }
    else if(trim(document.frmLogin.sPwd.value)=="")
    {
    alert("password empty");
    document.frmLogin.sPwd.focus();
    return false;
    }
    }
    </script>
    </head>

    <body>
    <p>Acme Clinical Applications Login Screen - OAM edition</p>
    <p>
      &nbsp;
    </p>
    <div><%=error%></div>
    <form name="frmLogin" onSubmit="return validate();" action="http://auth.acme.com/oam/server/auth_cred_submit" method="post">
      <p>
        User Name<input type="text" name="username"/><br/>Password &nbsp;<input type="password"
                                                                                 name="password"/>
        <input name="request_id" value="<%=reqId%>" type="hidden">  <br/>
      </p>
      <p>
        <input type="submit" name="sSubmit" value="Submit"/>
      </p>
    </form>
    </body>
    </html>