Version Affected: All
How to test SameSite cookies using the SameSiteTester as an initial troubleshooting tool.
Changes to how Chrome 80 will handle SameSite cookies have prompted changes to how Identity Providers and Service Providers also handle SameSite cookies. See this article for more information on those changes:
If the IdP or the SP are not correctly handling SameSite cookies then it can break workflows in ways that are difficult to diagnose. The SameSiteTester can help in determining if SameSite is the cause of an issue and if it is on the IdP side or the SP side.
Download the tool from here:
Right click the ZIP | Properties and click Unblock, then extract both files anywhere that you have write permissions:
All the tool needs to run is a Start URL, this will usually be the URL to an SPInit realm but can be anywhere, including a Service Provider or even a random site. If you want to see it in action you can point it towards:
Run the EXE by either double clicking and it will ask you for a Start URL or from a command line where you can specify the URL as an argument, e.g.:
SameSiteTester -startURL https://portal.secureauth.com
Don't forget the protocol.
The tool will read the accompanying JSON file to retrieve a list of UserAgents and what the correct SameSite response should be. Most modern browsers can handle SameSite=None but those that are incompatible should not be sent a cookie with the SameSite attribute present, that's what "Unset" means.
You can add your own UserAgent strings to the JSON file as desired, the format should be obvious.
What the tool then does for each UserAgent is start at the startURL and follow redirections as necessary (e.g. from IdP SPInit realm to a Service Provider).
It checks these things:
If SameSite is set and should not be <- Problem
If SameSite is set but the Secure flag is not <- Problem
If SameSite should be set but isn't <-Warning
If SameSite is set to a value that it shouldn't be according to the JSON file <- Usually a problem
You may notice it also displays any errors received from the webserver being queried like error 500 etc. That's what the last 2 entries in the JSON file do, they send a NULL user agent and an empty string respectively. In our initial version of the SameSite hotfix it would crash with an internal server error if a NULL user agent was passed (fixed in SameSite hotfix 200106_004_8) so this is a good way of finding realms still on the older hotfix.
The tool outputs a lot of information but it's colour coded to help interpret the results. Basically look for Red and be aware of anything in Yellow.
Green = good
Red = a problem
Yellow = warning, may be a problem, depends on the cookie or error.
Purple = redirect
Blue = Sending a request
If an IdP realm is found to be failing the test then it can usually be fixed by applying the standalone SameSite hotfix, see here:
If a Service Provider is found to be sending SameSite cookies incorrectly then it will need to be taken up with the specific SP and they will need to change their code to implement UserAgent sniffing or undertake other strategies to avoid sending incorrect SameSite cookies.
If this tool proves inconclusive then further manual troubleshooting can be implemented by following this article:
Special Considerations (optional as needed):
The tool does have limitations. It will not be able to follow redirects that require user input (e.g. username and password prompts), but in most circumstances it is possible to workaround by supplying the URL that a browser hits after authentication. Additionally some workflows do not serve cookies until partway though the workflow or until successful authentication.
SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.
Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.