@lobehub/chat 1.77.18 → 1.78.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 # Changelog
 
+## [Version 1.78.0](https://github.com/lobehub/lobe-chat/compare/v1.77.18...v1.78.0)
+
+<sup>Released on **2025-04-09**</sup>
+
+#### ✨ Features
+
+- **misc**: Add Keycloak SSO provider support.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **misc**: Add Keycloak SSO provider support, closes [#7342](https://github.com/lobehub/lobe-chat/issues/7342) ([f739425](https://github.com/lobehub/lobe-chat/commit/f739425))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 1.77.18](https://github.com/lobehub/lobe-chat/compare/v1.77.17...v1.77.18)
 
 <sup>Released on **2025-04-09**</sup>

package/README.md

@@ -333,7 +333,7 @@ In addition, these plugins are not limited to news aggregation, but can also ext
 | [MintbaseSearch](https://lobechat.com/discover/plugin/mintbasesearch)<br/><sup>By **mintbase** on **2024-12-31**</sup>       | Find any NFT data on the NEAR Protocol.<br/>`crypto` `nft`                                                              |
 | [Bing_websearch](https://lobechat.com/discover/plugin/Bingsearch-identifier)<br/><sup>By **FineHow** on **2024-12-22**</sup> | Search for information from the internet base BingApi<br/>`bingsearch`                                                  |
 
-> 📊 Total plugins: [<kbd>**46**</kbd>](https://lobechat.com/discover/plugins)
+> 📊 Total plugins: [<kbd>**45**</kbd>](https://lobechat.com/discover/plugins)
 
  <!-- PLUGIN LIST -->
 

package/README.zh-CN.md

@@ -326,7 +326,7 @@ LobeChat 的插件生态系统是其核心功能的重要扩展，它极大地
 | [MintbaseSearch](https://lobechat.com/discover/plugin/mintbasesearch)<br/><sup>By **mintbase** on **2024-12-31**</sup>     | 在 NEAR 协议上查找任何 NFT 数据。<br/>`加密货币` `nft`                             |
 | [必应网页搜索](https://lobechat.com/discover/plugin/Bingsearch-identifier)<br/><sup>By **FineHow** on **2024-12-22**</sup> | 通过 BingApi 搜索互联网上的信息<br/>`bingsearch`                                   |
 
-> 📊 Total plugins: [<kbd>**46**</kbd>](https://lobechat.com/discover/plugins)
+> 📊 Total plugins: [<kbd>**45**</kbd>](https://lobechat.com/discover/plugins)
 
  <!-- PLUGIN LIST -->
 

package/changelog/v1.json

@@ -1,4 +1,13 @@
 [
+  {
+    "children": {
+      "features": [
+        "Add Keycloak SSO provider support."
+      ]
+    },
+    "date": "2025-04-09",
+    "version": "1.78.0"
+  },
   {
     "children": {
       "improvements": [

package/docs/self-hosting/advanced/auth/next-auth/keycloak.mdx

@@ -0,0 +1,119 @@
+---
+title: Configuring Keycloak Authentication Service in LobeChat
+description: >-
+  Learn how to configure the Keycloak authentication service in LobeChat,
+  including deployment, creation, permission settings, and environment
+  variables.
+tags:
+  - Keycloak Authentication
+  - Environment Variable Configuration
+  - Single Sign-On
+  - LobeChat
+---
+
+# Configuring Keycloak Authentication Service in LobeChat
+
+[Keycloak](https://www.keycloak.org/) is an open-source identity and access management solution that provides single sign-on, identity brokering, and social login features, suitable for modern applications and services.
+
+<Callout type={'tip'}>
+  If you want to privately deploy Keycloak, we recommend using it together with LobeChat via Docker Compose deployment for easier service management.
+</Callout>
+
+## Keycloak Configuration Process
+
+If you deploy using a local network IP, this guide assumes:
+
+- Your LobeChat database version IP/port is `http://LOBECHAT_IP:3210`.
+- Your privately deployed Keycloak domain is `http://KEYCLOAK_IP:8080`.
+
+If you deploy using a public network, this guide assumes:
+
+- Your LobeChat database version domain is `https://lobe.example.com`.
+- Your privately deployed Keycloak domain is `https://lobe-auth-api.example.com`.
+
+<Steps>
+  ### Create Keycloak Realm and Client
+
+  Access your privately deployed Keycloak admin console (default is `http://localhost:8080/admin`) and log in with the administrator account.
+
+  1. Create a new Realm
+     - Click the dropdown menu in the upper left corner and select "Create Realm"
+     - Enter a name, such as "LobeChat", then click "Create"
+
+  2. Create a Client
+     - Select "Clients" from the left menu, then click "Create client"
+     - Fill in the following information:
+       - Client ID: `lobechat`
+       - Client type: `OpenID Connect`
+       - Click "Next"
+     - On the "Capability config" page:
+       - Enable "Client authentication"
+       - Enable "Standard flow"
+       - Click "Next"
+     - On the "Login settings" page:
+       - Valid redirect URIs:
+         - Local development environment: `http://localhost:3210/api/auth/callback/keycloak`
+         - Local network IP deployment: `http://LOBECHAT_IP:3210/api/auth/callback/keycloak`
+         - Public environment: `https://lobe.example.com/api/auth/callback/keycloak`
+       - Web origins: Add your LobeChat domain or IP
+       - Click "Save"
+
+  3. Get Client Secret
+     - On the client details page, switch to the "Credentials" tab
+     - Copy the "Client secret" value, which will be needed later
+
+  ### Configure Users and Roles (Optional)
+
+  1. Create Users
+     - Select "Users" from the left menu, then click "Add user"
+     - Fill in the user information and click "Create"
+     - On the user details page, switch to the "Credentials" tab
+     - Set a password, and disable the "Temporary" option if needed
+     - Click "Set Password" to save
+
+  2. Create Roles and Permissions
+     - Select "Realm roles" from the left menu
+     - Click "Create role"
+     - Create necessary roles, such as "admin", "user", etc.
+     - Assign roles to users: On the user details page, switch to the "Role mapping" tab and assign appropriate roles
+
+  ### Disable Registration (Optional)
+
+  To ensure the security of your application, it's recommended to control Keycloak's registration functionality.
+
+  1. Select "Realm settings" from the left menu
+  2. Switch to the "Login" tab
+  3. In the "User registration" section, disable the "User registration" option
+  4. Click "Save" to save the settings
+
+  <Callout type={'warning'}>
+    If registration is not disabled, anyone might be able to register and log in to your application. Please configure according to your security requirements.
+  </Callout>
+
+  ### Configure Environment Variables
+
+  Set the obtained client ID and client secret as `AUTH_KEYCLOAK_ID` and `AUTH_KEYCLOAK_SECRET` in the LobeChat environment variables.
+
+  Configure the LobeChat environment variable `AUTH_KEYCLOAK_ISSUER` as:
+
+  - `http://localhost:8080/realms/LobeChat` for local development environment
+  - `http://KEYCLOAK_IP:8080/realms/LobeChat` for privately deployed Keycloak on a local network
+  - `https://lobe-auth-api.example.com/realms/LobeChat` for Keycloak deployed in a public environment
+
+  When deploying LobeChat, you need to configure the following environment variables:
+
+  | Environment Variable      | Type     | Description                                                                                                                                                                              |
+  | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `NEXT_AUTH_SECRET`        | Required | Key used to encrypt Auth.js session tokens. You can generate a key using: `openssl rand -base64 32`                                                                                      |
+  | `NEXT_AUTH_SSO_PROVIDERS` | Required | Select the single sign-on provider for LobeChat. For Keycloak, fill in `keycloak`.                                                                                                       |
+  | `AUTH_KEYCLOAK_ID`        | Required | Keycloak client ID                                                                                                                                                                       |
+  | `AUTH_KEYCLOAK_SECRET`    | Required | Keycloak client secret                                                                                                                                                                   |
+  | `AUTH_KEYCLOAK_ISSUER`    | Required | OpenID Connect issuer URL for the Keycloak provider, in the format `{keycloak_url}/realms/{realm_name}`                                                                                  |
+  | `NEXTAUTH_URL`            | Required | This URL specifies the callback address for Auth.js during OAuth verification. Only needed when the default generated redirect address is incorrect. `https://lobe.example.com/api/auth` |
+
+  <Callout type={'tip'}>
+    Visit [📘 Environment Variables](/zh/docs/self-hosting/environment-variables/auth#keycloak) for details on related variables.
+  </Callout>
+</Steps>
+
+<Callout type={'info'}>After successful deployment, users will be able to authenticate through Keycloak and use LobeChat.</Callout>

package/docs/self-hosting/advanced/auth/next-auth/keycloak.zh-CN.mdx

@@ -0,0 +1,116 @@
+---
+title: 在 LobeChat 中配置 Keycloak 身份验证服务
+description: 学习如何在 LobeChat 中配置 Keycloak 身份验证服务，包括部署、创建、设置权限和环境变量。
+tags:
+  - Keycloak 身份验证
+  - 环境变量配置
+  - 单点登录
+  - LobeChat
+---
+
+# 配置 Keycloak 身份验证服务
+
+[Keycloak](https://www.keycloak.org/) 是一个开源的身份和访问管理解决方案，提供单点登录、身份代理和社交登录等功能，适用于现代应用和服务。
+
+<Callout type={'tip'}>
+  若你想要私有部署 Keycloak，我们建议你将之与 LobeChat 一同使用 Docker Compose 部署，这样可以更方便地管理服务。
+</Callout>
+
+## Keycloak 配置流程
+
+若你使用局域网 IP 部署，下文假设：
+
+- 你的 LobeChat 数据库版本 IP / 端口为 `http://LOBECHAT_IP:3210`。
+- 你私有部署 Keycloak，其域名为 `http://KEYCLOAK_IP:8080`。
+
+若你使用公网部署，下文假设：
+
+- 你的 LobeChat 数据库版本域名为 `https://lobe.example.com`。
+- 你私有部署 Keycloak，其域名为 `https://lobe-auth-api.example.com`。
+
+<Steps>
+  ### 创建 Keycloak 领域和客户端
+
+  访问你私有部署的 Keycloak 管理控制台（默认为 `http://localhost:8080/admin`），使用管理员账号登录。
+
+  1. 创建新领域（Realm）
+     - 点击左上角的下拉菜单，选择 "Create Realm"
+     - 输入名称，例如 "LobeChat"，然后点击 "Create"
+
+  2. 创建客户端（Client）
+     - 在左侧菜单中选择 "Clients"，然后点击 "Create client"
+     - 填写以下信息：
+       - Client ID: `lobechat`
+       - Client type: `OpenID Connect`
+       - 点击 "Next"
+     - 在 "Capability config" 页面：
+       - 启用 "Client authentication"
+       - 启用 "Standard flow"
+       - 点击 "Next"
+     - 在 "Login settings" 页面：
+       - Valid redirect URIs:
+         - 本地开发环境：`http://localhost:3210/api/auth/callback/keycloak`
+         - 局域网 IP 部署：`http://LOBECHAT_IP:3210/api/auth/callback/keycloak`
+         - 公网环境：`https://lobe.example.com/api/auth/callback/keycloak`
+       - Web origins: 添加你的 LobeChat 域名或 IP
+       - 点击 "Save"
+
+  3. 获取客户端密钥
+     - 在客户端详情页，切换到 "Credentials" 选项卡
+     - 复制 "Client secret" 的值，后续需要用到
+
+  ### 配置用户和角色（可选）
+
+  1. 创建用户
+     - 在左侧菜单中选择 "Users"，然后点击 "Add user"
+     - 填写用户信息，点击 "Create"
+     - 在用户详情页，切换到 "Credentials" 选项卡
+     - 设置密码，并根据需要禁用 "Temporary" 选项
+     - 点击 "Set Password" 保存
+
+  2. 创建角色和权限
+     - 在左侧菜单中选择 "Realm roles"
+     - 点击 "Create role"
+     - 创建所需角色，如 "admin"、"user" 等
+     - 为用户分配角色：在用户详情页，切换到 "Role mapping" 选项卡，分配相应角色
+
+  ### 关闭注册（可选）
+
+  为了保证你的应用安全，建议控制 Keycloak 的注册功能。
+
+  1. 在左侧菜单中选择 "Realm settings"
+  2. 切换到 "Login" 选项卡
+  3. 在 "User registration" 部分，禁用 "User registration" 选项
+  4. 点击 "Save" 保存设置
+
+  <Callout type={'warning'}>
+    如果不关闭注册功能，任何人都可能注册并登录你的应用，请根据你的安全需求进行配置。
+  </Callout>
+
+  ### 配置环境变量
+
+  将获取到的客户端 ID 和客户端密钥，设为 LobeChat 环境变量中的 `AUTH_KEYCLOAK_ID` 和 `AUTH_KEYCLOAK_SECRET`。
+
+  配置 LobeChat 环境变量中 `AUTH_KEYCLOAK_ISSUER` 为：
+
+  - `http://localhost:8080/realms/LobeChat`，若你是本地开发环境
+  - `http://KEYCLOAK_IP:8080/realms/LobeChat`，若你是局域网私有部署的 Keycloak
+  - `https://lobe-auth-api.example.com/realms/LobeChat`，若你是公网环境部署的 Keycloak
+
+  在部署 LobeChat 时，你需要配置以下环境变量：
+
+  | 环境变量                      | 类型 | 描述                                                                                               |
+  | ------------------------- | -- | ------------------------------------------------------------------------------------------------ |
+  | `NEXT_AUTH_SECRET`        | 必选 | 用于加密 Auth.js 会话令牌的密钥。您可以使用以下命令生成秘钥： `openssl rand -base64 32`                                    |
+  | `NEXT_AUTH_SSO_PROVIDERS` | 必选 | 选择 LoboChat 的单点登录提供商。使用 Keycloak 请填写 `keycloak`。                                                 |
+  | `AUTH_KEYCLOAK_ID`        | 必选 | Keycloak 客户端 ID                                                                                  |
+  | `AUTH_KEYCLOAK_SECRET`    | 必选 | Keycloak 客户端密钥                                                                                   |
+  | `AUTH_KEYCLOAK_ISSUER`    | 必选 | Keycloak 提供程序的 OpenID Connect 颁发者 URL，格式为 `{keycloak_url}/realms/{realm_name}`                   |
+  | `NEXTAUTH_URL`            | 必选 | 该 URL 用于指定 Auth.js 在执行 OAuth 验证时的回调地址，当默认生成的重定向地址发生不正确时才需要设置。`https://lobe.example.com/api/auth` |
+
+  <Callout type={'tip'}>
+    前往 [📘 环境变量](/zh/docs/self-hosting/environment-variables/auth#keycloak) 可查阅相关变量详情。
+  </Callout>
+</Steps>
+
+<Callout type={'info'}>部署成功后，用户将可以通过 Keycloak 身份认证并使用 LobeChat。</Callout>

package/docs/self-hosting/advanced/auth.mdx

@@ -52,6 +52,8 @@ Currently supported identity verification services include:
   <Card href={'/docs/self-hosting/advanced/auth/next-auth/authelia'} title={'Authelia'} />
 
   <Card href={'/docs/self-hosting/advanced/auth/next-auth/logto'} title={'Logto'} />
+
+  <Card href={'/docs/self-hosting/advanced/auth/next-auth/keycloak'} title={'Keycloak'} />
 </Cards>
 
 Click on the links to view the corresponding platform's configuration documentation.
@@ -73,6 +75,7 @@ The order corresponds to the display order of the SSO providers.
 | Logto                 | `logto`                 |
 | Microsoft Entra ID    | `microsoft-entra-id`    |
 | ZITADEL               | `zitadel`               |
+| Keycloak              | `keycloak`              |
 
 ## Other SSO Providers
 

package/docs/self-hosting/advanced/auth.zh-CN.mdx

@@ -49,6 +49,8 @@ LobeChat 与 Clerk 做了深度集成，能够为用户提供一个更加安全
   <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/authelia'} title={'Authelia'} />
 
   <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/logto'} title={'Logto'} />
+
+  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/keycloak'} title={'Keycloak'} />
 </Cards>
 
 点击即可查看对应平台的配置文档。
@@ -70,6 +72,7 @@ LobeChat 与 Clerk 做了深度集成，能够为用户提供一个更加安全
 | Logto                 | `logto`                 |
 | Microsoft Entra ID    | `microsoft-entra-id`    |
 | ZITADEL               | `zitadel`               |
+| Keycloak              | `keycloak`              |
 
 ## 其他 SSO 提供商
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/chat",
-  "version": "1.77.18",
+  "version": "1.78.0",
   "description": "Lobe Chat - an open-source, high-performance chatbot framework that supports speech synthesis, multimodal, and extensible Function Call plugin system. Supports one-click free deployment of your private ChatGPT/LLM web application.",
   "keywords": [
     "framework",

package/src/libs/next-auth/sso-providers/index.ts

@@ -6,6 +6,7 @@ import Casdoor from './casdoor';
 import CloudflareZeroTrust from './cloudflare-zero-trust';
 import GenericOIDC from './generic-oidc';
 import Github from './github';
+import Keycloak from './keycloak';
 import Logto from './logto';
 import MicrosoftEntraID from './microsoft-entra-id';
 import WeChat from './wechat';
@@ -24,4 +25,5 @@ export const ssoProviders = [
   Casdoor,
   MicrosoftEntraID,
   WeChat,
+  Keycloak,
 ];

package/src/libs/next-auth/sso-providers/keycloak.ts

@@ -0,0 +1,25 @@
+import Keycloak from 'next-auth/providers/keycloak';
+
+import { CommonProviderConfig } from './sso.config';
+
+const provider = {
+  id: 'keycloak',
+  provider: Keycloak({
+    ...CommonProviderConfig,
+    // Specify auth scope, at least include 'openid email'
+    authorization: { params: { scope: 'openid email profile' } },
+    clientId: process.env.AUTH_KEYCLOAK_ID,
+    clientSecret: process.env.AUTH_KEYCLOAK_SECRET,
+    issuer: process.env.AUTH_KEYCLOAK_ISSUER,
+    profile(profile) {
+      return {
+        email: profile.email,
+        id: profile.sub,
+        name: profile.name,
+        providerAccountId: profile.sub,
+      };
+    },
+  }),
+};
+
+export default provider;