This documentation is for the Web Login Service v2 (CAS2) that was retired end of calendar year 2014.
It is here for informational purposes only and is no longer applicable.
----------------------------------------------------------------------
File:   0-web-developers.txt
Descr:  Using CAS Web Login Service for Web site developers
By:     Russell Tokuyama
Date:   01/30/03
Mod:    $Id: 0-web-developers.txt 283 2009-09-30 20:55:13Z russ $
----------------------------------------------------------------------
CONTENTS
  1. CHANGE LOG
  2. OVERVIEW
  3. WEB LOGIN PROCESS
  4. URLs
  5. LOGIN SECURELY
  6. TOKEN VALIDATION
  7. LOGGING OUT
  8. SAMPLE WEB APP USING THE WEB LOGIN SERVICE
  9. FREQUENTLY ASKED QUESTIONS (FAQ)
     Q: Why does my site automatically login a returning user after they
        logout of their session with my site?
     Q: Is there a preferred method for logging out users?
 10. RESOURCES
----------------------------------------------------------------------
  1. CHANGE LOG
     01/30/2003; Initial version.  RT
     06/07/2011; Contact information and copyright dates updated. MH

  2. OVERVIEW
     The Web Login Service is available for only University of Hawaii
     (UH) Web site developers to use to authenticate users with their UH
     username and password.  This alleviates the problem of having to
     develop a user authentication system as part of the Web site
     development.  It also provides increased security for users by not
     allowing Web sites to handle their password (often done insecurely
     such as sending it in the clear).
     The Web Login Service does not provide authorization or access
     control services.  However, as a side effect of authenticating a
     user, a Web site (a.k.a., Web application) can get data about the
     user (person info) that can be used to perform access control.  If
     you do not perform any access control then anyone in the UH Core
     LDAP Directory Service will be able to use your Web site.  This is
     all current people in the UH System as well as visitors allowed by
     the Visitor Internet Access (VIA) at http://www.hawaii.edu/via/.
     
     The Web Login Service uses the CAS (Central Authentication Service)
     software written by Yale University (see RESOURCES below).  DO NOT
     contact Yale about this installation as the CAS software has been
     modified for UH-specific requirements.

  3. WEB LOGIN PROCESS
     When your Web site is set up to use the Web Login Service it uses a
     link on the login or main page of the site instead of an HTML form.
     The link redirects the user to the Web Login Service which presents
     them with a secure HTML form.  To be authenticated, the user only
     enters her UH username and password on the Web Login service's
     secure HTML form.
     After submitting her UH username and password the user is
     redirected back to your Web site.  Then, your Web site takes the
     authentication token that the Web Login Service sent along with the
     redirect and asks the Web Login Service to validate it.  If the
     user supplied the correct password the Web Login Service will
     return a confirmation message to your Web site.  Otherwise, a
     rejection message is returned.  The confirmation message will
     include the user's UH username, UH number (uhUuid), and full name
     (last, first middle initials).
     From this, the Web site will know who the user is.  The Web Login
     service does not provide session tracking information so it is your
     Web site's responsibility to handle session tracking.  Session
     tracking will reduce the number of round trips to the Web Login
     Service to validate the user each time a resource (URL/URI) is
     requested from your Web site.

  4. URLs
     a. Login securely
          https://login.its.hawaii.edu/cas/login
     b. Token validation
          https://login.its.hawaii.edu/cas/validate
     CAUTION: Use of any other URLs may cause problems.

  5. LOGIN SECURELY
     To have a user login securely put a link on your main page to the
     "login securely" URL with a request parameter named service and
     having a value that is the Service URL (i.e., the URL of the main
     page or a page that will be able to handle an HTTP request with a
     parameter).  This link should be labeled with something like "Login
     Securely" to establish in your user's mind that their password will
     not be seen by your application and is handled securely.  See the
     next section on token validation for information about how your
     application finds out their username.
     Here's an example:
       a. Service URL
          This is your site's menu page or the page after a user logs
          in.
       
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://myserver/myapp
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
       b. "Login Securely" link
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<A HREF=
"https://login.its.hawaii.edu/cas/login?service=https://myserver/myapp">
login securely</A>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     NOTES:
        1. The Service URL must be a real URL.  For example, most Web
           servers have a default page that is returned when you request
           a URL that ends with a forward slash character, "/".  This
           often results in redirects to index.html or index.htm while
           others use default.htm or default.asp.
        2. Since the Service URL is passed as the value of a query
           parameter, it should be URL-escaped to avoid being mangled by
           the Web Login Service.  Please refer to Appendix A of RFC
           2396 for details.
     
  6. TOKEN VALIDATION
     This section describes how your application finds out the username
     of the user that is logging in.
     When the Web Login Service has authenticated the user, it will
     redirect the user back to your Web site to the Service URL with an
     HTTP request parameter named, ticket, added on the end of the
     Service URL.  That Service URL can not be a static page since it
     won't be able to extract the authentication token and validate it.
     Here's an example of the URL used by the Web Login Service to
     redirect the request back to the Web site:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://myserver/myapp?ticket=ST-3-8tkkJbPThesE1cZjVVtc
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     The server-side processing of your Service URL must validate the
     extracted authentication token by sending an HTTP GET request
     with the following parameters:
       service=<Service URL>
       ticket=<authentication token>
     Here's an example of the request sent to the Web Login Service:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://login.its.hawaii.edu/cas/validate?service=https://myserver/myapp
