Product documentation
Citrix Virtual Apps and Desktops
Current Release Service 2507 LTSR 2503 2411 2407 2402 LTSR 2311 2203 LTSR
View PDF

Single sign-on support

February 9, 2026
Contributed by: 
C

Introduction

Browser Content Redirection now offers streamlined user experience with single sign-on support, enabling VDA-side authentication and cookie sharing.

This enhancement eliminates redundant logins, boosting productivity by maintaining authentication and cookie persistence across BCR sessions, even after the BCR window is closed.

This seamless experience further enhances security by ensuring authentication originates from the VDA, not the client.

Without Single sign-on

  • Opening an authenticated page within BCR required users to re-enter their credentials each time, breaking SSO persistence.
  • SSO was only maintained while the BCR window remained open; closing and reopening the window forced users to repeat the login process.
  • The authentication flow happened from the client, forcing administrators to provide network access to secure authentication sites from the client device.

With Single sign-on

  • Users are no longer prompted for credentials (when already authenticated on the VDA), as SSO is seamlessly preserved from the VDA browser.
  • Authentication happens from the VDA, which improves security posture by limiting client-side network requirements and exposure, providing a significantly improved and uninterrupted experience.

Minimum requirements

  • Citrix Virtual Apps and Desktops 2511
  • Citrix Workspace App for Windows 2511
  • Citrix Workspace App for Linux 2511 (Preview)
  • Browser Redirection Extension (Chrome or Edge) 25.11 or later

Supported authentication sequences

There are two types of authentication sequences that are currently supported with BCR Single sign-on.

Redirection based authentication

In this standard method, the application uses an HTTP redirect to force the user to a dedicated page for authentication.

For example, if a user attempts to reach https://my.intranet.app without the necessary session cookies, the web application will respond with an HTTP 302 Redirect to the authentication endpoint, like https://my.intranet.app/auth .

Once the user successfully authenticates on that page, the browser is redirected back to the original application URL, now including the required authentication cookies.

In-page forms-based authentication [Preview]

This method keeps the user on the intended application URL while dynamically presenting the login interface.

For example, if a user navigates to a protected page, such as https://my.intranet.app , the page loads the authentication form directly without triggering a redirection, because the necessary cookies are missing. This process may involve several internal exchanges between the page interface and the Identity Provider (IDP). These exchanges continue until a final, valid cookie is provided and utilized, granting the user access to the content on the original page.

Note:

In case your scenario is not covered by the mechanisms specified above and it’s not possible to set up your webapp to use above mechanisms, reach out to Citrix Product team.

Configuration

Step 0: Introduction

There are two methods to configure Single sign-on with BCR. Choosing the method of configuration depends on the authentication mechanism for the desired BCR websites and the flexibility you need to configure multiple web applications for single sign on support.

Method 1: This method uses the existing BCR policies in Web Studio and uses them to achieve Single sign on support.

Before introduction of Single sign-on support, Browser content redirection authentication sites policy was used to specify the URLs used for authentication (or intermediary pages) to be redirected to the client to ensure there is no break in the flow.

With the introduction of Single sign-on support, BCR will leverage the authentication cookies on the VDA side browser and hence, the URLs in authentication sites policy now need to be configured in the Browser content redirection block list policy instead. This ensures that the authentication happens through the VDA.

Method 2: This method operates on a similar logic as Method 1, but the URLs are configured via JSON (bcrconfig.json) instead and the hosted JSON URL is called in BCR ACL policy. The JSON configuration offers additional flexibility.

  1. Enterprises use several web applications in their environment, and each application may use a different authentication mechanism based on its implementation. The new JSON method allows configuration to be more intuitive, robust and scalable.
  2. When dealing with In-page forms-based authentication, the Method 1 does not offer a way to set specific authentication cookie as there are no existing policies to support such configuration. Hence, if your website requires In-page forms-based authentication, JSON is the only way to do it.

Looking towards the future, JSON offers a scalable way to introduce more robust features, and Citrix recommends trying the JSON based configuration.

Step 1: Determining authentication mechanism

To determine which Method to use for your configuration, first step is to determine what kind of authentication mechanism your application is using. To accurately determine the web application’s authentication method, the best approach is to contact the web application administrator.

If that is not an option, you must inspect the request/response interactions in the browser’s developer tools, under the Network tab, while performing the authentication flow without the BCR extension installed. The following results can help you determine the authentication type:

For Redirection based authentication: Look under the Status column for one or more 302 (Redirection) responses. The 302 responses should contain a location header pointing to the authentication page. This page URL must be set in the Browser Content Redirection block list policy if you are using Method 1 and denyList section of the app configuration in the bcrconfig.json file if you are using Method 2.

