Optionally provide private feedback to help us improve this article...

Thank you for your feedback!


InstantForum Single Sign On Considerations

This article lists key concepts to consider when attempting to generate or share the forms authentication cookie required by InstantForum with your own web site or web application. This is typically required if you wish to provide a single sign on experience between your existing ASP.NET web site and InstantForum.

Multiple Web.Config Files At Different Directory Levels

If you have InstantForum installed in a child folder of your IIS web site within a web application or virtual directory you should ensure you only have one "<authnetication>" element within your root web.config file. The .NET framework does not allow you to have multiple <authentication> elements at different levels within the application hierarchy.

Sharing the ASP.NET Forms Authentication Cookie

If InstantForum is installed in a virtual directory or web application under your main web site or a completely separate web site within IIS (for example a sub-domain) you will need to ensure the ASP.NET forms authentication ticket is encrypted & decrypted using consistent private keys across each application that needs to access the forms authentication cookie.

To ensure this you will need to explicitly provide identical <machineKey> elements within each web.config file for each application you wish to share the forms authentication cookie with.

For example if your using our API from your main web site and calling our User.Authenticate() method to create the required forms authentication cookie and InstantForum is installed as a child web application under your existing web site you will need to ensure the same <machineKey> elements appear both in your main web sites web.config file and within the InstantForum web.config file like so...

<system.web> 
<!-- Encryption keys for forms authentication cookie. This ensures tickets remain consistent
between multiple servers or multiple web applications. -->
<machineKey validationKey="BD52058A3DEA473EA99F29418689528A494DF2B00054BB7C"
decryptionKey="684FC9301F404DE1B9565E7D952005579E823307BED44885"/>
</system.web>

Each application & web site within IIS has it's own unique set of private machine keys which are generated randomly unless you explicitly set these within your web.config file. If these are not consistent a forms authentication cookie generated by one application won't be accessible to another as they use different keys for the encryption & description of the forms authentication cookie.

If wish to generate your own unique machineKey element for use within your web applications please refer to the links below...

Single Sign-On Across Sub-Domains / Multiple IIS Web Sites

If you generate the forms authentication on your main web site say https://www.abc.com/ and you wish to share the forms authentication tickets generated by your site with InstantForum installed at https://forum.abc.com/ you will need to ensure you provide a consistent top level domain within the domain attribute for the <forms> element within each web.config file. This is shown below...

authentication mode="Forms">
<forms name="InstantASP" domain="abc.com" loginUrl="~/Account/Login.aspx" protection="All" slidingExpiration="true"/>
</authentication>

This will ensure the forms authentication cookie can be accessed by sub-domains of abc.com for example community.abc.com or forums.abc.com.

Creating the Forms Authentication Cookie From Your Application

If you don't already create a forms authentication cookie during your login process you can use the User.Authenticate() method provided by the InstantASP API to create the required forms authentication cookie. For example...

// YourMethodToCheckUsernamePassword would check the username and password against your core user tables
bool myAuthCheck = YourMethodToCheckUsernamePassword(txtEmail.Text, txtPassword.Text);
InstantASP.InstantForum.Components.User user = null;
if (myAuthCheck)
{

	// check if account already exists
	user = InstantASP.InstantForum.Business.User.SelectUser(txtEmail.Text);
	// we found the user within InstantASP_Users
	if (user.UserID > 0)
	{
		// create forms authentication cookie if you don't already create one
		User.Authenticate(true); // true = persist cookie
		
	}
	else // new user found - add to forum tables & authenticate
	{

		// build user
		user = new InstantASP.InstantForum.Components.User();
		user.EmailAddress = txtEmaill.Text;
		user.Password = txtPasswordl.Text;
		user.Username = txtEmaill.Text;
		user.PrimaryRoleID = InstantASP.Common.Business.Roles.SelectRole(InstantASP.Common.Enumerations.EnumRequiredRoles.Member).RoleID;

		// add user & authenticate
		int intIdentity = InstantASP.InstantForum.Business.User.InsertUpdateUser(user);

		if (intIdentity > 0)
		{

			user = InstantASP.InstantForum.Business.User.SelectUser(intIdentity);
			user.Authenticate(true);

		}

	}

	// redirect to your account pages or main web site
	Response.Redirect("https://yoursite.com/Default.aspx");

}

For further information on working with the user API and the User.Authenticate() method please see Creating Users Programmatically.

In Summary

To share the forms authentication cookie required by InstantForum for user authentication with two or more web applications must consider the following...

  1. Ensure all <authentication> elements are consistent in each web.config file for each application that requires access to the forms authentication cookie. Ensure a consistent name and domain attribute.
  2. Ensure consistent <machineKey> elements in each web.config file that requires access to the forms authentication ticket.
  3. Ensure usernames and email addresses within the InstantASP_Users table match the usernames and email addresses of users in your main web site users database table.
  4. A forms authentication cookie must be created by your login page which contains a HMAC of the users username or email address.

That's It!

‚ÄčIf we can assist with any questions regarding single sign on of course please don't hesitate to open a support ticket or contact us for assistance.