&ticket=ST-95-a1kjb6g4Tcdeh17vfy6g
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NOTE: The request should be all on one line.
     After validating the authentication token, the Web Login Service
     will return a text document that is a message indicating success
     or failure of the user's authentication.
     The message sent back in response to a validation request is
     plain text.  If the authentication was successful, the message
     is:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
yes
teststaf
11668132
Staff M Teststaff
staff; student
uhm; kcc
eduPersonOrgDN=uhm,eduPersonAffiliation=staff; eduPersonOrgDN=kcc,eduPersonAffiliation=student
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     The message contains:
       a. Status of authentication
       b. UH username
       c. UH number (a.k.a., uhUuid - a UH unique identifier)
          NOTE: The UH number should be handled confidentially like a
                Social Security Number.  Especially with information
                about or associated with students.  FERPA laws
                constrain what may be published about students.  Please
                check with the Admissions and Records office about
                privacy about student information.
       d. Full name
       e. Affiliation - multiple affiliations are separated by
          semicolons.
       d. Campus - multiple campuses are separated by semicolons;
       f. Campus affiliation - multiple campus affiliations are separated by
                 semicolons.
     If the authentication step fails the user will remain at the Web
     Login Service's login page.  They would need to visit the Account
     Management page to reset their password or call the Help Desk for
     assistance.
     The authentication token is a one-time use token so any attempt
     to reuse it will result in this message being sent back:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
no
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     CAUTION:  After the Web Login Service redirects the user back to
     your app and you have validated the token, redirect the user to a
     URL that does not have the token in the URL.  Not doing so, opens
     the user to bookmarking a URL with a token in it.  This becomes a
     problem because the CAS software isn't on guard for this and this
     results in a looping problem sending the user back and forth
     between your site and the Web Login Service.

  7. LOGGING OUT
     Web applications that login a user handle their own session state
     and offer the user the ability to log out of a session.  However,
     upon returning to the Web application's Service URL, the user will
     be automatically logged back in because of the ticket-granting
     cookie if cookies are enabled in the user's browser.  This is a
     single sign-on feature across Web applications that use the Web
     Login Service.  There are two basic ways to "log out"; logout from
     application and Web Login Service single sign-on or logout from
     application and force re-authentication to the Web Login Service.
     To logout a user and prevent her from automatically logging back
     into a Web application, the Web application can forward the user to
     the Logout URL of the Web Login Service.  That URL will destroy the
     ticket-granting cookie that enables the single sign-on feature and
     gives the user a page that informs them that they have logged out of
     the Web Login Service.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://login.its.hawaii.edu/cas/logout
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     If you want a page from your site to be displayed to the user
     instead of the one from the Web Login Service, add the URL for that
     page as one of the parameters for the Logout URL.  The the user
     will see a page that is more closely associated with the Web
     application that they are logging out of.  In reality, the logout
     is from both the Web application and the single sign-on feature of
     the Web Login Service.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://login.its.hawaii.edu/cas/logout?service=https://myserver/myapp/
