issuerUri and clientIdoidc-spa requires two parameters to connect to your Keycloak instance: issuerUri and clientId.
issuerUriIn Keycloak, the OIDC issuer URI follows this format:
https://<KC_DOMAIN><KC_RELATIVE_PATH>/realms/<REALM_NAME>
<KC_DOMAIN>: The domain where your Keycloak server is hosted (e.g., auth.my-company.com).
<KC_RELATIVE_PATH>: The subpath under which Keycloak is hosted. In recent versions, this is an empty string (""). In older versions, it was "/auth".
Check your Keycloak server configuration; this parameter is typically set using an environment variable:
Example: -e KC_HTTP_RELATIVE_PATH=/auth
clientIdThe clientId is usually something like 'myapp'. Follow these steps to create a suitable client for your SPA:
Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.
Log in as an administrator.
Select your realm from the top-left dropdown.
One important policy to define is how often users need to re-authenticate when visiting your site.
For security-critical apps, users should log in each visit and be logged out after inactivity.
Why? Users accessing sensitive applications should not remain authenticated indefinitely, especially if they step away from their device. The session idle timeout ensures automatic logout after inactivity.
Steps to enforce this policy:
Disable "Remember Me":
Select your realm.
Navigate to Realm Settings → Login.
Set "Remember Me"
For apps where users should remain logged in for weeks or months (e.g., YouTube-style behavior):
Enable "Remember Me":
Select your realm.
Navigate to Realm Settings → Login.
Set "Remember Me"
By default, Keycloak does not allow users to delete their accounts.
If you implement a , users will see an "Action not permitted" error.
Enabling Account Deletion:
Navigate to Authentication → Required Actions.
Enable "Delete Account".
Go to Realm Settings → User Registration → Default Roles.
Click Assign Role
To test your configuration:
const { ... } = createOidc({
issuerUri: "...",
clientId: "...",
// ...
});Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.
Log in as an administrator.
Click on the realm selector in the top-left corner.
Click "Create a new Realm", give it a name, and save.
Click Create Client.
Enter a Client ID, for example, myapp, and click Next.
Ensure Client Authentication is off, and Standard Flow is enabled. Click Next.
Set two Valid Redirect URIs, ensure both URLs end with /:
https://<APP_DOMAIN><BASE_URL>
http://localhost:<DEV_PORT><BASE_URL>
Parameters:
<APP_DOMAIN>: Examples: https://my-company.com or https://app.my-company.com. 🔹 For beter performances ensure <APP_DOMAIN> and <KC_DOMAIN> share the same root domain (my-company.com). See .
<BASE_URL>: Examples: "/" or "/dashboard/".
Click Save, and you're done! 🎉
Configure session timeout:
Go to Realm Settings → Sessions.
Set SSO Session idle: 5 minutes (ensures users are logged out after 5 minutes of inactivity).
Set SSO Session max idle: 14 days (ensures users who actively use the app don’t get logged out unnecessarily).
Optionally, display a logout countdown before automatic logout:
Configure session timeout:
Users without "Remember Me" will need to log in every 2 weeks:
Set Session idle timeout: 14 days.
Set Session max idle timeout: 14 days.
Users who checked "Remember Me" should stay logged in for 1 year:
Set Session idle timeout (Remember Me): 365 days.
Set Session max idle timeout (Remember Me): 365 days.
npx degit https://github.com/keycloakify/oidc-spa/examples/tanstack-router-file-based oidc-spa-tanstack-router
cd oidc-spa-tanstack-router
cp .env.local.sample .env.local
# Edit the .env.local file to reflect your configuration
yarn
yarn dev<DEV_PORT>: Example: 5173 (default for Vite's dev server, adapt to your setup).