Single Sign On

This page reviews Single Sign-On solutions in netFORUM.

Please note that all links on this form are generic and will need to be reviewed to match the configuration of the site where this will be implemented. Particular sections which should be checked:

Domain of the eWeb site - the examples on this page use http://members.naxyz.org/eWeb to represent the eWeb site. Also, if this is being implemented on a test site first, please be sure to include that portion of the URL as necessary (i.e. http://members.naxyz.org/netFORUMNAXYZTest/eweb)
Domain of the SSO site - the examples on this page use http://www.naxyz.org to represent the site that should be logged into with eWeb.
Site - this is a parameter which indicates which eWeb site to use. The examples on this page use NAXYZ, and in most cases, the site code is the client's acronym, but may not be.
Token - this is a query string parameter used when eWeb is not the login page and should be named based on the Site. The examples on this page use NAXYZ as the site, so the token is named NAXYZToken. This value must be based on the value of the Site (*Site*Token)

Single Sign-On Without eWeb

If you have a website and you need to implement single sign-on, and you are not using NetForum eWeb, but you do want to store usernames and passwords in NetForum, then here is how you can do this.

User names and Passwords are stored for each customer in NetForum. You can develop a login page on which you prompt the user for their user name and password. You can validate their entry by calling either the WebLogin or WEBWebUserLogin web methods in xWeb. The latter web method has more functionality and is recommeneded if your version of NetForum xWeb is recent enough to have this web method. With WEBWebUserLogin, the return will contain the user's Customer Key and other information.

If you want to implement a feature to allow a user to change their password, or if they forgot their password, see XWeb:UpdateFacadeObject customer password for a case study, or use the WEBWebUserChangePassword web method.

Single Sign-On With eWeb - eWeb Login

If you are using eWeb as the website on which users log in, then we recommend using this baseline solution, available in the 2008.01.02 and 2007.01.05 releases (and later).

In this solution, if a third-party application wants to log in a user, the application should Response.Redirect the user to a special eWeb page called the LoginRequired page, and include specific querystring parameters that will specify which page in the third-party application the user should be directed back to, upon successful login. You will get back a special Token that you can use later to authenticate the user's identity in netFORUM.

LoginRequired Page

The URL of the Login Required page in eWeb will take this form:

http://members.naxyz.org/eweb/DynamicPage.aspx?Site=ZZZ&WebCode=LoginRequired&URL_success=http://www.naxyz.org/MemberPage.cfm?userToken={token}

A successful login will return the user to the URL address specified in the URL_success querystring parameter, which in the example above would be:

http://www.naxyz.org/MemberPage.cfm?userToken=f5ec2fb9-af17-44c8-8461-d939998f2a56

Observe how the guid f5ec2fb9-af17-44c8-8461-d939998f2a56 has replaced {token}. (Of course, this values is made up; you will get a different value every time.)

Let's deconstruct this URL and its parameters:

Base URL - http://members.naxyz.org/eweb/DynamicPage.aspx? is the base URL of the NetForum eWeb site
Site - The Site parameter will be the Web Site code for (presumably) the default web site; this parameter is required.
WebCode - The WebCode=LoginRequired is a standard eWeb page that will process the request. This is required.
URL_success - indicates the URL on the third-party website to which you want NetForum to return the user. You must embed in this URL's querystring ?userToken={Token}. Depending on how your third-party application is structured, this URL_success could be a single "landing" page that acts as a switcher, or the page the user is trying to access, etc. You may embed other querystring parameters as well that could be used by your application; eWeb will send those right back (see example below with intendedurl).

You may need to URL Encode everything after the URL_success= parameter.

Please note that none of the URLs below will truly work as they are made up URLs for teaching purposes.

For example, if you have a "simple" URL_success like this:

http://www.naxyz.org/memberpage.cfm?usertoken={token}

Then your complete URL will be:

http://members.naxyz.org/eweb/DynamicPage.aspx?Site=eWeb&WebCode=LoginRequired&URL_success=http://www.naxyz.org/memberpage.cfm?usertoken={token}

Even without URL Encoding, a success will return the user to:

http://www.naxyz.org/memberpage.cfm?usertoken=5d6ef416-2bd5-4a65-b609-8afae7b83201&Site=eWeb

If you run into issues with this, you might try URL encoding the URL_success anyway.