logout.html
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NOTE: The URL should be all on one line.
     If you want the user to authenticate every time they click on your
     login URL, change your login URL by appending "&renew=true".
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
https://login.its.hawaii.edu/cas/login?service=https://myserver/myapp
&renew=true
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NOTE: The URL should be all on one line.
     This will cause the Web Login Service to prompt the user to login
     whenever she clicks on the "Login securely" URL but still permits
     the user to single sign-on to other Web applications using the Web
     Login Service.

     NOTE: Since the Service URL is passed as the value of a query
           parameter, it should be URL-escaped to avoid being mangled by
           the Web Login Service.  Please refer to Appendix A of RFC
           2396 for details.
  8. ACCESS CONTROL
     It is every developer's responsibility to perform access control
     (authorization) after a user has logged on to their Web site.  This
     is done by checking the person info.  The affiliation, campus, or
     campus affiliation data should be enough to filter out unauthorized
     users.  Alternatively, you explicitly allow or disallow by
     username.  In any event, the developer must make this decision.
  9. SAMPLE WEB APPS USING THE WEB LOGIN SERVICE
     a. Here's an ASP file that prints out the user's name after they
        have authenticated.  Once successfully authenticated, the ASP
        page remembers the user's name and username.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<%@ Language=JScript %>
<%
// File: default.asp
// Mod:  02/06/03, Russell Tokuyama (UH ITS); set up for UH.
//
// Install in Inetpub\wwwroot\HelloCas and request:
//   http://myserver/HelloCas/
//
// Based on sample ASP code that uses CAS by Howard Gilbert.
//
// If you logon, it says "Hello " followed by your userid
// For the Web server to talk to the CAS server, this code depends on the
// Microsoft ServerXMLHTTP control provided with MSXML. If the MS XML
// parser is not already installed on the IIS host machine, 
// download version 3.0 SP1 or better from http://www.microsoft.com/xml
// Insert name of CAS Server at your location
var CAS_Server = "https://login.its.hawaii.edu/cas/";
// Note: Request.ServerVariables("SERVER_NAME") or anything based on
// the HTTP "Host" header should NOT be used; this header is supplied by
// the client and isn't trusted. (--SB)
// Insert public name of IIS Server hosting this script
var MyServer = "http://buzz1.its.hawaii.edu:8008/";
var greeting = "World"; // In case I fail
var line0 = "";
var line1 = "";
var line2 = "";
var line3 = "";
var line4 = "";
// See if already logged on
var uid = Session.Contents("Netid");
if (!uid) {
    // Check for ticket returned by CAS redirect
    var ticket = Request.QueryString.Item("ticket").Item;
    if (!ticket) {
        // No session, no ticket, Redirect to CAS Logon page
        var url = CAS_Server+"login?"+
                  "service="+MyServer+"HelloCas/default.asp"
        Response.Redirect(url);
        Response.End;   
    } else {        
        // Back from CAS, validate ticket and get userid
        var http = Server.CreateObject("MSXML2.ServerXMLHTTP");
        var url = CAS_Server+"validate?ticket="+ticket+"&"+
                  "service="+MyServer+"HelloCas/default.asp";
        http.open("GET",url,false); // HTTP transaction to CAS server
        http.send();
                
        var resp=http.responseText.split('\n'); // Lines become array members
        if (resp[0]=="yes") {  // Logon successful
            greeting = resp[1]; // get userid for message
            line0 = resp[0] + "\n";
            line1 = resp[1] + "\n";
            line2 = resp[2] + "\n";
            line3 = resp[3] + "\n";
            line4 = resp[4] + "\n";
            // Save for subsequent calls
            Session.Contents("Netid")=resp[1];
            Session.Contents("Name")=resp[3];
        }
    }
}
else {
    greeting = Session.Contents("Name");
}
%>
<HTML>
<HEAD><title>CAS ASP Example application</title></HEAD>
<BODY>
<P>Hello <%=greeting%> (<%=uid%>)
</P>
<P>The validation message contains:<BR>
<PRE>
<%=line0%>
<%=line1%>
<%=line2%>
<%=line3%>
<%=line4%>
</PRE>
</BODY>
</HTML>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     b. Here's a PHP script that counts the number of times a user
        visits the URL.  The user's person info is also displayed.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<?php
    // cas-demo.php - Demo of PHP using the Web Login Service
    //              - 06/08/07, Russell Tokuyama
    //              - Copyright (c) University of Hawaii 2007
    //                See the end of this file for the copyright notice.
    //
    //-------------------------------------------------------------
    //
    // The only things that need to be configured:
    //
    //-------------------------------------------------------------
    // 1. Set this to the URL of this script.
    $me = "http://somehost/cas-demo.php";
    // 2. Set this to the base URL of the Web Login Service (no trailing 
    //    slash).
    $weblogin = "https://login.its.hawaii.edu/cas";
    //-------------------------------------------------------------
    //
    // These are based on the above variables.
    //
    // Login link to the Web Login Service
    $login = "${weblogin}/login?service=" . urlencode($me);
    // Logout link to the Web Login Service
    $logout = "${weblogin}/logout?service=" . urlencode($me) .
              urlencode("?logoff=yes");
    //-------------------------------------------------------------
    //
    // For help with problems, look in your Apache web server's error_log
    // file.
    //
    //-------------------------------------------------------------

    //-------------------------------------------------------------
    // This function will call the Web Login Service's validate URL on
    // the service ticket returned when a user logins there.  It returns
    // the elements of the validation response.  See the Web Login
    // Service documentation at
    // http://www.hawaii.edu/infotech/middleware/weblogin/.
    //-------------------------------------------------------------
    function validate($svc, $tkt) {
        global $weblogin;
        // validation URL of the Web Login Service
        $validate_url = "$weblogin/validate" .
                        '?service=' . urlencode($svc) .
                        '&ticket=' . urlencode($tkt);
        // Call the validation service
        error_log('validate(): validating [' . $validate_url . ']');
        $resp = file_get_contents($validate_url );
        if (empty($resp)) {
            error_log('validate(): empty response');
        }
        else {
            // Parse the validation response to get the username and
            // person info for the authenticated user.
            list($status, $uid, $uhuuid, $name, $affil) = explode("\n", $resp);
            if (empty($status)) {
                error_log('validate(): response didn\'t explode');
            }
            return array($status, $uid, $uhuuid, $name, $affil);
        }
        return;
    }

    //-------------------------------------------------------------
    // This part of the script handles calling the Web Login Service
    // to authenticate the user if the user doesn't have a session yet,
    // validating the service ticket after they are authenticated, and
    // handling the user's session which is independent of the
    // authentication with the Web Login Service.
    //-------------------------------------------------------------
    session_start();
    if ($_GET['logoff']) {
        session_destroy();
        header("Location: $me");
        exit;
    }
    if (!session_is_registered('name')) { // not logged in
        $ticket = $_GET['ticket'];
        if (! empty($ticket)) {
            // validate service ticket
            list ($status, $uid, $uhuuid, $name, $affs) =
                validate($me, $ticket);
            if ($status == 'yes') {
                // save data in session
                $_SESSION['name']   = "$name";
                $_SESSION['uid']    = "$uid";
                $_SESSION['affs']   = "$affs";
                $_SESSION['count']  = 1;
                $name = "$name";
                // Get rid of the query parameters in the URL.
                header("Location: $me");  // redirect to me
                exit;
            } else {
                if (empty($status)) {
                    error_log('status is empty');
                    $action = 'network_error';
                }
                else {
                    error_log('status: ' . $status);
                    // tried to reuse the service ticket
                    $action = 'reuse_error';
                    session_destroy();
                }
            }
        }
        else {
            error_log('ticket is empty');
            $action = 'empty_ticket';
        }
    } else {  // previously logged in
        $action = 'continue';
        // get data from session
        $name   = $_SESSION['name'];
        $uid    = $_SESSION['uid'];
        $affs   = $_SESSION['affs'];
        $count  = $_SESSION['count'];
        // bump our counter
        $_SESSION['count']++;
    }
    //-------------------------------------------------------------
    // The HTML portion follows.
    //-------------------------------------------------------------
