webuijsf
Tag login


Use the webuijsf:login component to authenticate users. By default the tag is linked to a JAAS(Java Authentication and Authorization Service) based infrastructure. Application developers can write LoginModule implementations suited to their needs. For more details on how to write JAAS LoginModule applications see the following link: http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html. The JAAS configuration containing the LoginModule impl entries should be added to the config file if one exists or a new file should be created and specified using the appropriate Djava parameter. The webuijsf:login tag allows you to insert HTML elements like textfield, statictext, dropdowns, listboxes, labels to prompt users to enter authentication data. The prompts that need to be displayed are usually controlled at the server side by the loginModule implementation classes.

Configuring the login tag

Use the serviceName attribute to identify the underlying authentication service.

Use the value to capture the resuolt of the authentication process. For the default JAAS based backend the value of the authentication process is the Subject object representing the authenticated Principal and credential objects.

Use the redirectURL to specify a URL to redirect to after successful authentication.

Set the autoStart attribute to true to initiate the authentication process on its own without any client side intervention or wait for some other client side entity to start the authentication process. By default this attribute is set to true. In situations where the authentication process needs to start based on other events happening on the client side this attribute should be set to false and the appropriate client side API used to fire up the process.


Client-side JavaScript Functions

When the component is rendered, a DOM object corresponding to the component is created. Subscribing to well known events is the only way to interact with the login widget. The widget publishes events announcing success or failure of the authentication process. Applications should use these events to figure out what to do next. Applications can also use the authenticate() function to kick start the authentication process.

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
authenticate() Use this function to start the authentication process if you do not want the process to start when the page loads.
setProps(props) Use this function to change any of the following supported properties. Generally, setProps() should only be called by function that is handling the result of an authentication to the underlying server side.
  • id - ID of the login widget.
  • loginState - State of the authentication process.
  • autoStart - Flag indicating if authentication process should start on page load.
  • userData - JSON object containing user data that needs to be displayed as user prompt.
  • keys - JSON object representing the key value mapping for user data fields
  • style
  • tabIndex
  • className
subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to.
  • obj: The object in which a function will be invoked, or null for default scope.
  • func The name of a function in context, or a function reference to invoke when topic is published.

Client Side JavaScript Events

Based on the result of the authentication process, some functions may publish event topics for custom AJAX implementations to listen for. See example2 below.


The following events are supported.

<Node>.event.authenticate.beginTopic Event topic published before asynchronously authenticating the component. Supported properties include:
id: this.id, loginState: this.loginState, keys: this.keys, endTopic: <Node>.event.authenticate.endTopic
  • loginState - the current state of the authentication process
  • keys - the set of key value pairs representing user/credential information
  • id - The client id to process the event for
<Node>.event.authenticate.endTopic Event topic published after asynchronously authenticating the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
<Node>.event.result.successTopic Event topic published when the asynchronously submitted authentication process has succeeded. Supported properties include:
  • id - The client id to process the event for
<Node>.event.result.failureTopic

Event topic published when the asynchronously submitted authentication process has failed. Supported properties include:

  • id - The client id to process the event for

Examples

For all the examples below one of the following JAAS configuration entries have been used.

AppLogin1 {
com.sun.webui.jsf.example.login.TestLoginModule optional;
};

AppLogin2 {
com.sun.webui.jsf.example.login.TestLoginModule2 requisite;
com.sun.webui.jsf.example.login.TestLoginModule3 requisite;
};

Example 1: Basic login example with single LoginModule

<webuijsf:login id="login1" redirectURL="/example/faces/login/result.jsp"
serviceName="AppLogin1" value="#{LoginBean.value}" />

Example 2: Login example showing use of events


<webuijsf:script>
    function init() {
        var domNode = document.getElementById("form1:login3");
        if (domNode == null || domNode.event == null) {
            return setTimeout('init();', 10);
        }
        domNode.subscribe(domNode.event.result.successTopic, this, handleEvent);
        domNode.subscribe(domNode.event.result.failureTopic, this, handleFailureEvent);
    }

    this.handleEvent = function(id) {
        var loc = document.location;
        var newURL = loc.protocol + "//" + loc.host;
        newURL = newURL + "/example/faces/login/result.jsp";
        document.location.href = newURL;
    }

    this.handleFailureEvent = function(id) {
        var loc = document.location;
        var newURL = loc.protocol + "//" + loc.host;
        newURL = newURL + "/example/faces/login/failed.jsp";
        document.location.href = newURL;
    }
</webuijsf:script>

<webuijsf:body onLoad="init();">
<webuijsf:form id="form1">
<webuijsf:masthead id="Masthead" productImageURL="/images/webconsole.png"
  productImageDescription="Java Web Console" userInfo="test_user"
  serverInfo="test_server" />

<webuijsf:login id="login3" value="#{LoginBean.value}" serviceName="AppLogin1"/>

</webuijsf:form>
</webuijsf:body>


Example 3: Login example using two LoginModule implementations.


<webuijsf:login id="login2" value="#{LoginBean.value}" serviceName="AppLogin2" />

Example 4: Secondary login example