For In-page forms-based authentication: Look under the Method column for several POST requests. One of the later responses to a POST request should return a set-cookie header with the web-app specific authentication cookie. This cookie should be set in the cookies section of the app configuration in the bcrconfig.json file. As Method 1 doesn’t support In-page forms-based authentication, Method 2 is the only configuration option for this scenario.

Example: Here’s an example with github.com. This method can be used for any website that you want to redirect with BCR and ensure that you have the right configuration

  1. Open Chrome, then press CTRL+SHIFT+I to bring up its developer tools.
  2. Click on the Network tab.
  3. Check the Preserve log setting.
  4. Click on the Doc filter to simplify the network logs.
  5. Right click next to the Name and add the URL column.
  6. Browser to github.com while the developer tools are still open.
  7. Sign in to github.com
  8. Note all the intermediate hops between github.com’s initial page and its destination after logon has occurred.
  9. Analyze the request/response headers to determine the authentication type as specified above.

Step 2: Choose a configuration method

  1. If you’re dealing with only Redirection based authentication and you don’t have a need for redirecting multiple web applications with varying needs (e.g., one web application with Redirection based authentication and another web application with In-page forms based authentication), you can choose Method 1 to configure Single sign-on.

  2. If you’re dealing with In-page forms-based authentication (or) you are dealing with multiple web applications with different authentication mechanisms (or) simply want more flexibility even if you just have Redirection based authentication, you can choose Method 2.

Step 3: Configure

Method 1: Configure BCR Single sign-on with existing policies

  1. Enable the feature in the VDA by creating the following registry value in the HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\HDXMediaStream key: Dword BrowserProfileSharing value 1
  2. Configure the Browser content redirection ACL configuration policy with the websites to be redirected. No change in configuration on this front.
  3. In case you have URLs configured in authentication sites policy already, copy them into the Browser content redirection block list policy and disable the authentication sites policy.
  4. In case you haven’t configured authentication / intermediary sites previously, then identify the intermediary URLs (from the request/response interactions in the browser’s developer tools, under the Network tab, while performing the authentication flow without the BCR extension installed) and configure them in the block list.

Method 2: Configure BCR Single sign-on with JSON

Creating bcrconfig.json

The bcrconfig.json can contain several web app configurations. BCR extension will try to match the requested URL to one of the allowList specified by one of the apps in the apps array and dynamically apply its related rules to decide how to handle page redirection and single sign on processing. The following keys can be utilized to control how a web app is treated by the BCR extension (please note that boolean values must be lower case as per JSON specifications - true or false only):

  • appName [string value, mandatory]: This is mainly used internally by the extension and for logging purposes.

  • allowList [string array, mandatory]: An app must contain at least one URL in allowList, which is the URL that is intended to be redirected so that the client should render the page, not the VDA. Multiple URLs can be defined, and wildcards are accepted. The wildcard rules are exactly the same as Browser Content Redirection ACL configuration. For example, to configure all Google apps to be redirected, utilize the following array:

    [“.google.com/”, “.google.com”, “.youtube.com”, “.youtube.com/”]

  • denyList [string value, optional]: Define the URLs to which the web application redirects the user when authentication is required. This configuration is primarily essential for redirection-based authentication, but it can also be used to prevent specific redirects in some forms-based authentication flows. URLs listed in this key will not be redirected so that server-side authentication occurs. You can also use this when profile sharing is not needed to restrict specific sub-URLs of a domain to not get redirected to the client.
  • profileSharing [boolean value, mandatory]: This is the key value that needs to be set to ensure Single sign-on authentication cookies and other cookies that store user preferences to be shared, ensuring consistent behavior between server-side and client-side rendered pages.
  • cookies [string array, optional]: Define one or more authentication cookies necessary for the web application to load without prompting the user. The extension will then prevent client-side redirection until all cookies listed here are detected as set for the given web app URL. This setting is primarily used for In-page forms-based authentication, but it can also be utilized for redirection-based authentication in addition to specifying denyList in certain scenarios.
  • deleteClientCache[boolean value, optional]: If bcrconfig.json configuration mechanism is used, then the BCR client deletes its browser cache by default for enhanced security. This process happens when the user closes all redirected tabs or starts a redirected page for the first time in a session. Set this key’s value to false to prevent this behavior. If client device is trusted, then setting this key to false can enhance user experience. If client device is not trusted, then not setting this key (or) setting this key to true can enhance security posture.
  • schemaVersion [string value, mandatory]: This is mainly used internally by the extension and for logging purposes. At the time of this writing, it should have its value set to 2511.