?>
<html>
  <head>
    <title>Demo of Web Login Service Using PHP</title>
  </head>
  <body>
    <h1>My App</h1>
<?php
    if ($action == 'continue') {
        if ($count == 1) {
?>
     <p>Welcome, <?php echo "$name"; ?>!</p>
<?php
        }
        else {
?>
     <p>Welcome back, <?php echo "$name"; ?>!</p>
<?php
        }
?>
     <p>We know this about you:</p>
     <ul>
       <li>UH username = <?php echo "$uid"; ?><li>
       <li>UH affiliation = <?php echo "$affs"; ?><li>
     </ul>
     <p>This is your <?php echo "$count"; ?> time here.</p>
     <p><a href="<?php echo "$me" ?>">Continue</a></p>
     <p><a href="<?php echo "$me?logoff=yes" ?>">log off (clear session)</a></p>
     <p><a href="<?php echo "$logout" ?>">log off (no more single-signon)</a></p>
<?php
    }
    else {
        if ($action == 'reuse_error') {
?>
     <p>Can't reuse service tickets!</p>
<?php
        }
        else {
?>
     <p><?php echo "Action: $action" ?></p>
<?php
        }
?>
     <p>Please <a href="<?php echo "$login"; ?>">login securely</a> by clicking on the link.</p>
<?php
    }
