What’s the difference between the Keycloak onLoad options?

The Keycloak JavaScript adapter‘s init() method takes an onLoad option that lets you control how Keycloak performs its authentication:

1. login-required
2. check-sso

1. login-required

As soon as keycloak.init() is called, the user is redirected to the Keycloak authorization endpoint to check the user’s authentication status.

If the authorization endpoint detects that the user is authenticated, they’re redirected to the application with the appropriate authentication tokens; otherwise they’re redirected to the Keycloak login page.

login-required is useful for applications where the entire app is only functional if the user is logged in.

See visual illustration here.

2. check-sso

Keycloak will use a hidden iframe to check if the user is already authenticated via an existing session. The iframe request will include any Keycloak cookies like KEYCLOAK_SESSION which the Keycloak server can use to determine the authentication status.

If they user is authenticated, the application receives the authentication tokens. If not, the application still loads but no authentication tokens are available. It’s up to the application developers to handle the authenticated and unauthenticated states.

check-sso is useful when your application needs to be functional for both authenticated and unauthenticated users.

See visual illustration here.

Sources/links

Keycloak JS adapter reference