Example Configuration 
{
  "apps": [
    {
      "appName": "myWebApp1",
      "allowList": [
        "https://myWebApp1.com/*"
      ],
      "denyList": [],
      "requires": {
        "profileSharing": false,
        "cookies": []
      }
    },
    {
      "appName": "myWebApp2",
      "allowList": [
        "https://myWebApp2.com/*"
      ],
      "denyList": [
        "https://myWebApp2.com/authPortal/*"
      ],
      "requires": {
        "profileSharing": true,
        "cookies": []
      }
    },
    {
      "appName": "myWebApp3",
      "allowList": [
        "https://*.myWebApp3.com/"
      ],
      "denyList": [
        "https://myWebApp3.com/authPortal/*"
      ],
      "requires": {
        "profileSharing": true,
        "cookies": [
          "requiredAuthCookie1",
          "requiredAuthCookie2"
        ]
      }
    }
  ],
  "preferences": {
    "deleteClientCache": true
  },
  "schemaVersion": "2511"
}
<!--NeedCopy-->

Here is a sample bcrconfig.json file. Its elements are explained in detail below:

The JSON structure above contains 3 apps with different configurations:

myWebApp1 scenario, no SSO:

  • The allowList key’s string array value specifies that all paths within https://myWebApp1.com should be redirected to the client, except for values listed in the denyList key, if any.
  • The denyList key’s string array value is empty, so no authentication sites will be prevented from redirection. So, authentication will not be kept strictly on the server side.
  • The profileSharing key’s boolean value is set to false, so no cookies pertaining to the allowList entries will be shared with the client.
  • The cookies key’s string array is empty, but it would have been ignored anyways since the profileSharing sharing key is set to false.

myWebApp2, redirection-based authentication scenario:

  • The allowList key’s string array value specifies that all paths within https://myWebApp2.com should be redirected to the client, except for values listed in the denyList key, if any.

  • The denyList key’s string array value specifies that paths that start with /authPortal/ under the myWebApp2.com domain will be prevented from client-side redirection so that server-side authentication can be performed.

  • The profileSharing key’s boolean value is set to true, so cookies pertaining to the allowList entries will be shared with the client and single sign-on goes through.

  • The cookies key’s string array is empty, so the extension will not wait for a specific cookie to be set post server-side authentication before they are shared with the client.

myWebApp3, forms-based authentication scenario:

  • The allowList key’s string array value specifies that all paths within https://myWebApp3.com should be redirected to the client, except for values listed in the denyList key, if any.
  • The denyList key’s string array value specifies that paths that start with /authPortal/ under the myWebApp2.com domain will be prevented from client-side redirection so that server-side authentication can be performed.
  • The profileSharing key’s boolean value is set to true, so cookies pertaining to the allowList entries will be shared with the client.
  • The cookies key’s string array contains a cookie name, so the extension will wait for this cookie to be set post server-side authentication. The cookie for the related URL in allowList will be shared with the client and client-side redirection will occur.
Preferences
  • The deleteClientCache key is set to be true, so the BCR client deletes its browser cache by default for enhanced security. This is the default behavior even if the key is not set.
Configuring the BCR policy

Once you have created the bcrconfig.json, follow the steps below to configure the Browser Content Redirection ACL configuration to use the content in the JSON file.

  • Name the file with .bcrconfig.json extension, for example, myrules.bcrconfig.json

  • Host the JSON file on a webserver accessible to the VDA and note the URL.

    Note:

    The server must allow file downloads; Microsoft IIS sites permit JSON file downloads by default.

  • In Citrix Studio, under the Policies, add the URL from the previous step to the Browser content redirection ACL configuration setting:

    Note:

    Other entries in the Browser content redirection ACL configuration setting can remain. The BCR Extension prioritizes the bcrconfig.json settings if conflicts arise. Citrix recommends shifting the entire configuration to JSON for ease of management, application-level configuration and scalability.

  • Save the policy and launch a session to test the policy configuration.

    Note:

    After setting the policy, you can edit the hosted bcrconfig.json file anytime for tuning. The file reloads and applies changes only when the main browser process running the BCR extension launches or relaunches.

Note:

  • In essence, from the policy perspective, you need to just enable Browser Content Redirection policy (which is enabled by default) and configure Browser Content Redirection ACL configuration policy with the URL which points to the JSON file.

  • JSON configuration currently applies to the following policies and makes them flexible, but the rest of the policies continue to do the same actions as before.

    • Browser content redirection ACL configuration: URLs in the ACL can now be configured via JSON through allowList key.
    • Browser Content redirection block list configuration: Blocklist can now be configured via JSON through denyList key.
    • Browser Content redirection authentication sites: Authentication sites can also be configured via JSON through denyList key.
Single sign-on support
February 9, 2026
Contributed by: 
C
February 9, 2026
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.