?>
    </body>
</html>
<?php
    //-------------------------------------------------------------
    // Copyright (c) 2011 University of Hawaii.  All rights reserved.
    //
    // Redistribution and use in source and binary forms, with or without
    // modification, are permitted provided that the following conditions
    // are met:
    //
    // 1. Redistributions of source code must retain the above copyright
    //    notice, this list of conditions and the following disclaimer.
    //
    // 2. Redistributions in binary form must reproduce the above copyright
    //    notice, this list of conditions and the following disclaimer in
    //    the documentation and/or other materials provided with the
    //    distribution.
    //
    // 3. Redistributions of any form whatsoever must retain the following
    //    acknowledgment:
    //    "This product includes software developed by the University of
    //    Hawaii (http://www.hawaii.edu/)."
    //
    // THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY OF HAWAII "AS IS" AND ANY
    // EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    // PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE UNIVERSITY OF HAWAII
    // OR THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    // NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    // HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
    // OF THE POSSIBILITY OF SUCH DAMAGE.
    //-------------------------------------------------------------
?>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     c. An alternative method of using the Web Login Service with PHP is
        available at:
          http://www.hawaii.edu/infotech/webservice/cas.html
        This is some information put together by DLUS for ITS hosted web
        sites and uses PHP's interface to the cURL library.
     d. Here's a JSP demo.  It comes in two JSPs: cas-demo.jsp and the
        supporting cas-handler.jsp.  You'll also need the Java CAS
        client jar which you can get from:
        http://www.ja-sig.org/products/cas/client/javaclient/index.html
        which has a link to casclient-2.1.1.jar.  Install the
        casclient-2.1.1.jar file in your web app's WEB-INF/lib
        directory.  Install the JSP files in your web app's main
        directory.  Point your browser at cas-demo.jsp.
        
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<%
// cas-demo.jsp - Demo of using the Web Login Service with JSPs
//              - 08/21/08, russ@hawaii.edu
//              - Copyright (c) University of Hawaii 2011
//                All rights reserved.
//              - See the end of this file for the LICENSE
%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
  <title>Demo of Sessions Using JSP</title>
</head>

