Keycloak

Getting the issuerUri and clientId

oidc-spa requires two parameters to connect to your Keycloak instance: issuerUri and clientId.

const { ... } = createOidc({
    issuerUri: "...",
    clientId: "...",
    // ...
});

issuerUri

In 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

• <REALM_NAME>: The name of your realm (e.g., myrealm). 🔹 Important: Always create a dedicated realm for your organization—never use the master realm. To create a new realm:

  1. Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.

  2. Log in as an administrator.

  3. Click on the realm selector in the top-left corner.

  4. Click "Create a new Realm", give it a name, and save.

clientId

The clientId is usually something like 'myapp'. Follow these steps to create a suitable client for your SPA:

1. Open https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console.

2. Log in as an administrator.

3. Select your realm from the top-left dropdown.

4. In the left panel, click Clients.

5. Click Create Client.

6. Enter a Client ID, for example, myapp, and click Next.

7. Ensure Client Authentication is off, and Standard Flow is enabled. Click Next.

8. 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 end of third party cookies.

     • <BASE_URL>: Examples: "/" or "/dashboard/".

     • <DEV_PORT>: Example: 5173 (default for Vite's dev server, adapt to your setup).

9. Click Save, and you're done! 🎉

---

Session Lifespan Configuration

One important policy to define is how often users need to re-authenticate when visiting your site.

This configuration does not affect the access token lifetime (default: 5 minutes). It controls how long Keycloak keeps the session active.

🔐 Security-Sensitive Apps (Banking, Admin Panels, etc.)

For security-critical apps, users should log in each visit and be logged out .

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:

1. Disable "Remember Me":

   • Select your realm.

   • Navigate to Realm Settings → Login.

   • Set "Remember Me" to Off.

2. 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).

3. Optionally, display a logout countdown before automatic logout:

Auto Logout

---

🛍️ Non-Sensitive Apps (E-commerce, Social Media, etc.)

For apps where users should remain logged in for weeks or months (e.g., YouTube-style behavior):

1. Enable "Remember Me":

   • Select your realm.

   • Navigate to Realm Settings → Login.

   • Set "Remember Me" to On.

2. 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.

---

🗑️ Allowing Users to Delete Their Own Accounts

By default, Keycloak does not allow users to delete their accounts.

If you implement a delete account button, users will see an "Action not permitted" error.

Enabling Account Deletion:

1. Navigate to Authentication → Required Actions.

2. Enable "Delete Account".

3. Go to Realm Settings → User Registration → Default Roles.

4. Click Assign Role, filter by client, select Delete Account, and assign it.

---