For custom authentication, the client application passes credentials to the server without relying on the browser. Although you apply security constraints to a destination, you actually log in and log out of the channels associated with the destination. Therefore, to send authentication credentials to a destination that uses custom authentication, you specify a user name and password as arguments to the ChannelSet.login() method. You remove credentials by calling the ChannelSet.logout() method.

Because multiple destinations can use the same channels, and corresponding ChannelSet object, logging in to one destination logs the user in to any other destination that uses the same channel or channels. If two components apply different credentials to the same ChannelSet object, the last credentials applied are used. If multiple components use the same authenticated ChannelSet object, calling the logout() method logs all components out of the destinations.

The login() and logout() methods return an AsyncToken object. Assign event handlers to the AsyncToken object for the result event to handle a successful call, and for the fault event to handle a failure.

How the server processes the logout() method depends on the setting of the per-client-authentication property:

• If the per-client-authentication property is false (default), the logout() method invalidates the current session. A new FlexSession object is automatically created to replace it, and the new session does not contain any attributes or an authenticated information. If authentication information is stored at the session level, and a client disconnect results in the FlexSession being invalidated, authenticated information is also cleared.
• If the per-client-authentication property is true, the logout() method clears the authentication information stored in the FlexClient object, but does not invalidate the FlexClient object or FlexSession object.

Custom authentication example

The following example uses the ChannelSet.login() and ChannelSet.logout() methods with a RemoteObject control. This application performs the following actions:

• Creates a ChannelSet object in the creationComplete handler that represents the channels used by the RemoteObject component.
• Passes credentials to the server by calling the ROLogin() function in response to a Button click event.
• Uses the RemoteObject component to send a String to the server in response to a Button click event. The server returns the same String back to the RemoteObject component.
• Uses the result event of the RemoteObject component to display the String in a TextArea control.
• Logs out of the server by calling the ROLogout() function in response to a Button click event.

<?xml version="1.0"?>
<!-- security/SecurityConstraintCustom.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="100%" height="100%"
    creationComplete="creationCompleteHandler();">

    <mx:Script>
        <![CDATA[
            import mx.controls.Alert;
            import mx.messaging.config.ServerConfig;
            import mx.rpc.AsyncToken;
            import mx.rpc.AsyncResponder;
            import mx.rpc.events.FaultEvent;
            import mx.rpc.events.ResultEvent;
            import mx.messaging.ChannelSet;

            // Define a ChannelSet object.
            public var cs:ChannelSet;
            
            // Define an AsyncToken object.
            public var token:AsyncToken;

            // Initialize ChannelSet object based on the 
            // destination of the RemoteObject component.
            private function creationCompleteHandler():void {
                if (cs == null)
                    cs = ServerConfig.getChannelSet(remoteObject.destination);                    
            }

            // Login and handle authentication success or failure. 
            private function ROLogin():void {
                // Make sure that the user is not already logged in.
                if (cs.authenticated == false) {
                    token = cs.login("sampleuser", "samplepassword");
                    // Add result and fault handlers.
                    token.addResponder(new AsyncResponder(LoginResultEvent, LoginFaultEvent));
                }
            }

            // Handle successful login.
            private function LoginResultEvent(event:ResultEvent, token:Object=null):void  {
                switch(event.result) {
                    case "success":
                        authenticatedCB.selected = true;
                    break;
                    default:
                }
            }
            
            // Handle login failure.
            private function LoginFaultEvent(event:FaultEvent, token:Object=null):void {
                switch(event.fault.faultCode) {
                    case "Client.Authentication":
                        default:
                            authenticatedCB.selected = false;
                            Alert.show("Login failure: " + event.fault.faultString);
                }
            }

            // Logout and handle success or failure.
            private function ROLogout():void {
                // Add result and fault handlers.
                token = cs.logout();
                token.addResponder(new AsyncResponder(LogoutResultEvent,LogoutFaultEvent));
            }

            // Handle successful logout.
            private function LogoutResultEvent(event:ResultEvent, token:Object=null):void {
                switch (event.result) {
                    case "success":
                        authenticatedCB.selected = false;
                        break;
                    default:
                }
            }

            // Handle logout failure.
            private function LogoutFaultEvent(event:FaultEvent, token:Object=null):void {
                Alert.show("Logout failure: " + event.fault.faultString);
            }

            // Handle message recevied by RemoteObject component.
            private function resultHandler(event:ResultEvent):void {
                ta.text += "Server responded: "+ event.result + "\n";
            }

            // Handle fault from RemoteObject component.
            private function faultHandler(event:FaultEvent):void {
                ta.text += "Received fault: " + event.fault + "\n";
            }
        ]]>
    </mx:Script>

    <mx:HBox>
        <mx:Label text="Enter a text for the server to echo"/>
        <mx:TextInput id="ti" text="Hello World!"/>
        <mx:Button label="Login" 
            click="ROLogin();"/>
        <mx:Button label="Echo"  
            enabled="{authenticatedCB.selected}"
            click="remoteObject.echo(ti.text);"/>
        <mx:Button label="Logout" 
            click="ROLogout();"/>
        <mx:CheckBox id="authenticatedCB" 
            label="Authenticated?" 
            enabled="false"/>
    </mx:HBox>
    <mx:TextArea id="ta" width="100%" height="100%"/>

    <mx:RemoteObject id="remoteObject"
        destination="remoting_AMF_SecurityConstraint_Custom"
        result="resultHandler(event);"
        fault="faultHandler(event);"/>
</mx:Application>

Configure Tomcat for custom authentication

Perform the following configuration steps to use custom authentication with Tomcat:

1. Place the flex-tomcat-common.jar file in the tomcat/lib/blazeds directory.
2. Place the flex-tomcat-server.jar file in the tomcat/lib/blazeds directory.
3. Edit the tomcat/conf/catalina.properties file to add the following path to the common.loader property:

   ${catalina.home}/lib/blazeds/*.jar
   
   

4. Edit the tomcat/conf/context.xml file to add the following tag to the Context descriptors:

   <Valve className="flex.messaging.security.TomcatValve"/> 
   
   

5. Restart Tomcat.

You can now authenticate against the current Tomcat realm. Typically user information is in the conf/tomcat-users.xml file. For more information, see the Tomcat documentation.