spacer
 spacer
 spacer
The FuseTalk External Authentication Module
Platform: ColdFusion

  • What Is the External Authentication Module?
  • Preparing to use the External Authentication Module
  • The External Authentication Wizard
  • Cookie Authentication (Wizard)
  • Session Authentication (Wizard)
  • External Authentication Scripting
  • The Code Explained

    This guide is meant as a supplement to the documentation provided in the global administration area. Please read the external authentication documentation along with this article. You can find a copy of the documentation here.

    WHAT IS THE EXTERNAL AUTHENTICATION MODULE?
    The External Authentication Module (EAM) is a very flexible feature of FuseTalk which lets you integrate a login system, which your website currently uses. This means that if a user has already performed a login procedure on your website, once they hit FuseTalk, the user will not have to login a second time.

    The EAM is very flexible and can be integrated with any authentication system which you are currently using. The EAM is divided in two different modules. If you are using Cookies or Sessions on your website to keep the user state, you can use the external authentication wizard. If you are using any other method to keep state on your website you can use the open concept login templates which are described in detailed below.

     PREPARING TO USE THE EXTERNAL AUTHENTICATION MODULE
    Since the EAM uses credentials that have been entered on your web site, FuseTalk requires you to pass a few details in order for the authentication to happen. The required details are, username, e-mail address, first name, and last name. Each section will describe how to pass this information to FuseTalk.

     THE EXTERNAL AUTHENTICATION WIZARD
    The external authentication wizard is a very innovative feature which lets you setup your authentication in a few minutes. The wizard only works with stand-alone forums. For global forums proceed to "EXTERNAL AUTHENTICATION SCRIPTING". Follow the steps below to start the wizard:

    1.Login to the Global Administrator.
    2.Enter the "Forums - Management" section.
    3.Update the forum you wish to use the wizard with by selecting the update icon, the update forum window will open.
    4.Select the "authentication" tab.
    5.Select "Yes" for the External Authentication setting and click the "Update Settings" button.
    6.Select "Yes" for the User Authentication Wizard setting and click the "Update Settings" button.
    7.A javascript alert box will appear telling you that the current users who are attached to the forum will no longer be able to login through FuseTalk. This is because the login button will disappear. Click on OK.
    8.Select the "Open Authentication Wizard" Link.

     COOKIE AUTHENTICATION (WIZARD)
    The following are step by step details on how to setup cookie authentication with the wizard.

    1.Select the "next" button of the first welcome screen of the wizard.
    2.On the second screen (selecting the authentication method) select "Cookies" and select the next button.

    NOTE: FuseTalk assumes that the cookie which will be read by FuseTalk contains a "key" to data which is available in a database. For example, your cookie might contain a user ID which references a record in the table of your database. FuseTalk also assumes that you can get the required details (username, first and last name and e-mail address from the query). This is an example of a query.

    Select username, email, firstname, lastname from employees
    where employeeid = #cookie.employeeid#

    Notice that in the query we make reference to the cookie using standard ColdFusion syntax (#cookie.employeeid#). If you are not familiar with ColdFusion syntax, the #cookie.employeeid# means to access a cookie name employeeid.

    3.Enter the Query information to retrieve the required details, in the text box provided.
    4.Enter the "Datasource" name which points to the database that you are accessing in the query.
    5.If your datasource requires you to login, enter the username and password in "DB Username" and "DB Password".
    6.Enter the username, e-mail address, firstname and lastname field information.

    In our case this is how step 3 of the wizard would look like:


    7.Select the "Next" button, to proceed.
    8.The fourth screen off the wizard lets you decide if your users require to login before accessing FuseTalk. If they do require to login select the "Yes" radio button, and enter the URL of the login template on your website. (The login template will be the location where the user is redirected if a user attempts to access FuseTalk without being logged in.) If you wish for users to be able to browser the forums without being logged in, select the "No" radio button.
    9.Select the "Next" button, to proceed.
    10.The fifth screen is a review of your information. Ensure that the information entered is correct, if so select the "Finish" button.

    You have completed the authentication wizard and you are now ready to try it out. To do so login on your web site, then enter FuseTalk. You should be logged in.

     SESSION AUTHENTICATION (WIZARD)
    The following are step by step details on how to setup session authentication with the wizard.

    1.Select the "next" button of the first welcome screen of the wizard.
    2.On the second screen (selecting the authentication method) select "Sessions" and select the next button.

    NOTE: For the session wizard to be successful FuseTalk requires that you have the required information in session variables. This means that the username, e-mail address, firstname and lastname need to be contained in session variables. FuseTalk also requires that you know the name of the Application of your website.

    i.e. If the application tag is <cfapplication name="MyApplication" …..>, the name of your application would be MyApplication.

    3.Enter the username, e-mail address, firstname and lastname session information.
    4.Enter the "application name".

    In our case this is how step 3 of the wizard would look like:


    5.Select the "Next" button, to proceed.
    6.The fourth screen off the wizard lets you decide if your users require to login before accessing FuseTalk. If they do require to login select the "Yes" radio button, and enter the URL of the login template on your website. (The login template will be the location where the user is redirected if a user attempts to access FuseTalk without being logged in.) If you wish for users to be able to browser the forums without being logged in, select the "No" radio button.
    7.Select the "Next" button, to proceed.
    8.The fifth screen is a review of your information. Ensure that the information entered is correct, if so select the "Finish" button.

    You have completed the authentication wizard and you are now ready to try it out. To do so login on your web site, then enter FuseTalk. You should be logged in.

     EXTERNAL AUTHENTICATION SCRIPTING
    If, for various reasons, you cannot use the External Authentication Wizard you can script your own authentication using login templates which can be edited. It is very useful to understand all the steps that make this feature work.


    1.A user enters FuseTalk from your web site.
    2.FuseTalk detects that the Authentication Module has been enabled for the specified forum and includes the authentication module in the process.
    3.FuseTalk uses the custom scripts that you have created to authenticate the user.
    4.Using variables that your custom scripts will set, FuseTalk detects if the user is validated. If the user has been validated, FuseTalk performs the necessary steps to log in the user. Also, since FuseTalk is a highly customizable system, you need a record for the user in your FuseTalk database. During this step FuseTalk checks the FuseTalk database to see if a record already exists for the user: if not, a new record is created.
    5.The Authentication Feature sends the user information back to FuseTalk, which can then perform normal operations as though the user was always logged in.

    Now that you understand how this feature interacts with FuseTalk, you are ready to open the authentication template and create your own authentication scripts. In our example we will be using Cookies to login the users, and the user will be required to login before browsing the forums. Follow these steps to create your external authentication scripts.

    1.Login to the Global Administrator.
    2.Enter the "Forums - Management" section.
    3.Update the forum you wish to use the wizard with by selecting the update icon, the update forum window will open.
    4.Select the "authentication" tab.
    5.Select "Yes" for the External Authentication setting and click the "Update Settings" button.
    6.Ensure that "No" is selected for the User Authentication Wizard setting and click the "Update Settings" button.
    7.Open the login.cfm template located in the forum/modules/authentication directory if you are using this for a STAND-ALONE forum. Open the loginglobal.cfm template located in the forum/modules/authentication directory if you are using this for a GLOBAL forum. Your authentication scripts should go between these comments:

    <!--- INSERT CODE HERE --->

    YOUR SCRIPT GOES HERE

    <!--- END CODE HERE --->

    8.Insert the following script between the comments.

    <cfif not isDefined("cookie.mysitecookie")>
        <cflocation url="http://www.mywebsite.com/login.cfm">
    </cfif>

    <cfquery name="GetUserDetails" datasource="myds">
        select username, emailaddress, firstname, lastname from myusers
        where userid = #cookie.mysitecookie#
    </cfquery>

    <cfif GetUserDetails.recordcount eq 0>
        <cflocation url="http://www.mywebsite.com/login.cfm">
    </cfif>

    <cfset FTVAR_NICKNAMEFRM = GetUserDetails.username>
    <cfset FTVAR_FIRSTNAMEFRM = GetUserDetails.firstname>
    <cfset FTVAR_LASTNAMEFRM = GetUserDetails.lastname>
    <cfset FTVAR_EMAILADDRESSFRM = GetUserDetails.emailaddress>

    <cfset FTVAR_PROCEED = "Yes">
    <cfset FTUSER_LOGGEDIN = "Yes">

    9.Save your template. Because FuseTalk is a multi-forum system you will need to save the template you created with the filename that has the following format: login<forumid>.cfm. Replace the <forumid> with the ID of the forum. The forum ID can be retrieved by entering the global administration area and searching for the forum under "FORUMS - Management". The ID can be found in the first column. If you are using a global forum, you do not need to do this since you should have edited the loginglobal.cfm template.

    You have completed the authentication script and you are now ready to try it out. To do so login on your web site, then enter FuseTalk. You should be logged in.

    Now that you know how to create the scripts let us explain what the script means.

     THE CODE EXPLAINED
    This command states that if the cookie named mysitecookie does not exists, redirect the user to http://www.mywebsite.com/login.cfm. In our case this is the location the user would need to login on to our web site in order to access FuseTalk.

    <cfif not isDefined("cookie.mysitecookie")>
        <cflocation url="http://www.mywebsite.com/login.cfm">
    </cfif>
    This command retrieves the required details from a database.

    <cfquery name="GetUserDetails" datasource="myds">
        select username, emailaddress, firstname, lastname from myusers
        where userid = #cookie.mysitecookie#
    </cfquery>
    This command states that if the query does not return any rows (because the user doesn't exist, or the cookie does not have a correct value) re-direct the user to the login template on your web site.

    <cfif GetUserDetails.recordcount eq 0>
        <cflocation url="http://www.mywebsite.com/login.cfm">
    </cfif>
    These commands set the firstname, lastname, username and email address of the user.

    <cfset FTVAR_NICKNAMEFRM = GetUserDetails.username>
    <cfset FTVAR_FIRSTNAMEFRM = GetUserDetails.firstname>
    <cfset FTVAR_LASTNAMEFRM = GetUserDetails.lastname>
    <cfset FTVAR_EMAILADDRESSFRM = GetUserDetails.emailaddress>
    These command set other required variables for FuseTalk. If the FTVAR_PROCEED variable is set to "No", the authentication process would stop at the end of this template, if the FTUSER_LOGGEDIN variable would be set to "No" the user would not be logged in FuseTalk.

    <cfset FTVAR_PROCEED = "Yes">
    <cfset FTUSER_LOGGEDIN = "Yes">
    Below is a representation of these steps with an explanation. There are six variables which will require your attention during the scripting process. These are them with a description:

    FTVAR_PROCEED:This variable determines if the user has been validated once your scripts are finished. By default the value is YES. You will need to set the value to NO if the user has not been validated.
    FTUSER_LOGGEDIN:This variable is used by FuseTalk to determine if a user is logged in or not. By default when the authentication module is turned on the value is YES. You will need to set the value to NO if the user is not validated.
    FTVAR_NICKNAMEFRM:This variable is used by FuseTalk and should contain the user's username.
    FTVAR_EMAILADDRESSFRM:This variable is used by FuseTalk and should contain the user's e-mail address.
    FTVAR_LASTNAMEFRM:This variable is used by FuseTalk and should contain the user's last name. If you do not have leave blank.
    FTVAR_FIRSTNAMEFRM:This variable is used by FuseTalk and should contain the user's first name. If you do not have leave blank.

    Hopefully this article has given you a better understanding on how the external authentication system of FuseTalk works. If you have any other questions about external authentication please do not hesitate to contact     support@fusetalk.com. Also there are numerous example in the documentation an in the samples directory of your FuseTalk install that will help guide you through the process.

    To discuss this article or to ask question please visit our forums.