Next, let's examine a more "complicated" URL_success that has its own querystring values needed by your application. For example you might need a reference to the page the user was trying to access, illustrated by the intendedurl querystring parameter. In this example, you might want all "return trips" to go to memberpage.cfm for authentication purposes, and then you will have memberpage.cfm send the user to the URL they were originally trying to access.

http://www.naxyz.org/memberpage.cfm?usertoken={token}&intendedurl=http://www.naxyz.org/committee.cfm?id=332

If you use this URL redirect:

http://members.naxyz.org/eweb/DynamicPage.aspx?Site=eWeb&WebCode=LoginRequired&URL_success=http://www.naxyz.org/memberpage.cfm?usertoken={token}&intendedurl=http://www.naxyz.org/committee.cfm?id=332

Then you fill find that when the user comes back, the intendedurl querystring parameter may get dropped.

Therefore, first you must URL Encode the entire value of the URL_success querystring parameter, which in this case is:

http://www.naxyz.org/memberpage.cfm?usertoken={token}&intendedurl=http://www.naxyz.org/committee.cfm?id=332

If you URL Encode this, you get:

http%3a%2f%2fwww.naxyz.org%2fmemberpage.cfm%3fusertoken%3d%7btoken%7d%26intendedurl%3dhttp%3a%2f%2fwww.naxyz.org%2fcommittee.cfm%3fid%3d332

Your complete URL will be:

http://members.naxyz.org/eweb/DynamicPage.aspx?Site=eWeb&WebCode=LoginRequired&URL_success=http%3a%2f%2fwww.naxyz.org%2fmemberpage.cfm%3fusertoken%3d%7btoken%7d%26intendedurl%3dhttp%3a%2f%2fwww.naxyz.org%2fcommittee.cfm%3fid%3d332

A successful login will return the user to:

http://www.naxyz.org/memberpage.cfm?usertoken=f8251df8-1e53-43bf-9273-db4eff11dc4e&intendedurl=http://www.naxyz.org/committee.cfm?id=332&Site=eWeb

If you run into issues with URL Encoding, we recommend starting by not URL Encoding anything, and then URL Encode one thing at a time until you have a success.

Using the Token

The URL of this "return page" will be indicated in a special URL_success querystring parameter, as described above. If you also include a special parsed value in your querysting called {token}, as shown above, then NetForum will automatically generate an authorization token (similar to the way the WebLogin web method generates a token) and return that value in the querystring. Your program can then request that value and pass the value to the WebValidate or WEBWebUserValidateToken web method to get the Customer Key of the user. Once you have the Customer Key, you can then get other information about the user with other web methods.

The token will, by default, have an expiration date advanced the number of minutes of the session timeout (which by default is 20 minutes). If you want to immediately expire the token, then call the WebLogout web method after calling WebLogin.

The benefit of this approach is that no private or sensitive information is ever revealed; the Token value itself is a randomly-generated guid value and it can be expired. Additionally, this solution works with sites on different domains that cannot share a domain cookie.

Note that we have named the actual querystring parameter userToken to avoid confusion. Technically you could call this querystring parameter anything you want. The important consideration is that you must use the special code Token in order to trigger netFORUM to generate a new token value.

Page Flow Diagram

Flow chart showing single sign-on solution

The page flow diagram illustrates the steps described above.

The blue-shaded boxes depict a third-party application that is not netFORUM. The yellow boxes depict NetForum xWeb, and the light-green boxes depict NetForum eWeb. Of course, the way the third-party application works could vary; the flow chart shows a representative example.

In the blue decision box "Is User Logged In?", if "no", then we assume the third-party application will Response.Redirect the user to eWeb, using a URL pattern as described in the section above. Next, the user will arrive in eWeb. If the user happens to be logged in already, then netFORUM will generate a Token, then return the user to the URL specified in the URL_success querystring parameter, and place the value of the Token in place of the {Token} portion of the URL. This will happen without the user even realizing they left the original site.

If the user is not logged in to netFORUM, then the user will go to the eWeb Login page to login. If they can log in successfully, then eWeb will automatically redirect the user to the page specified in URL_success. Note that if the user clicks off the login page, or clicks on New Visitor Registration or forgot password, then eWeb will have "lost" where the user was trying to go originally, and the user will just stay on the eWeb page. eWeb will not send them back to URL_success. The only way the user will get back to the original page is if they click back to it somehow.

