---
title: Configuring single sign-on
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
Single sign-on is a session and user authentication service that permits users to use one set of sign-in credentials (e.g., a name and a password) to access multiple websites. The service authenticates the user across a set of websites and eliminates further sign-in prompts when accessing different sites during an existing session.
Single sign-on can be implemented:
- [On a single shared domain](#setting-up-single-sign-on-on-a-shared-main-domain)
- [Across different domains](#setting-up-single-sign-on-across-different-domains)
- [Via the Xperience API](#implementing-single-sign-on-via-the-xperience-api)
The single sign-on functionality described on this page is supported only for the **administration application**. For the live site, you need to implement single sign-on based on ASP.NET Identity.
> **Note:** **Note**
>
> When implementing single sign-on for websites spread across multiple Xperience instances, we strongly recommend that all instances target the same version of the Microsoft .NET Framework.
## Setting up single sign-on on a shared main domain
This approach allows you to configure single sign-on for multiple sites running on subdomains of a shared main domain (for example _site1.example.com_, _site2.example.com_) on the Internet Information Services (IIS) server. Users authenticated this way have access to both the secured content on the live site and the administration interface of all Xperience instances sharing the main domain. The sites or applications **do not need** to be running on Xperience.
Single sign-on on a shared main domain is supported in the following scenarios:
### Forms Authentication
To set up single sign-on with Forms authentication across applications running on a shared main domain and using the standard ASP.NET 2.0 Forms authentication, ensure that:
1. All applications share the user database or at least use the same user names. You may need to integrate the authentication using a [custom security handler](https://docs.kentico.com/13/custom-development/handling-global-events/handling-custom-administration-authentication.md).
2. The _web.config_ file of all applications uses the same authentication cookie name and the path is set to "/":
```html
```
3. The _web.config_ file of all applications uses the same machine key.
- The **machineKey** element is not present in the web.config by default.
- You can use a PowerShell script to generate the _machineKey_ element by following [this article from Microsoft](https://support.microsoft.com/en-us/kb/2915218#bookmark-appendixa). Insert the generated _machineKey_ into the __ section in the application's **web.config** file:
```html
...
...
```
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 forms-authentication cookie to the main shared domain:
```html
```
### Windows Authentication
If you are using the [Windows AD authentication](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/configuring-windows-ad-authentication.md), the user identity is shared within the Windows domain. No additional configuration is required.
## Setting up single sign-on across different domains
Single sign-on across different domains can be enabled only for site switching via the administration interface. This approach requires all sites to be running on a **single** Xperience instance. The sites can still use completely different domains.
To enable single sign-on across different domains:
1. Navigate to **Settings -> Security & Membership**.
2. Select the **Automatically sign-in user when site changes** checkbox under _Administration._
3. Click **Save**.
No further configuration is necessary. Users can now freely switch sites via the administration interface without the need to re-enter their credentials every time the site changes.
## Implementing single sign-on via the Xperience API
You can also implement single sign-on functionality on custom pages using the Xperience API.
The following code example shows how to authenticate a user with a particular username in your code:
```csharp
string userName = "testuser";
// Authenticates the user with the specified user name
CMS.Membership.AuthenticationHelper.AuthenticateUser(userName, true, false);
```
User authentication via the _AuthenticateUser()_ method closely mimics standard ASP.NET Forms authentication. The authentication cookie created when a user is authenticated this way will behave according to its settings as described in the [Forms authentication](#forms-authentication) section above.
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.
```csharp
using CMS.Membership;
using CMS.Helpers;
...
string userName = "testuser";
// Gets the user with the specified user name
UserInfo userInfo = UserInfo.Provider.Get(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);
```