ForgeRock SDKs 3.3

Troubleshooting your JavaScript app

This section contains information on how to diagnose issues within the application, or with communication to the ForgeRock® Identity Platform.

How to fix cross-domain, authenticated-request failures?

As browsers continue to implement stricter privacy and security configurations, third-party cookies are commonly being disabled by default. Third-party cookies are defined by a web app and corresponding server sharing cookies with mismatched domains: example.app and server.com.

This is common when the ForgeRock® Identity Cloud is running on a ForgeRock provided domain, forgeblocks.com, and a web app is running on a separately hosted domain, company.com. When third-party cookies are disabled by the browser, the set cookie instruction sent by Identity Cloud on forgeblocks.com, such as the session cookie, to the web app on company.com will be ignored by the browser. Hence, the cookie will not be written. This will lead to subsequent requests requiring authentication to fail due to the missing cookie.

The Authorization Code Flow (OAuth 2.0) is one such request and the resulting error will resemble this:

SecurityError: Blocked a frame with origin "http://example.com" from accessing a cross-origin frame.
It’s worth noting that this isn’t a CORS configuration issue, even though this mentions "cross-origin". In most cases, this is due to a request to the /authorize endpoint resulting in a redirection within the iframe to the ForgeRock login page, due to the missing session cookie, which is not allowed to be rendered in an iframe for security reasons.

Use a shared parent domain

The best action to take is to ensure all entities of your system are on the same parent domain. This can be done by the use of subdomains with a shared parent domain often using a reverse proxy that routes a request to the appropriate application server. An example would be store.example.com, the web app, and accounts.example.com, the IAM server.

If a shared domain is not possible, the browser configuration will have to be changed.

macOS and iOS Safari workaround

In Apple’s Safari, third-party cookies are disabled by default. Disabling Prevent Cross-site Tracking in Safari’s privacy settings lets Safari use third-party cookies.

Safari’s privacy settings screenshot

Google Chrome and Incognito Mode workaround

Currently, in Google Chrome, third-party cookies are disabled when in Incognito mode by default. This can be fixed by changing the cookie setting from Block third-party cookies in Incognito to Allow all cookies in Chrome settings under Privacy and security > Cookies and other site data.

Chrome’s cookie privacy settings screenshot

How do I enable "platform authenticators" in Safari (iOS and macOS)?

Apple’s latest operating systems (iOS 14 and macOS 11 as of this writing) place a strict requirement for the use of their Face ID and Touch ID (platform authenticators) on the web. The requirement is that a "user gesture" needs to be the trigger prior to, and directly associated with, accessing navigator.credentials, the Web Authentication (aka WebAuthn) API. If there’s not a clear connection between a "user activated event" and the access of the API, Apple will log a warning similar to the following:

User gesture is not detected.
To use the platform authenticator, call ‘navigator.credentials.get’ within user activated events.

This is essentially communicating that the call site of the credentials API needs to happen within the callback function of a user-activated event, like click, touch, keydown, and so on, as opposed to events like DOM load or routing-related events. If there’s too much elapsed time between the event and the API access, or the connection, scope or context of the event is cleared from the DOM or runtime, Apple will not allow the use of its platform authenticators.

Access to non-platform authenticators like roaming (USB) keys will still be available regardless of user activated events.

Solution

First, make sure the "user activated event," such as click, touch, keydown, and so on, precedes the calling of the credentials API, and the call site of the API happens within the event handler’s callback function. Calling the API after a routing event or a DOM load event will not work.

If the issue persists, ensure the DOM element with which the user interacts (button or link), the associated DOM event’s callback function, and its relationship with the credentials API call site is all preserved. Once the API has successfully been triggered, the DOM and event handler-related code can be cleared.

For more information, see this Webkit blog article: Meet Face ID and Touch ID for the Web.

How do I fix "a mutation operation was attempted on a database that did not allow mutations"?

This error message can occur if you are using Firefox’s Private Window mode, which prevents write operations to IndexedDB. For more information, see IndexedDB does not function in private browsing mode.

For version 2.2 and below, IndexedDB is the JavaScript SDK’s default storage mechanism for OAuth/OIDC tokens.

Solution

Because IndexedDB is not writable within Firefox’s private mode, ForgeRock recommends using either localStorage or sessionStorage. You can configure the use of either by setting the tokenStore value on the config object to your preferred option.

Here’s an example:

Config.set({
  // standard config settings ...
  tokenStore: 'localStorage', // Or, 'sessionStorage'
});
Copyright © 2010-2022 ForgeRock, all rights reserved.