ForgeRock Developer Experience

SDK troubleshooting

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: and

This is common when the ForgeRock® Identity Cloud is running on a ForgeRock provided domain,, and a web app is running on a separately hosted domain, When third-party cookies are disabled by the browser, the set cookie instruction sent by Identity Cloud on, such as the session cookie, to the web app on 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 "" from accessing a cross-origin frame.
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, the web app, and, 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.


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.

In ForgeRock SDK for JavaScript 2.2 and earlier, indexedDB is the default storage mechanism for OAuth/OIDC tokens.


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:

  // standard config settings ...
  tokenStore: 'localStorage', // Or, 'sessionStorage'

The indexedDB option was removed in SDK for JavaScript 4.0. Use sessionStorage or localStorage instead.

Knowledge base

The ForgeRock Knowledge Base contains information on how to diagnose issues within your application, or with communication to the ForgeRock Identity Platform.

For troubleshooting information, see the following articles in the ForgeRock Knowledge Base:

Getting support

Ping Identity provides support services, professional services, training, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see

Ping Identity has staff members around the globe who support our international customers and partners. For details on Ping Identity’s support offering, visit

Ping Identity publishes comprehensive documentation online:

  • The Ping Identity Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock Identity Platform software.

    While many articles are visible to everyone, Ping Identity customers have access to much more, including advanced information for customers using ForgeRock Identity Platform software in a mission-critical capacity.

  • Ping Identity product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

Copyright © 2010-2024 ForgeRock, all rights reserved.