Before you install
Before you install this patch, you must be aware of the following:
- If your cookies are not currently secure, you must enable secure cookies (com.iplanet.am.cookie.secure) before installing this patch to ensure this filter sets the SameSite attribute correctly. See Reference › Cookie for further information.
- This patch makes changes to the web.xml file; if you have customized this, you will need to re-add your changes once you have applied the patch.
Other browsers have introduced similar changes or are in the process of rolling out these changes. In particular, Edge has implemented these changes in version 86 (October 2020), Firefox has been testing SameSite=Lax on its beta users and will roll out to everyone at a later date and Safari blocks all cross-site cookies.
The following links provide more background on these changes and timescales:
Edge: Version 86.0.622.38: October 9
- Firefox: Changes to SameSite Cookie Behavior – A Call to Action for Web Developers
- Safari: Full Third-Party Cookie Blocking and More
SameSite Cookies - Are you Ready?
The SameSite=Lax attribute prevents browsers from sending cookies in cross-site requests (where the registrable domain differs), unless they are top-level navigation requests that use a safe HTTP method (defined as GET, HEAD, OPTIONS or TRACE). Cross-origin requests (for example, a request from ui.example.com to api.example.com) are allowed because the registrable domain is the same. In reality, this means you are unlikely to be affected by this change unless you have genuine multi-domain installs or are using federation.
Expected impacts in AM
The following list provides some features (but not all) that are expected to be affected by these changes:
- SAML2 Single Logout (SLO) using the HTTP POST binding. AM will fail to see the session cookie on the logout request, which will cause logout to fail.
- Some uses of the SAML2 POST binding and the OpenID Connect Form Post response mode may be impacted. In particular, the common pattern of setting the "state" parameter as a cookie at the client before starting an OIDC flow may no longer work if the Form Post response mode is used.
- Any cross-site use of AM's REST APIs that has been configured with Access-Control-Allow-Credentials to enable cookie support. SameSite effectively completely disables this usage of CORS.
The use of AM embedded in an iframe. For example, when using the OIDC checkSession endpoint or doing a "silent renew" pattern such as loading the authorization endpoint in an iframe with prompt=none to check if the user is still logged in.
Expected impacts in IG
IG strips the SameSite attribute in pre-IG 6.5.2 versions. You can upgrade to IG 6.5.2 or later to ensure IG maintains the SameSite attribute setting for any cookies that arrive at IG. See Release Notes › Improvements in IG 6.5.2 for further information.
AM fixed versions and support patches
AM 5.5.2, and AM 18.104.22.168 and later add a new filter that sets the SameSite=None attribute for all secure AM cookies on compatible browsers. You can download this from BackStage.
A SameSite Cookie Support Patch is available for the following versions, which adds the new filter:
- AM 22.214.171.124 (same patch will work for all 6.5.2.x versions)
- AM 6.5.1
- AM 126.96.36.199 (same patch will work for all 6.0.0.x versions)
- AM 5.5.1
- AM 5.1.1
You can download these patch bundles from BackStage. See How do I install an AM/OpenAM patch (All versions) supplied by ForgeRock support? for further information on installing these patches. Since the web.xml file is being updated, you may need to delete the web container working files and restart AM. For example, if you deploy on Apache Tomcat™, you would need to delete the /path/to/tomcat/work/Catalina/localhost/openam/ directory.
The recommendation is to upgrade to a fixed version or deploy the relevant patches at the earliest opportunity to prevent AM features being impacted.
The new filter included in the fixed versions and support patches sets the SameSite=None attribute for all Secure cookies unless:
- The cookie is not set by AM. Cookies set by custom code (for example, cookies containing a nonce or state value when performing an OIDC response_mode=form_post flow) must be manually updated. This can be automated using IG as indicated below.
The user is using an incompatible browser such as Safari on Mac® OS 10.14 or iOS® 12 (which incorrectly treats the SameSite=None attribute as SameSite=Strict). This issue has been fixed in newer versions of Mac OS and iOS.
The filter includes a list of User-Agents for which the filter is disabled based on Google's list (SameSite=None: Known Incompatible Clients). However, you can customize it if required by updating the filter definition for the DisableSameSiteCookiesFilter in the web.xml file (located in the /path/to/tomcat/webapps/openam/WEB-INF directory).
A patch bundle is not available for OpenAM 13.x per the ForgeRock End of Service Life (EOSL) policy.
If you encounter any issues as a result of how Chrome handles SameSite cookies, the recommended workarounds are:
- Upgrade to a fixed version of AM (AM 5.5.2; AM 188.8.131.52 and later).
- Upgrade to a version of AM that has a patch (AM 5.1.1, AM 5.5.1, AM 6.0.0.x, AM 6.5.1 or AM 6.5.2.x) and install the patch.
- Use a binding other than HTTP POST for SLO.
Configuring load balancers, external gateways and reverse proxies is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.
If you are using IG 6.5.2 or later, you can use the sameSite property in CrossDomainSingleSignOnFilter and JwtSession to manage the circumstances in which a cookie is sent to the server. See Configuration Reference › CrossDomainSingleSignOnFilter and Configuration Reference › JwtSession for further information.