SDK troubleshooting
ForgeRock SDK for JavaScript
Troubleshoot your JavaScript apps
Knowledge base
Browse our extensive list of articles regarding diagnosing and fixing issues you might encounter when using the ForgeRock SDKs.
Getting support
Discover how to contact our support team for specific assistance not covered in the documentation or knowledge base.
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.
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.
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.
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.
|
In ForgeRock SDK for JavaScript 2.2 and earlier, |
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'
});|
The |
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
ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.
ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock’s support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.
ForgeRock publishes comprehensive documentation online:
-
The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.
While many articles are visible to everyone, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.
-
ForgeRock 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.