Configuring single sign-on

Single sign-on is a feature which enables users to authenticate just once and then access multiple websites without the need to enter logon credentials again for each site. There are three ways how you can achieve this:

• Single sign-on on the same main domain
• Single sign-on across different domains
• Single sign-on API

The sections below describe necessary configuration for each approach.

Single sign-on on the same main domain

This approach lets you configure single sign-on for multiple sites running on the same main domain (e.g. site1.example.com, site2.example.com, etc.) in the IIS. The sites do not need to be running on Kentico.

Single sign-on on the same main domain is supported in the following scenarios:

Forms Authentication

If you are using Forms authentication and you need to share user identity across applications that run on the same main domain while all of them use standard ASP.NET 2.0 Forms authentication, you need to ensure that:

1. All applications use the same user database or at least the same user names. You may need to integrate the authentication using a custom security handler.

2. The web.config file of all applications uses the same authentication cookie name and the path is set to “/”:

   Copy

   
   
   
    <authentication mode="Forms">
      <forms name=".ASPXFORMSAUTH" path="/" ... />
    </authentication> 
   
   
    

3. The web.config file of all applications uses the same machine key.

   • The machine key is not present in the web.config by default.

   • You can use a PowerShell script to generate the machineKey element according to the instructions in this article from Microsoft. Insert the generated machineKey element into the <system.web> section in the web.config file:

     Copy

     
     
     
       <system.web>
        ...
         <machineKey decryption="..." decryptionKey="..." validation="..." validationKey="..."  />
        ...
       </system.web>
     
     
       

4. If your applications run on different sub-domains, such as www.example.com and forums.example.com, you need to set the domain attribute of the authentication cookie to the main domain so that it’s shared across domains:

   Copy

   
   
   
    <forms name=".ASPXFORMSAUTH" path="/" domain=".mywebsite.com" ... />
   
   
    

Windows Authentication

If you are using Windows authentication, the user identity is shared within the Windows domain. No additional configuration is required.

Single sign-on across different domains

This approach requires all websites to be running in a single instance of Kentico, while they can use completely different domains.

Single sign-on across completely different domains in the same instance of Kentico can be enabled by selecting the Automatically sign-in user when site changes check box in Settings -> Security & Membership.

With this option enabled, no further configuration is necessary - users only need to enter their logon credentials once. After that, they can switch between different sites running on Kentico using the Site drop-down list, without the need to enter their logon credentials for each domain.

Single sign-on API

The single sign-on functionality is also achievable on your custom pages using the Kentico API. The following code example shows how to authenticate a user with a particular username in your code:

string userName = "testuser";

// Authenticates the user with the specified user name
CMS.Membership.AuthenticationHelper.AuthenticateUser(userName, true, false);

The second code example shows how to generate a URL with a user authentication token. The system automatically authenticates users when they access this URL.

using CMS.Membership;
using CMS.Helpers;

...

string userName = "testuser";        

// Gets the user with the specified user name
UserInfo userInfo = UserInfoProvider.GetUserInfo(userName);

// Gets the authentication URL for a specified user and target URL
string url = AuthenticationHelper.GetUserAuthenticationUrl(userInfo, "/default.aspx");

// Redirects the user to the target URL for authentication
URLHelper.Redirect(url);