<webuijsf:head>
<webuijsf:script>
    function init() {
        var domNode = document.getElementById("form1:secondary");
        if (domNode == null || domNode.event == null) {
            return setTimeout('init();', 10);
        }
        domNode.subscribe(domNode.event.result.successTopic, this, handleSuccessEvent);
        domNode.subscribe(domNode.event.result.failureTopic, this, handleFailureEvent);
    }

    this.handleSuccessEvent = function(id) {
        // show the common task page after successful authentication
        var cts = document.getElementById("form1:ctp1");
        cts.style.display = "block";
    }

    this.handleFailureEvent = function(id) {
        // show the retry button
        var loginDiv = document.getElementById("form1:secondary");
        loginDiv.style.display = "none";
        var btn = document.getElementById("form1:retry");
        btn.style.display = "block";
    }
<webuijsf:script>

</webuijsf:head>
<webuijsf:body id="body" onLoad="init();" styleClass="#{themeStyles.CTS_BACKGROUND}">
  <webuijsf:form id="form1">

    <webuijsf:login id="secondary" value="#{LoginBean.value}" serviceName="AppLogin1" />

    <webuijsf:button id="retry" text="Authentication Failed, Retry"
      toolTip="Try Authenticating Again" style="display:none"
      onClick="var login = document.getElementById('form1:login1'); login.style.display='block'; login.authenticate();" />

    <webuijsf:commonTasksSection style="display:none" id="ctp1">
        <webuijsf:commonTasksGroup id="taskGroup1" title="#{msgs.commontask_group1}">
            <webuijsf:commonTask id="task1" text="#{msgs.commontask_task1}"
              toolTip="#{msgs.commontask_task1}" actionExpression="#{commonTask.taskAction}"
              target="_blank" icon="CTS_OVERVIEW">
            <webuijsf:commonTask>
            <webuijsf:commonTask id="task2" text="#{msgs.commontask_task2}" toolTip="#{msgs.commontask_task2}"
              onClick="popup();return false;" infoTitle="#{msgs.commontask_task2infotitle}"
              infoText="#{msgs.commontask_task2infotext}" />
        </webuijsf:commonTasksGroup>
        <webuijsf:commonTasksGroup id="taskGroup2" title="#{msgs.commontask_group2}">
            <webuijsf:commonTask id="task3" text="#{msgs.commontask_task3}" toolTip="#{msgs.commontask_task3}"
               onClick="popup();return false; " infoLinkUrl="/faces/commontask/sample.jsp"
               infoLinkText="#{msgs.commontask_infolinktext}" infoTitle="#{msgs.commontask_task3infotitle}"
               infoText="#{msgs.commontask_task3infotext}"/>
            <webuijsf:commonTask id="task4" text="#{msgs.commontask_task4}" onClick="popup();return false;"
               toolTip="#{msgs.commontask_task4}"/>
            <webuijsf:commonTask id="task5" text="#{msgs.commontask_task5}"
               onClick="popup();return false;" infoTitle="#{msgs.commontask_task5infotitle}"
               toolTip="#{msgs.commontask_task5}" infoText="#{msgs.commontask_task5infotext}"/>
         </webuijsf:commonTasksGroup>
          ...
</webuijsf:body>
<webuijsf:script type="text/javascript">
    function popup() {
        var popupWin = window.open('/example/faces/commontask/sample.jsp', 'Test Page',
        'scrollbars,resizable,width=650,height=500,top='+((screen.height - (screen.height/1.618)) - (500/2))+',left='+((screen.width-650)/2) );
        popupWin.focus();
    }
<webuijsf:script>




Tag Information
Tag Classcom.sun.webui.jsf.component.LoginTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
loginControllerfalsefalsejava.lang.String

The login controller implementation class name. The controller must implement the LoginController interface. If this attribute is not supplied the default JAAS controller will be used. This attribute provides the application developer to use a non JAAS based authentication implementation with the same presentation layer.

htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
styleClassfalsefalsejava.lang.String

CSS style class(es) to be applied to the outermost HTML element when this component is rendered.

immediatefalsefalsejava.lang.String

Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase. May be desired for this component when required is true (although most likely not).

serviceNamefalsefalsejava.lang.String

The name of an entry in the JAAS login configuration file. This is the name for the LoginContext to use to look up an entry for this application in the JAAS login configuration file, described here. Such an entry specifies the class(es) that implement the desired underlying authentication technology(ies).

stylefalsefalsejava.lang.String

CSS style(s) to be applied to the outermost HTML element when this component is rendered.

redirectURLfalsefalsejava.lang.String

Defines the URL to which the user should be redirected upon successful authentication.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

autoStartfalsefalsejava.lang.String

A boolean attribute indicating if the login component should initiate the authentication process on its own without any client side intervention or wait for some other client side entity to start the authentication process. By default this attribute is set to true. In situations where the authentication process needs to start based on other events happening on the client side this attribute should be set to false and the appropriate client side API used to fire up the process.

valuefalsefalsejava.lang.StringNo Description
converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

renderedfalsefalsejava.lang.String Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
idfalsetruejava.lang.StringNo Description

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.