Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Angular app stuck on start while keycloak-js runs check-sso and the login status iframe

ErrorFailed to initialize adapter

Short answer

On start, keycloak-js with check-sso asks Keycloak whether a session exists, in a hidden iframe or by a redirect. It hangs when the silent check page is not served or not an allowed redirect, when the browser blocks third-party cookies, or when the status iframe cannot talk to Keycloak. Check each in that order.

  • Applies to keycloak-js current release, Angular 19 and 20
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Add the catch around init and log the error. Then request the silent check page directly; it must return the small HTML page, not your Angular index.html.

    keycloak.init({ onLoad: 'check-sso', silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html` })
      .catch(e => console.error('Failed to initialize adapter:', e));
  2. 2Match what you see, then jump to its fix

    1. 1The iframe loads your app's own index page instead of the silent page, or Keycloak shows an invalid redirect errorThe silent check page is missing or is not a valid redirect URIFix
    2. 2Keycloak rejects the request for the app's origin, or the browser reports a cross-origin failure to the Keycloak URLThe client lacks Valid Redirect URIs or Web Origins for the Angular URLFix
    3. 3Works in one browser and hangs or adds an extra redirect in another, especially when Keycloak and the app are on different sitesThe browser blocks third-party cookiesFix
    4. 4The start-up problem disappears when checkLoginIframe is set to falseThe login status iframe cannot finish its check in timeFix

What does the error look like?

  • Failed to initialize adapter

Cause 1 of 4

The silent check page is missing or is not a valid redirect URI

1Check

The page must be served by your application at the URL given in silentCheckSsoRedirectUri, and that URI must be a valid redirect in the client's settings in the Admin Console. Request it and read the response.

curl -s http://localhost:4200/silent-check-sso.html

2Fix

Add the page to the Angular assets so it is served as a static file, and add its full URL to Valid Redirect URIs of the client.

<!-- src/silent-check-sso.html -->
<!doctype html>
<html>
<body>
    <script>
        parent.postMessage(location.href, location.origin);
    </script>
</body>
</html>

3Verify

The curl output shows the script above, and the app starts.

curl -s http://localhost:4200/silent-check-sso.html | grep postMessage

Confirmed by keycloak.org

Did this fix it?

Cause 2 of 4

The client lacks Valid Redirect URIs or Web Origins for the Angular URL

1Check

Open the client in the Admin Console and compare the app URL with Valid Redirect URIs and Web Origins.

echo "App origin: $APP_ORIGIN"

2Fix

Set both fields as specifically as possible: the exact app origin, not a wildcard for every host.

Valid Redirect URIs: http://localhost:4200/*
Web Origins: http://localhost:4200

3Verify

Reload the app; init resolves.

echo "reload and watch the console"

Confirmed by keycloak.org

Did this fix it?

Cause 3 of 4

The browser blocks third-party cookies

1Check

When third-party cookies are blocked, the adapter turns the status iframe off by itself, and silent check-sso is not supported, so it falls back to a normal check-sso redirect. Cookies set by a different site than the page are third-party cookies, and Firefox and Safari block many of them by default. Test in a browser that allows them, or serve both under one site.

echo "compare behaviour with third-party cookies allowed and blocked"

2Fix

Serve the app and Keycloak over TLS on the same site where you can. Keep silentCheckSsoFallback at its default true so the redirect fallback works, and use a shorter access token lifespan, because without the iframe a logout is noticed only when the token is refreshed.

await keycloak.init({
  onLoad: 'check-sso',
  silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`,
  silentCheckSsoFallback: true
});

3Verify

The app loads in both browsers; the blocked one shows one redirect to Keycloak and back.

echo "repeat in both browsers"

Confirmed by keycloak.org

Did this fix it?

Cause 4 of 4

The login status iframe cannot finish its check in time

1Check

Turn the iframe off for one run. If the app now starts, the iframe check is the blocker. The adapter waits up to messageReceiveTimeout (default 10000 ms) for Keycloak's message.

echo "set checkLoginIframe: false for one test run"

2Fix

Raise messageReceiveTimeout if the network is slow; if you accept slower logout detection, set checkLoginIframe to false.

await keycloak.init({
  onLoad: 'check-sso',
  silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`,
  messageReceiveTimeout: 20000,
  // checkLoginIframe: false
});

3Verify

init resolves and the app renders.

echo "watch the console for Failed to initialize adapter"

Confirmed by keycloak.org

Did this fix it?

How do I stop it coming back?

  • Serve silent-check-sso.html as a static file and list its full URL in Valid Redirect URIs for every environment.
  • Always put a catch on keycloak.init so a failure shows up in the console instead of a blank screen.
  • Test sign-in once with third-party cookies blocked before release.
  • Keep Valid Redirect URIs and Web Origins exact for each environment.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Security

Keycloak blocks your single-page app with a CORS error

Request requires preflight, which is disallowed to follow cross-origin redirects.

Keycloak checks the Origin header of a browser call against the Web origins configured on that client and refuses it with 403 when it does not match.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.