On the page on which the user lands (specified in URL_success) in the third-party application, it is up to the third-party application to Request the value of the Token from the querystring parameter (shown as userToken in the example above. The third-party application can call WebValidate or WEBWebUserValidateToken with the Token and then call any other web method(s) needed to get more information about the user, and "log in" the user to the third-party application and do anything else needed by the application.

The light-blue decision box on the bottom right ("Is User Authorized?") is intended to depict what might happen if a user requests to view privileged content, such as a page that only Members can view. It is up to the third-party application to govern this access based on applicable netFORUM data about that user.

Managing Logouts

The example above details a single sign-on. But what about signing off?

If a user logs out of netFORUM (or closes browsers or resets their cache), there is no automatic provision to log that user out of any sites that have employed this single sign-on feature. Understandably, if the user logs out of netFORUM eWeb, you would want to ensure that they are logged out of your third-party application as well. One way to do this is to post to the LoginRequired URL above every time you need to validate the user's identity. This is the only safe way to ensure the user is still logged into eWeb.

If you have a "log out" feature on your third-party site, and you want to have that feature also log the user out of eWeb, then you will need to implement a log out feature as described below in #Appendix B - Single Sign Out.

From eweb site, if you want eWeb to redirect user, after logout, to a certain page of external site (third-party site), you could change the "Logout" hyperlink in netFORUM CMS to include "RedirectURL" parameter of the target page. This is especially useful for you to implement single logout. You can find more detail below in Appendix B - Single Sign Out.

Single Sign-On With eWeb - External Login

If you are using a login form on a third party site, but also want to log users into eWeb, you will want to use a feature made available in 2008.01.05 which makes it possible to include a token in the URL of the eWeb page, identifying the user and logging them in.

How to get the Token

The token is generated by calling the baseline xWeb method xWeb:WebLogin. This method accepts parameters for username and password and, if validated, returns a token for the user which will identify them for a short period of time. This token will only be valid for a few minutes, so it should only be created near to the time when it will be passed to eWeb for login (the time the token will last is managed in the xWeb web.config See XWeb:Configuration_Settings#Timeout). By making this token only last for a short period of time and providing a new token every time a user logs in, the login is more secure.

What to do with the Token

Once the token is generated, it can be included in the query string of an eWeb URL like:

http://members.naxyz.org/eweb/StartPage.aspx?Site=NAXYZ&NAXYZToken=E21F4E7E-F488-4561-BBC2-A81BF7A3231A&URL_success=http%3a%2f%2fwww.naxyz.org%2fmemberpage.cfm%26intendedurl%3dhttp%3a%2f%2fwww.naxyz.org%2fcommittee.cfm%3fid%3d332

Note that the name of the parameter for the token includes the site id - NAXYZ. This will vary for each eWeb site as necessary. Also, the URL_success is passed, similar to the other Single Sign-On option. If this value is present, once the user is logged in, they will be returned to this location. A second parameter can also be included - URL_failed - which, if present and the login is unsuccessful, will take the user to that location. This feature should function on any eWeb page.

Where Should Users Login?

Between the two sites, only one login page should be used. This will ensure that all login actions take the same steps and correctly initiate whichever sites are necessary. Beginning with 2008.01.07 and netFORUM 3.0.3, a new system option is available named eWebExternalLoginURL. If this option is populated, netFORUM’s eWeb login page will redirect the user to the value of this option instead of prompting for login. This page can still be used for auto-logins as it will not redirect if a URL_Success is present, an auto-login token is passed to the login page, or if the user is logged in already. When redirecting to the external login, the user’s original destination will be passed as a query string parameter named IntendedURL

Single Sign-On Considerations

Forgot Password

If the eWeb login page is being used as the login point, the standard Forgot Password functionality will be available for the user. Beginning with 2008.01.07 and netFORUM 3.0.3, the system will maintain the user's intended destination and take them there after they complete this process. If eWeb is not the login point, Forgot Password will need to be configured on the site which is managing the login.

Force Password Change

If the eWeb login page is being used as the login point, beginning with 2008.01.07 and netFORUM 3.0.3, even if a URL_Success value has been passed, the standard Force Password Change functionality will be enforced when a user logs in. Once the user has changed their password, they will be returned to the URL_Success. If eWeb is not the login point, forcing a user to change their password should be implemented by the site managing the login.

New Users

If the eWeb login page is being used as the login point, the standard New Visitor Registration functionality will be available for the user. Beginning with 2008.01.07 and netFORUM 3.0.3, the system will maintain the user's intended destination and take them there after they complete this process. If eWeb is not the login point, New Visitor Registration will need to be configured on the site which is managing the login.

Determining if a User is Logged in

Beginning with 2008.01.07 and netFORUM 3.0.3, the eWeb login page will accept a new query string parameter URL_NotLoggedIn. If this parameter is passed and no user is currently logged into eWeb, instead of being prompted to login, they will be redirected to this URL. If a user is logged in and a URL_Success parameter is passed, they will be redirected to that location. Otherwise, they will be shown their current login information.

Keeping Sessions Alive on Multiple Sites

If the user on the Members Only site subsequently attempts to access a netFORUM page that requires a login, then the user will have already been logged into netFORUM behind the scenes. If that user should then move back to the Members Only site, then presumably the user’s cookie or session will still be active on the Members Only site, making the need for an additional login unnecessary.

In order to keep both sessions active, every requested Members Only web page should include a way of touching eWeb to keep the session alive. Similarly, netFORUM’s eWeb site can be configured (using system option KeepSessionAliveUrl) to also touch a page on the Member’s Only site for each requested eWeb page. This will ensure that both sessions remain alive and synched. This system option can be configured with multiple URLS if needed by separating them with a semi-colon (';').

There are several options for doing the touch to eWeb. Our most commonly used approach is to reference an invisible image which is located on the eWeb site. This invisible image is located here:

http://members.naxyz.org/eweb/images/img_transparent.gif

where members.naxyz.org will be the actual URL of the association’s eWeb site.

However, we have noticed that this may not always work and have additional options. One additional option is to use the same methodology as eWeb and place a javascript referencing the eWeb site:

<script language="javascript">
<!--
        blackHole0 = new Image();
        blackHole0.src = 'http://members.naxyz.org/eweb';
//-->
</SCRIPT>

The code above is generated by eWeb for each link in the KeepSessionAliveUrl System Option.

Finally, if you prefer to not use a javascript for this purpose, you can place an iFrame on the Member's Only site which references the eWeb location and this will cause the eWeb session to be refreshed on each page load.

Passing Credentials to an External Site

In some cases, a link to an external site which includes the user's credentials may be needed, but only to log the user in initially. In this case, the link should include a token, and the page which generates the link will also need to generate the token. Here's some sample code for creating this link using an eWeb List Content Detail:

{BeginListSQL}
declare @token uniqueidentifier
set @token = newid()
 
insert into ws_security (xws_current_token, xws_expiration, xws_expiration_policy, xws_cst_key, xws_usr_code)
values (@token, dateadd(minute, 20, getdate()), 'Sliding', {CustomerKey}, <user code of a netForum user account
to assign as record creator>)
 
select @token as [token]
{EndListSQL}
{BeginListDetail}
<table>
<tr><td>http://www.externalsite.com/?UserToken={token}</td></tr>
</table>
{EndListDetail}

The code should be placed in the main content area of the content detail and should be a List content type. Otherwise, it can be arranged similar to any other eWeb content. This sample will create a new token and insert a record into the table which stores the tokens - ws_security - relating the customer to the token. This token is then included in the link which is passed to the external site. This site will then be able to use the token and call XWeb:WebValidate to identify the user who is currently logged in. After identifying the user, the site can also call XWeb:WebLogout to invalidate the token. The token will only be good for a short period of time, so the user can't bookmark the link or accidentally pass the link to a friend which would include their login information.

Troubleshooting

Case Sensitivity

NetForumURL querystring values can be case sensitive. Therefore, you should NOT upper- or lower-case querystring values in NetForum URLs or you may encounter unpredictable results or behavior.

Appendix A - User Information XML Web Service

As an optional customization, Abila can create a web service that can return more information about a customer if the baseline web methods are not sufficient. This is not a baseline feature as it needs to be customized for each client’s specific needs. Contact Avectra for more information.

Appendix B - Single Sign Out

In order to sign out the member from eWeb when the member logs out of the client site (external site), Logout.aspx can be called with a RedirectURL querystring parameter.

For instance, if the individual logs in to external site through Single Sign On, he is also logged in to eWeb. External site may have a log out process and obviously this will be out of eWeb’s control as it is an external site. So, if individual logs out on the external site, he will still be logged in in eWeb.

To log the user out of netFORUM, the external site’s Logout process should call the following (RedirectURL needs to be changed of course) URL:

.../eWeb/Logout.aspx?RedirectURL=http://www.AssociationExternalSite.org

By doing this, they will also be logged out from eWeb and be redirected to the site specified as RedirectURL.

If you want to ensure that logging out of eWeb will also log the user out of a third-party site, then you could change the hyperlink in netFORUM CMS to have the RedirectURL of a special "logout" page on the third-party site.

Appendix C - Cross Domain SSO

The Drupal project allows limited cross domain single sign on and the theory can be expanded to other platforms. It requires programs on each domain to work in conjunction to set cookies for the primary domain by using carefully crafted CSS references. Given two domains such as www.naxyz.org and www.naxyzaffiliate.org, when logging someone in to www.naxyzaffiliate.org including a specially crafted css reference tag such as the below example can allow a different to set a domain cookie without having the user be redirected to the site:

<style type="text/css">
http://www.naxyz.org/SpecialLogin.aspx?cst_id=123456&code=d58e3582afa99040e27b92b13c8f2280
</style>

Normally, style tags in HTML documents are used to set the look and feel of a website, but it also gives an unobtrusive way for the www.naxyz.org site to set a cookie on the users computer. The actual response or contents of the css file can be empty.

When contemplating this approach it is important to ensure that individuals cannot craft their own links to log in as a different user, which is why close coordination between the two sites is important. The Drupal project passes the customer id, a special hashed version of the customer id, and a special hashed version of the customer's password. What makes the hashed versions special is including a secret word shared by both sites with the customer id or password before hashing, which helps ensure that individuals cannot create replace their customer ID with another's, or create their own hash. The receiving site then uses the customer id and secret word to make its own hashes in the same fashion as the sending site to verify that both the customer id and password are valid. For more information about hashing and the use of salt to help security visit see [MD5 on Wikipedia].

Appendix D: Archived Solutions

Over time, Abila has developed better and more secure single sign-on solutions as NetForum evolved. The following legacy solutions are no longer recommended but are left for reference to older implementations that we developed before our newer and more secure solutions, as described above. If you are about to launch a single sign-on solution, refer to the examples above and we recommend that you ignore the options below.

Solution Option 1 - Username and Password Prompt using non-eWeb page

Not recommended.

Solution Option 2 - Username and Password prompt using eWeb page

Not recommended.

Solution Option 3 - Domain Cookie Authentication

This is not a baseline feature in NetForum. This solution may be implemented as a custom modification for a single sign-on solution.

A domain cookie can be used for centralized authentication if two (or more) sites can be registered under the same domain.

For example, if the members only site is called:

http://www.naxyz.org

and the netFORUM eWeb site can be registered as:

http://members.naxyz.org/

then a cookie can be written by either application that can be read by the other, as long as the domain property of the cookie is set.

With this solution, netFORUM can be the authentication tool and it will write a domain cookie after a successful login. If the user should jump over to www.naxyz.org, then this application must read the contents of the domain cookie to determine if the user is a member.

If the user starts out on a members only page in the www.naxyz.org site, then the user can be redirected by this site to netFORUM’s eWeb for authentication, with a RedirectURL parameter specified to which \netFORUM will return the user after a successful login. For example:

http://members.naxyz.org/eweb/DynamicPage.aspx?WebCode=LoginRequired&RedirectURL=http://www.naxyz.org/membersonly/page.cfm?id=3224

If the user can login successfully, then netFORUM will write a domain cookie and then redirect the user to:

http://www.naxyz.org/membersonly/page.cfm?id=3224

This page could then check the contents of the cookie and authenticate the user as needed.

Under this solution, the integrating site (www.naxyz.org) must be modified to read the contents of the cookie and manage the redirection of the user.

The domain cookie may contain values for member id, membership status, or any other values as needed. Avectra would need to work with the client to handle any other details.

Solution Option 4 - Domain Cookie Login

This option has been deprecated. Please contact Abila for alternate approaches if you were referred to this "Option 4".

Solution Option 5 - Querystring Authorization Token

This option is Abila ' s preferred solution and is described in #Single Sign-On With eWeb above. Although we no longer refer to this as "Option 5", we are leaving the reference on this page for people who are searching for it or have a dated hyperlink to this option.