Keycloak (v0.8.7) | LibreChat

Archived documentation

You are reading the frozen documentation for v0.8.7, which is no longer maintained. Go to the latest docs.

Access Keycloak Admin Console:

Open the Keycloak Admin Console in your web browser. This is usually found at a URL like http://localhost:8080/auth/admin/.

Create a Realm (if necessary):

If you don't already have a realm for your application, create one. Click on 'Add Realm' and give it a name.

Create a Client:

Within your realm, click on 'Clients' and then 'Create'.
Enter a client ID and select 'openid-connect' as the Client Protocol.
Set 'Client Authentication' to 'On'.
In 'Valid Redirect URIs', enter http://localhost:3080/oauth/openid/callback or the appropriate URI for your application.

Configure Client:

After creating the client, you will be redirected to its settings page.
Note the 'Client ID' and 'Secret' from the 'Credentials' tab – you'll need these for your application.

Add Roles (Optional): If you want to restrict access to users with specific roles, you can define roles in Keycloak and assign them to users.

Go to the 'Roles' tab in your client or realm (depending on where you want to define the roles).
Create roles that match the value(s) you have in OPENID_REQUIRED_ROLE.

Assign Roles to Users (Optional):

Go to 'Users', select a user, and go to the 'Role Mappings' tab.
Assign at least one of the roles specified in OPENID_REQUIRED_ROLE to the user.

Get path of roles list inside token (Optional):

Decode your jwtToken from OpenID provider and determine path for roles list inside access token. For example, if you are using Keycloak, the path is realm_access.roles.
Put this path in OPENID_REQUIRED_ROLE_PARAMETER_PATH variable in .env file.
By parameter OPENID_REQUIRED_ROLE_TOKEN_KIND you can specify which token kind you want to use. Possible values are access and id.

Update Your Project's Configuration:

Open the .env file in your project folder and add the following variables:

OPENID_ISSUER=http://localhost:8080/realms/[YourRealmName]
OPENID_CLIENT_ID=[YourClientID]
OPENID_CLIENT_SECRET=[YourClientSecret]
OPENID_SESSION_SECRET=[JustGenerateARandomSessionSecret]
OPENID_CALLBACK_URL=/oauth/openid/callback
OPENID_SCOPE="openid profile email"
OPENID_REQUIRED_ROLE=[YourRequiredRole] # Single role or comma-separated roles (e.g., role1,role2,admin)
OPENID_REQUIRED_ROLE_TOKEN_KIND=(access|id) # that means, `access` or `id`
OPENID_REQUIRED_ROLE_PARAMETER_PATH="realm_access.roles"

# Optional: redirects the user to the end session endpoint after logging out
OPENID_USE_END_SESSION_ENDPOINT=true

# Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
# OPENID_MAX_LOGOUT_URL_LENGTH=2000