Version 50

    JBoss Federated SSO - Getting Started

     

    IMPORTANT NOTICE:  Please discontinue use of JBoss Federated SSO. You need to use JBoss Identity (http://jboss.org/jbossidentity/) for your needs.

     

    Step 1 - Installation

    • Download JBoss Federated SSO from here : Download

    • Unzip/Untar the distribution on your machine

    • If the src bundle is downloaded, perform the following build steps by going to

          • deploy.dir and jboss.home(ex: deploy.dir=default and/or jboss.home=c:/jboss-4.0.4.GA)

          • After the build installSSO is successfull, you should see a jboss-sso.sar in the deploy directory of your server configuration

       

      • Install the SSO Federation Server by going to

       

       

       

      Step2 - Configure the Identity Management Framework

       

      • Look at the following configuration in jboss-sso.sar/conf/sso.cfg.xml

       

         <!-- 
                identity management related configuration, this is the LDAP based module
                Technically, this can be a provider that can integrate with thirdparty identity systems like SiteMinder etc
           -->
           <identity-management>
                <login>
                     <provider id="si:jboss-sso:ldap:login" class="org.jboss.security.idm.ldap.LDAPIdentityProvider">
                          <property name="connectionURL">
                               jdbc:ldap://localhost:389/dc=jboss,dc=com?SEARCH_SCOPE:=subTreeScope&secure:=false&concat_atts:=true&size_limit:=10000000
                          </property>
                          <property name="username">cn=Admin,dc=jboss,dc=com</property>
                          <property name="password">jbossrocks</property>
                          <property name="identityOu">jbosssso</property>
                          <property name="roleOu">role</property>
                     </provider>
                </login>          
           </identity-management>
      

         

        • JBoss Federated SSO ships with an LDAP provider that integrates with an LDAP repository using the standard inetOrgPerson schema for user information, and organizationUnit schema for storing role information. This has been tested successfully with OpenLDAP and Red Hat Directory Server. Further support for other LDAP repositories like OpenDS, Microsoft Active Directory etc is on the roadmap

         

        • If you do not have an LDAP repository and want to use the test application out-of-the-box, you can try the bundled DemoLoginProvider. You have to ensure, that your Locale is set to "en", because the user storage is in the properties file users_en.properties in jboss-identity-management.jar. In any other case this provider won't work. An alternative is to create an users.properties file for your Locale (e. g. users_de.properties).

         

        • If you need to integrate with a custom Identity Store for you specific web application, all you will need to do is implement the org.jboss.security.idm.LoginProvider interface and integrate that implementation in the above provider configuration.

         

        • Here is the LoginProvider interface
          /*
          * JBoss, Home of Professional Open Source
          * Copyright 2005, JBoss Inc., and individual contributors as indicated
          * by the @authors tag. See the copyright.txt in the distribution for a
          * full listing of individual contributors.
          *
          * This is free software; you can redistribute it and/or modify it
          * under the terms of the GNU Lesser General Public License as
          * published by the Free Software Foundation; either version 2.1 of
          * the License, or (at your option) any later version.
          *
          * This software is distributed in the hope that it will be useful,
          * but WITHOUT ANY WARRANTY; without even the implied warranty of
          * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
          * Lesser General Public License for more details.
          *
          * You should have received a copy of the GNU Lesser General Public
          * License along with this software; if not, write to the Free
          * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
          * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
          */
          package org.jboss.security.idm;
          
          import java.security.Principal;
          import java.util.Collection;
          
          /**
           * 
           * @author Sohil Shah - sohil.shah@jboss.com - Sep 20, 2006
           *
           */     
          package org.jboss.security.idm;
          
          import java.security.Principal;
          import java.util.Collection;
          
          public interface LoginProvider 
          {
              /**
               * id should be of the form: si:<a unique string such as vendor name, etc. eg. jboss>:<optional parameter>
               * @return
               * @throws IdentityException
               */
              public String getId() throws IdentityException;
              
              /**
               * 
               * @param principal
               * @return
               * @throws IdentityException
               */
              public Identity read(Principal principal) throws IdentityException;
              public Identity read(String username) throws IdentityException;
              
              /**
               * 
               * @param principal
               * @return
               * @throws IdentityException
               */
              public boolean exists(Principal principal) throws IdentityException;
              public boolean exists(String username) throws IdentityException;
              
              /**
               * 
               * @param principal
               * @param password
               * @return
               * @throws IdentityException
               */
              public boolean login(Principal principal,byte[] password) throws IdentityException;
              public boolean login(String username,byte[] password) throws IdentityException;
              
              /**
               * 
               * @return
               * @throws IdentityException
               */
              public Collection readAllRoles() throws IdentityException;
          }
          

             

             

             

            Step3 - Configure the Federated SSO Trust Server

             

            • Look at the following configuration in jboss-sso.sar/conf/sso.cfg.xml

               <!-- sso processor for SingleSignOn, the default JBossSingleSignOn processor uses OpenSAML-1.0, 
                 the next version of this processor will use the latest SAML specification 
                 -->
                 <sso-processor>
                      <processor class="org.jboss.security.saml.JBossSingleSignOn">
                           <property name="trustServer">http://node1.jboss.org:8080/federate/trust</property>
                      </processor>
                 </sso-processor>
            

               

              • Note: The Trust Server is integrated with the Federation Server and will deploy when the jboss-federation-server.ear file is deployed in the application server.

               

               

              Step4 - Configure your web application to activate Federated SSO

               

              • The SSO Framework has support for web applications that use their own mechanism for performing authentication as well as web applications that use container provided JAAS infrastructure for performing authentication. Depending on which one of the two authentication strategies are used, there is a corresponding set of instructions to integrate with the SSO Engine. These instructions are provided here: Web Application Integration

               

              Step5 - Testing your installation with the bundled test application

               

              • Install jboss-sso-test.ear into the 'deploy' directory of the 'default' configuration

               

              • run -c default -b node1.jboss.com

               

              • Now create an exact same copy of 'default' configuration and name it 'default2'

               

              • run -c default2 -b node1.jboss.org (for cross domain test) or run -c default2 -b node2.jboss.com (for same domain test)

               

               

              • Note: On Windows add the following entries to your hosts file to simulate applications running on different web domains

               

                  127.0.0.1        node1.jboss.com

                  127.0.1.1        node1.jboss.org

                  127.0.2.1        node2.jboss.com

               

               

              Conclusion - Congratualations. Your application is Federated SSO Enabled. What comes next?

               

              • If the above mentioned steps are successfull, you should be able to log in to your web application, and after successfully log in you should see a SAML Token in the form of domain cookie called token in your browser.

               

              • One thing to make sure is when you run your web application locally, run it with some kind of a domain name from the browser like, local.xyz.com instead of localhost. Since localhost does not represent a real domain the SAML token will not be placed.

               

              • Once these steps are successfull, your web application is what we call "Federated Single Sign On Enabled". With the help of a Federation Server you can perform Federated cross-domain Single Sign On inside a collection of partner sites that are members of this Federation. Please see here for details about setting up the Federation Server - Federation Server Setup