<body>
  <h1>Web Login Demo Client Application</h1>
  <%@ include file="cas-handler.jsp" %>
  <%
  //  For this demo, we are the front page and inside  protected page.
  //  The service URL is the inside page but URL-encoded.
  String frontPage  = request.getRequestURL().toString();
  String insidePage = request.getRequestURL().toString();
  String serviceURL = URLEncoder.encode(insidePage);
  String weblogin   = "https://russ.mgt.hawaii.edu:8443/cas";
  String netId = doWebLogin(request, response, weblogin, frontPage, serviceURL);
  // handle other actions like logging off
  String logoff = request.getParameter("logoff");
  if (logoff != null) {
      logIt("logging off and invalidating session");
      session.invalidate();
      response.sendRedirect(frontPage);
      return;  // bail here or get weird results
  }
  // The main part: show the front page or the inside protected page.
  if (netId == null) { // not logged in --> the outside page
      // show login link
      String loginLink   = weblogin + "/login?service=" + serviceURL;
      logIt("setting loginLink to = " + loginLink);
      logIt("not logged in yet; showing welcome page");
  %>
      <p> Welcome! </p>
      <p>Please <a href="<%= loginLink %>">login securely</a> by clicking
          on the link.</p>
  <%
  }
  else {  // logged in --> the inside protected page
      // show the number of times the user visited me
      Integer visits = (Integer) session.getAttribute("visits");
      if (visits == null) {
          visits = new Integer(1);
          logIt("first visit");
      }
      else {
          visits = new Integer(visits.intValue() + 1);
          logIt("bumped visits to " + visits);
      }
      session.setAttribute("visits", visits);
  %>
      <p> Welcome, <%= netId %> </p>
      <p> Number of visits = <%= visits.toString() %></p>
      <p><a href="<%= frontPage %>"> do it again </a></p>
      <p><a href="<%= frontPage + "?logoff" %>">log off (clear session)</a></p>
  <%
  } // else {  // logged in --> the inside protected page
  %>
  <p>
  <%= (new java.util.Date()).toLocaleString() %>
  </p>
  </body>
</html>
<%
// University of Hawaii LICENSE
//--------------------------------------------------------------------
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in
//    the documentation and/or other materials provided with the
//    distribution.
//
// 3. Redistributions of any form whatsoever must retain the following
//    acknowledgment:
//    "This product includes software developed by the University of
//    Hawaii (http://www.hawaii.edu/)."
//
// THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY OF HAWAII "AS IS" AND ANY
// EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE UNIVERSITY OF HAWAII
// OR THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
// NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
// OF THE POSSIBILITY OF SUCH DAMAGE.
//--------------------------------------------------------------------
%>
<%
// cas-handler.jsp - functions for using the CAS Client library to login
//                   users via the Web Login Service.
//                 - 08/21/08, russ@hawaii.edu
//                 - Copyright (c) University of Hawaii 2008
//                   All rights reserved.
//                 - See the end of this file for the LICENSE
//
//--------------------------------------------------------------------
//  Usage:
//    1. Include this file in your front page JSP.
//    2. Set up these URLS:
//       a. Front page - the advertised to users and they bookmark.
//       b. Inside page - where the application does all the work.
//       c. Service URL - the URL-encode form of the inside page.
//       d. Web Login Service - the one that authenticates users; not us.
//    3. Call the doWebLogin() method to get the netId (a.k.a., username)
//       of the user.  The Web Login Service is the only one to handle
//       the user's credentials.  We'll end with the netId if they
//       authenticate successfully with the Web Login Service.
//
//   Example JSP code:
//
//  String front    = request.getRequestURL().toString();
//  String inside   = request.getRequestURL().toString();
//  String service  = URLEncoder.encode(insidePage);
//  String weblogin = "https://russ.mgt.hawaii.edu:8443/cas";
//
//  String netId = doWebLogin(request, response, weblogin, front, service);
//
//--------------------------------------------------------------------
%>
<%@ page import="edu.yale.its.tp.cas.client.ServiceTicketValidator" %>
<%@ page import="java.net.URLEncoder" %>
<%@ page import="java.io.IOException" %>
<%@ page import="org.xml.sax.SAXException" %>
<%@ page import="javax.xml.parsers.ParserConfigurationException" %>
<%!
// A crude logging method - entry is sent to stderr.
protected void logIt(String msg) {
    String ts = (new java.util.Date()).toLocaleString();
    System.err.println(ts + " " + msg);
}
// Return a netId (a.k.a., username); null if not logged in or
// can't validate the service ticket from the Web Login Service.
protected String doWebLogin(HttpServletRequest req,
                            HttpServletResponse res,
                            String weblogin,
                            String frontPage,
                            String serviceURL) 
