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

Thank you for your feedback!


InstantKB Forms Authentication Single Sign On

New

InstantKB uses standard ASP.NET forms authentication for user authentication and persistence.This makes it very easy to achieve a single sign on (SSO) experience with InstantKB and existing ASP.NET web sites that also uses forms authentication or the ASP.NET membership provider.

InstantKB installed in a child application

This article assumes you have InstantKB installed in a child folder under your main web site. This child folder is marked as a web application within IIS. If you have InstantKB installed in a child folder under your main web site you should ensure you only have one "<authentication>" 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.

InstantKB installed in a separate web site

If you are running InstantKB as a separate web site within IIS (for example you are using a sub-domain) you will need to ensure both web.config files have identical <authentication> & <machineKey> elements. In addition if you are using a sub domain for your InstantKB installation you will also need to specify a domain attribute pointing to your top level domain within the <forms> element of both web.config files so the cookie can be accessed by your sub-domain.

For example...

<authentication mode="Forms">
  <forms name="InstantASP" domain="instantasp.co.uk" cookieless="UseCookies" loginUrl="Logon.aspx" protection="All" slidingExpiration="true" path="/"/>
</authentication>

Key Requirements for Forms Authentication SSO

To achieve a single sign on experience with your existing web site and InstantKB there are two essential requirements.

  1. Your parent web site must issue a valid ASP.NET forms authentication ticket upon user authentication. This ticket must be configured via the web.config files to be shared correctly with your main web site and your InstantKB installation. This includes ensuring a consistent <authentication> and <machineKey> element.
  2. A user account must exist for each authenticated user you wish to persist within the InstantASP_Users database table used by InstantKB. You will need to ensure at minimum the users email address is added to the InstantASP_Users table during your existing registration process. You can do this either via our .NET API or through TSQL.

Further sections discuss these two key requirements in more detail.

Configuring the Forms Authentication Cookie

When a user authenticates on your main web site a ASP.NET forms authentication ticket will be created which is stored by default in a cookie on the clients computer. This cookie must be shared with InstantKB for authentication to persist.

The cookie contains the forms authentication ticket which is represented by a HMAC token. The HMAC token is created via a cryptographic hash function in combination with a secret cryptographic key.

As encryption is involved when creating and reading the forms authentication ticket you will need to ensure both your main web site and InstantKB are using the same cryptographic key for the forms authentication ticket.

You can set this key through the <machineKey> element within each web.config file for each web application you wishto persist authentication. The <machineKey> settings within your web.cofig is the key to sharing your forms authentication cookie successfully across all web sites. Each web.config will need an identical <machineKey> element.

For example...

<machineKey validationKey="BD52058A3DEA473EA99F29418689528A494DF2B00054BB7C"
decryptionKey="684FC9301F404DE1B9565E7D952005579E823307BED44885" /> 

Note: Your main web site and the InstantKB installation must be using the same version of ASP.NET for this to work correctly. If your using different .NET versions for your main web site and InstantKB installations you may need to specify the encryption or hashing method to use within the <machineKey/> element. Newer versions of .NET use a more secure default SHA hashing algorithm for the forms authentication cookie.

For security purposes we would suggest creating your own private encryption keys. You can use the links below to generate valid keys for the machineKey element...

Creating InstantKB Users

If you handle authentication on your main web site against your core user database table you don't need to store a password within the InstantASP_Users table.

Adding InstantKB Users via the .NET API

Here  we use the InstantKB API during registration on the parent web site to add the user information to the InstantASP_Users database table used by InstantKB. To learn more about how to use our .NET API from your existing ASP.NET web site please see "Using the InstantKB .NET API".

var userId = Business.UserRepository.InsertUpdateUser(new Components.User()
{
EmailAddress = "email@address.com",
Password = "password",
Username = "UserName",
PrimaryRoleID = 3
});

// was the insert successful?
if (userId > 0)
{
// get instance of new user
var user = new Components.User(userId);
// optionally set client side authentication cookie
var identityProvider = Providers.UserIdentity.UserIdentityProvider.Instance();
identityProvider.SignIn(user);
}
else
{
if (userId == -1)

// username already exists

} else if (userId == -2)
{
// email already exists
}
}

 This is the only code you'll need to add to your existing registration process. This references our .NET API so you will need to add our assemblies to your project and add a single connection string to your web.config file so our assemblies know which database to work with.

<add key="InstantASP_ConnectionString" value="Server=localhost;trusted_connection=true;database=InstantKB_2011;" />

Adding InstantKB Users through TSQL

If you already call a stored procedure during your registration process to add user information to your core user tables you may just wish to extend your existing stored procedure to also add the user information to the InstantKB tables. The below TSQL shows how to add a new user to InstantKB...

/* NOTES: 
 You would replace  [InstantKB] with the name of your InstantKB.NET Database
*/

DECLARE @strUsername nvarchar(255)
SET @strUsername = 'A User'

DECLARE @strPassword nvarchar(255)
SET @strPassword = 'qwerty123456$#'

DECLARE @strEmailAddress nvarchar(255)
SET @strEmailAddress = 'auser@acompany.com'

-- check to see if user email already exists in InstantKB.NET
IF EXISTS(SELECT UserID FROM [InstantKB].[dbo].InstantASP_Users WHERE EmailAddress = @strEmailAddress)
BEGIN

UPDATE  [InstantKB].[dbo].InstantASP_Users
SET Username = @strUsername,
Password = @strPassword
WHERE EmailAddress = @strEmailAddress 

END
ELSE 
BEGIN

-- get default member role ID
DECLARE @intRoleID INT
SET @intRoleID = (SELECT RoleID FROM [InstantKB].[dbo].InstantASP_Roles WHERE MemberRole = 1)

-- user does not exists, create them
INSERT INTO [InstantKB].[dbo].InstantASP_Users
(
Username, 
EmailAddress,
[Password],
PrimaryRoleID 
)
VALUES 
(
@strUsername,
@strEmailAddress,
@strPassword,
@intRoleID
)

-- get new user ID
DECLARE @intUserID INT
SET @intUserID = @@IDENTITY 

-- add role relationships
INSERT INTO [InstantKB].[dbo].InstantASP_UsersRoles 
(
UserID,
RoleID
)
VALUES
(
@intUserID,
@intRoleID
)

-- add InstantKB.NET user data
INSERT INTO [InstantKB].[dbo].InstantKB_Users 
(
UserID, 
PermissionID
)
VALUES 
(
@intUserID,
0
)


END 

That's It!

Once you have the user information being added to the InstantASP_Users table and you are persisting the forms authentication cookie correctly you should notice once you register on your main web site and login you will also be automatically authenticated when you visit InstantKB.As always if we can assist with any questions please don't hesitate to contact us or open a support ticket.