Proper configuration of Studio policies is necessary for Browser Content Redirection to work.
This article takes Microsoft Teams as an example to describe a modern website using OAuth 2.0 for Authentication.
Browser Content Redirection is a technology built around a URL whitelisting mechanism. Two policies are exposed in Studio for that purpose:
i. Browser content redirection Access Control List (ACL) policy settings (a.k.a the ACL policy)
ii. Browser content redirection authentication sites (a.k.a the authentication sites policy)
While the description in edocs tries to cover the general cases, there are some websites using intrinsic redirection mechanisms that make the whitelisting process more difficult.
[Note: websites that rely on Integrated Windows Authentication, or that require a pop-up Windows Security message box are not handled correctly by BCR with CWA 1905 or older. This is because our overlay browser (HdxBrowser.exe or HdxBrowsercef.exe) cannot display that window, hence the user is stuck on a blank page. See CTX230052 (current limitations section)
CWA 1907 for Windows and higher fixes this problem].
Important Note :
Once the website is redirected to the client successfully(client fetch client render and/or server fetch client render), the authentication part is done client-side, not VDA-side.
So if the client machine is not domain joined, the authentication page will ask for user name and password (and maybe other MFA); the behavior shall be similar to opening the website in incognito-mode in a browser in the client machine.
In other words, after the overlay browser in Workspace app (HdxBrowserCef.exe process on the client machine) has established a connection to a web server, the authentication is done between HdxBrowserCef and the server (and not between the VDA-side browser and the server).
As an example of BCR redirections, we will look into:
Microsoft Teams
Microsoft Teams Live Events
Microsoft Stream
Google Meet
Cisco Webex Teams
Cisco Webex Meetings
GoToMeeting
It is essential that the Developer Tools is used to understand the website's behavior before configuring any policy.
The 'Preserve Log' check-box should be ticked, otherwise entries are cleared automatically.
Microsoft Teams
A user typing http://teams.microsoft.com will get an HTTP 307 response from the webserver, repointing the browser to https://teams.microsoft.com
(Hence it is critical that the right syntax is used when whitelisting a website, like http or https, with or without www, etc - otherwise redirection might fail).
From that URL, the resource https://teams.microsoft.com/auth/prelogin is contacted by the browser, which eventually ends up being redirected to:
https://login.microsoftonline.com/common/oauth2/authorize?response_type=id_token&client_id=xxxxxxxxxxxxxxxxxxxxxxxxx&redirect_uri=https%3A%2F%2Fteams.microsoft.com%2Fgo&state=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&&client-request-id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&x-client-SKU=Js&x-client-Ver=1.0.9&nonce=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1&domain_hint= |
Once the browser loads this page, it 'rests' and waits for user input. These redirections occured very fast, and the HdxVideo.js javascript that the Browser Content Redirection Chrome Extension needs to inject is not done in time.
In this case, the url https://login.microsoftonline.com/* needs to be whitelisted in the ACL policy in Studio.
Since Admins might not want to redirect the entire domain, better granularity can be achieved by leveraging a common parameter in OAuth 2.0 (redirect_uri, where the App name is embedded in the URL).
So whitelisting the following URL in the BCR ACL policy in Studio will achieve the objective, thanks to wildcards:
https://login.microsoftonline.com/*teams*
The Chrome Extension will now be able to inject HdxVideo.js, and the first redirection happens. The user will end up being redirected to an Office 365 Authentication website that is linked to Teams (see screenshot above), but this time the website will be running locally on the endpoint's overlay browser that is part of Workspace app (HdxBrowserCef.exe).
Important: Please note that any IdP/SSO websites your organization deployed to authenticate users in O365 will also need to be added to the Authentication Sites policy (e.g. https://mycompany.okta.com)
Please also note that Teams will require to add https://login.microsoftonline.com/login* to the Authentication Sites.
After a successful authentication, the overlay browser HdxBrowserCef.exe is pointed back to https://teams.microsoft.com
This URL (https://teams.microsoft.com/*) should now be whitelisted also in the 'Authentication Sites' policy in Studio.
Note: This might be somehow counter intuitive as the Authentication site is login.microsoftonline.com, not teams.microsoft.com - yet the problem in Teams is that the Chrome Extension is not loaded fast enough by the Browser and therefore injection fails on teams.microsoft.com.
Browser Content Redirection treats websites whitelisted under the Authentication sites policy as child websites that must remain redirected if the parent website was in the ACL whitelist policy. In the Teams case then, teams.microsoft.com is the child website of the parent login.microsoftonline.com
Microsoft Teams Live Events
Microsoft Teams Live Events are an extension of Teams meetings that enable you to schedule and produce events that stream to large online audiences.
Live Events are not optimized by HDX optimization for Microsoft Teams, so for an attendee, the video is rendered on the VDA instead, taking CPU/RAM/IO/Network resources on the virtual machine.
BCR provides a workaround to this problem - IT Admins can enable BCR and whitelist Live Events, so attendees open a Live Event URL invite on Chrome/Edge in the VDA and BCR will redirect the page to the client.
Typically, Org-wide Live Events permissions require a sign-in, so it is critical to understand your authentication MFA flow and whitelist accordingly.
Once the user clicks on the Live Event invite, the VDA-browser lands on the "Watch the live event in Microsoft Teams" website (left image on the picture above), clicking on "Watch on the web instead" will redirect the user to the "Welcome to the live event" website.
This is the first page you need to whitelist/redirect.
The URL https://teams.microsoft.com/*meetup-join needs to be added to the ACL Studio policy (make sure you are using the * wildcard).
Users then click on "Sign In", and HdxBrowserCef.exe will be landing in the main authentication site for all Microsoft Office 365 services, where the user finally will insert credentials.
Hence the site https://login.microsoftonline.com/* needs to be added to Authentication Sites Studio policy. Users typically enter their email address, and are redirected to your Organization's SAML/MFA page, e.g. https://myorg.okta.com/*.
This URL also has to be added to the Authentication Sites Studio policy: https://myorg.okta.com/* (make sure you are using the * wildcard).
Lastly, add https://teams.microsoft.com/* to the Authentication Sites Studio policy (make sure you are using the * wildcard).
Now the configuration is complete, and users will be able to watch the live event with BCR.
Troubleshooting: If you end up on a different page, or the Authentication flow seems to be not working and the HdxBrowserCef.exe gets stuck in an authentication loop or falls back to the VDA-side browser, it means you missed some URLs in your Organization's authentication flow, and an intermediate page was not added to the Authentication Sites Studio policy.
In such cases, the VDA-side Event Viewer will have an entry that tells you exactly what website URL caused BCR to fail. Add it to the Authentication Sites Studio policy and re-test.
Microsoft Stream
Microsoft's corporate video-sharing platform runs as an Office 365 service.
The URL https://stream.microsoft.com/* needs to be whitelisted in the ACL policy.
That is because whitelisting https://web.microsoftstream.com will not work, since that page redirects to login.microsoftonline.com using HTTP response status code 302 Found, and that page in turn redirects to https://stream.microsoft.com.
Once the browser lands on that website, clicking on Sign In will redirect to https://login.microsoftonline.com/common/oauth2/*microsoftstream*
where the user finally will insert his credentials.
Hence the site https://login.microsoftonline.com/*microsoftstream* needs to be added to Authentication Sites.
(This is different from the behavior in Teams).
If you are using SSO solutions like OKTA, or ADFS, the URLs will need to be added under Authentication Sites also.
Finally, also add https://web.microsoftstream.com/* to the Authentication Sites.
Google Meet
Required policy setting are as follows.
"Browser Content Redirection Authentication Sites"
https://accounts.google.com/*
https://meet.google.com/*
"Browser Content Redirection ACL Configuration"
https://meet.google.com/*
https://apps.google.com/*
Any other website used for SSO (e.g. Okta) must be added to the Authentication Sites policy (it could be more than one).
These websites require WebRTC support, hence you must use Citrix Workspace app 1809 for Windows or higher.
Currently, outgoing screensharing is not supported when using BCR.
Cisco Webex Teams
Add https://teams.webex.com/* to the ACL policy.
Add https://idbroker.webex.com/* to the Authentication Sites policy. This entry might vary depending on your Organization's SSO configuration and IdP providers. Any website used for SSO must be added to the Authentication Sites policy (it could be more than one).
Cisco Webex Meetings
Citrix and Cisco collaborated on this and have a solution ready.https://www.cisco.com/c/en/us/td/docs/collaboration/meeting_center/wvdi/wvdi-b-admin-guide/wvdi-b-admin-guide_chapter_01.pdf
GoToMeeting
First thing to notice is that navigating to https://gotomeet.me/mymeetingID redirects to https://www.gotomeet.me/mymeetingID
Whitelisting without the 'www' will result in failure. So whitelisting https://www.gotomeet.me/* is the solution (in the ACL policy).
Note the use of the wildcard '*' - this allows you to whitelist any path for that URL.
After the webpage is redirected, the user can click 'Join meeting in browser', which points to:
https://app.gotomeeting.com/index.html?meetingId=xxxxxxxxxx
Note that this is a different FQDN. So if the user clicks on that link, he will fall back to server-side.
The solution is to whitelist https://app.gotomeeting.com/*
You can either add this to the ACL policy or to the Authentication Sites policy (or both).
The difference is that if you add it only to the ACL policy, if the user clicks on the link it will trigger a re-processing of the URL by the VDA (look up of that URL in the ACL entries), resulting in a few extra redirection steps.
If you add it to the Authentication Sites policy, then since the parent website is https://www.gotomeet.me/* and that is already whitelisted in the ACL policy, a re-processing of the URL by the VDA is not required and the experience is smoother (see last paragraph under the Teams section).
Of course there could be a scenario where the user types https://app.gotomeeting.com/index.html?meetingId=xxxxxxxxxx directly as the first URL in Chrome's navigation bar. Browser Content Redirection will only kick-in if that URL is on the ACL policy (that is because the Authentication Sites policy is only processed after an ACL match). So in order to prevent this exact scenario from failing, you can add the URL to the ACL and Authentication Sites policies (and hence the reference to 'both' in the paragraph above).
To support new GoToMeeting please add following URLs in the policy "Browser Content Redirection ACL Configuration"
https://meet.goto.com/*
https://app.gotomeeting.com/*
https://global.gotomeeting.com/*