throws IOException, SAXException, ParserConfigurationException {
    String validateURL = weblogin + "/serviceValidate";
    HttpSession sess = req.getSession();
    String sessionId = sess.getId();
    logIt("sessionId = " + sessionId);
    String netId = (String) sess.getAttribute("netId");
    logIt("netId from session = " + netId);
    // if there's a service ticket, try to validate it
    String ticket = req.getParameter("ticket");
    logIt("got a ticket: " + ticket);
    if (ticket != null) {
        ServiceTicketValidator validator = new ServiceTicketValidator();
        validator.setCasValidateUrl(validateURL);
        validator.setService(serviceURL);
        validator.setServiceTicket(ticket);
        validator.validate();
        logIt("validation returned: " + validator.getResponse());
        if (validator.isAuthenticationSuccesful()) {
            netId = validator.getUser();
            logIt("authN successful for " + netId);
            // remember the user's username
            sess.setAttribute("netId", netId);
            // redirect back to me to get rid of the ticket in URL
            logIt("redirecting back to " + frontPage);
            res.sendRedirect(frontPage);
            return null;
        }
    }
    return netId;
}
%>
<%
// University of Hawaii LICENSE
//--------------------------------------------------------------------
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
//
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in
//    the documentation and/or other materials provided with the
//    distribution.
//
// 3. Redistributions of any form whatsoever must retain the following
//    acknowledgment:
//    "This product includes software developed by the University of
//    Hawaii (http://www.hawaii.edu/)."
//
// THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY OF HAWAII "AS IS" AND ANY
// EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE UNIVERSITY OF HAWAII
// OR THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
// NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
// OF THE POSSIBILITY OF SUCH DAMAGE.
//--------------------------------------------------------------------
%>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 10. FREQUENTLY ASKED QUESTIONS (FAQ)
     Q: Why does my site automatically login a returning user after they
        logout of their session with my site?
     A: The Web Login Service provides a single sign-on mechanism by
        default.  This is a convenience for the user visiting sites that
        use the Web Login Service.  If you want you make sure your users
        always authenticate themselves to the Web Login Service before
        entering your site, you need to add the renew parameter to your
        login redirect URL.

     Q: Is there a preferred method for logging out users?
     A: Which to use is a judgement call for Web apps.  When in doubt,
        use the Logout URL.  It will always force a user to
        re-authenticate to the Web Login Service.  Not having single
        sign-on is not necessarily a bad thing.
        The general user finds it difficult to understand the security
        implications of the various shades (actually, only two) of
        logging out.  If an app might be used from a kiosk (public use
        PC and browser) it is safer to set things up to logout
        completely using the Logout URL.
        A future enhancement could make single sign-on an option for the
        user so the default will be no single sign-on.  If the user
        chooses to enable single sign-on when authenticating to the Web
        Login Service, only those apps that don't use the renew
        parameter will permit single sign-on if the user doesn't logout
        via the Logout URL from a previously visited app.
     Q: Can anyone use my Web site?
     A: Anyone that is in the UH Core LDAP Directory Service.  In other
        words, current people in the UH System (ten campuses, system
        offices, some RCUH employees) and visitors (temporary guest
        accounts) managed by VIA (www.hawaii.edu/via/).  See section 8
        above.
 11. RESOURCES
     a. If you have questions, contact the ITS IAM Group at 
        its-iam-help@lists.hawaii.edu.  Be sure to provide details.  
        Assistance is only provided to the UH community.
     b. Yale University's Central Authentication Service (CAS)
        URL: http://www.yale.edu/tp/cas/
        NOTE: DO NOT contact Yale University's about Technology and
              Planning department about this installation as the CAS
              software has been modified for UH-specific requirements.
        More recently, CAS became a part of JA-SIG.
        URL:  http://www.ja-sig.org/products/cas/

----------------------------------------------------------------------
vim:ai expandtab tw=72
Browser not supported
