Keycloak Configuration

Getting the issuerUri and clientId

Oidc-spa need to two parameter to connect with your Keycloak instance, the issuerUri and the clientId.

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

issuerUri

In Keycloak, the OIDC issuer uri is formatted as such:

https://<KC_DOMAIN><KC_RELATIVE_PATH>/realms/<REALM_NAME>

• <KC_DOMAIN>: The domain of your Keycloak server, example: auth.my-company.com.

• <KC_RELATIVE_PATH>: The sub path under your which your Keycloak is hosted. By default, in recent version of keycloak it's "" (empty string). On older Keycloak version it used to be "/auth" by default. Check how you Keycloak server is configured. This parrameter is usualy set by an environement variable. Example -e KC_HTTP_RELATIVE_PATH=/auth.

• <REALM_NAME>: The name of your realm. Example: myrealm. One important note is that you should always create create a realm for your organization and never use the master realm. To create a realm navigate to https://<DOMAIN><KC_RELATIVE_PATH>/admin/master/console login as an administrator, click on the select at the top left corner of the page, click on "Create a new Realm", give it a name, save.

clientId

The client it is usualy something like 'myapp'. Let's see how to create a client suitable for your SPA.

1. Connect to your Keycloak Admin Console: https://<KC_DOMAIN><KC_RELATIVE_PATH>/admin/master/console

2. Login as an admin

3. Using the select input in the top left corner, navigate to your realm.

4. In the left pannel click on Clients.

5. Click on Create Client.

6. Fill in the Client ID, for example myapp, click on next.

7. Make sure Client authentication is off and that Standard Flow is checked in, click next.

8. Set two Valid Redirect URIs: https://<APP_DOMAIN><BASE_URL>oidc-callback.htm and http://localhost:<DEV_PORT>/oidc-callback.htm.

   1. <APP_DOMAIN>: Examples: https://my-company.com or https://app.my-company.com. Note that in order to avoid issues related to the end of third party cookies it's important that <APP_DOMAIN> and <KC_DOMAIN> be hosted under the same root domain (my-company.com).

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

   3. <DEV_PORT>: Example: 5173 (Default port of the Vite dev server)

   4. If you are not using using the oidc-callbak.htm file, remove the /oidc-callback.htm portion of the urls, there should be no trailing slashes at the end.

9. Feel free to fill in the other field but they are not required. Click Save, you're done!

Session lifespawn configuration

One important policy you want to define is how often you want your user to have to authenticate again when they visite your site. Note that the parameter that we will configure here do not affect the lifespawn of the access token that remains 5 minuts by default. What we are tweaking here is for how long Keycloak will keep the session active and that is reflected in the livespawn of the reflesh token, this how oidc-spa is able to learn about it.

Let's see the good defaults for the two more common scenario:

Sensitive apps like Banking, Admin pannels ect...

For thoses kind of web applications, you want the user to have to login again each time they visit your app. You also want them to be automatically loged out after .

To enforce this policy you want to:

• Disable the "Remeber Me" checkbox when logging in:

  • Select your realm

  • In the left menu navigate to realm settings

  • Go to the Login tab

  • Set "Remember Me" to Off

• Set the session Idle time:

  • In the Realm settings go to the Session Tab

  • Set Session idle: 5min

  • Session idle MAX: 14 days, if your user is actively using your app for days, there's no reason to desconect them.

You can display a coundown timer before auto logout with:

Auto Logout

Non sensitive app like ecomerce boutique or social media app

For thoses kind of app you don't want your user to have to authenticate every other day. Take YouTube for example, each time you reach the site your logged in already, we want this type of behaviour.

To enable it

• Enable the possibility for your user to check a "Remeber Me" checkbox when logging in:

  • Select your realm

  • In the left menu navigate to realm settings

  • Go to the Login tab

  • Set "Remember Me" to On

• Set the session idle: You want the users that haven't checked "Remember Me" to have to re authenticate once every 2 week.

  • In the Realm settings go to the Session Tab

  • Set Session idle and Session Idle Max to 14 days

• Set the session idle Remember Me: You want the users that have explicitely checked "Remeber Me" when logging in to only have to authenticate again once every year.

  • In the Session tab of the Realm settings, set Session idle Remeber Me and Session Idle Max Remember me to 356 days.

Enabling user to delete their own account

By default on Keycloak, users are not allowed to delete their accout.

If you try to implement a delete account button, when clicking on it, your users will be granted with an "action non permited" screen.

To enable it:

1. In the left bar navigate to Autentication -> Required Action -> "Delete Account" Enabled: On

2. In the left bar navigate to Realm Setting -> User Registration -> Default Roles -> Assign Role -> Filter by client -> select Delete Account and click on assign.