pad.ws 使用指南：如何在Keycloak配置用户授权登录

**Pad.ws** 是一款基于浏览器的在线协作白板工具，让你可以随时随地进行创意绘图、头脑风暴和视觉化思考。 https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.padws 应用安装后，打开首页，这里需要先进行授权登录 ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/280f9eda-4eb6-4fa0-b2df-1ccd10de3c53.png "image.png") ## 在 Keycloak 中创建 Client 的完整步骤 ### 第1步：进入 Keycloak 管理界面 1. 访问：`https://padws.域名.heiyu.space/auth/` 2. 登录： - Username: `admin` - Password: `admin123` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/a9b95d59-0110-4a78-b594-9246f8641369.png "image.png") --- ### 第2步：选择/创建 Realm 1. 点击左上角下拉菜单（默认是 "Master"） 2. 此时还没有 `padws` realm： - 点击 "Create Realm" - Realm name: `padws` - 点击 "Create" ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/e2ab447c-e403-4c06-a83f-31d318fb8c6f.png "image.png") 3. 确保当前在 `padws` realm 中（左上角显示 "padws"） ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/53cee974-02f8-45b3-958a-23a08a2c1dbe.png "image.png") --- ### 第3步：创建 Client（重点） #### 3.1 General Settings（常规设置）点击左侧菜单 "Clients" → "Create client" ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/1ca95486-e0a9-404a-865e-2e4035db5210.png "image.png") 填写： ``` Client type: OpenID Connect Client ID: padws-client ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/0cd16d89-e502-4b15-9c39-90af562ff104.png "image.png") **直接复制**: ``` padws-client ``` 点击 "Next" --- #### 3.2 Capability config（功能配置）填写： ``` ☑ Client authentication: ON（重要！） ☐ Authorization: OFF ☑ Standard flow: ON（勾选） ☑ Direct access grants: ON（勾选） ☐ Implicit flow: OFF ☐ Service accounts roles: OFF ☐ OAuth 2.0 Device Authorization Grant: OFF ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/3c51586c-a5a1-4cfa-9dda-68fe62bece7c.png "image.png") 点击 "Next" --- #### 3.3 Login settings（登录设置）⭐ 这是最关键的一步 **所有 URL 配置**（直接复制粘贴）： | 字段名 | 填写内容 | 说明 | |--------|----------|------| | **Root URL** | `https://padws.{your-url}.heiyu.space` | 应用根地址 | | **Home URL** | `https://padws.{your-url}.heiyu.space` | 首页地址 | | **Valid redirect URIs** | `https://padws.{your-url}.heiyu.space/*` | ⭐ OAuth 回调地址（重点）| | **Valid post logout redirect URIs** | `https://padws.{your-url}.heiyu.space/*` | 登出后重定向地址 | | **Web origins** | `https://padws.{your-url}.heiyu.space` | CORS 允许的来源 | ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/d144fdf8-ca92-42a1-a095-d2a08a64905c.png "image.png") --- ### 📋 详细填写说明 #### ✅ Root URL ``` https://padws.lanmao168.heiyu.space ``` **作用**: 应用的根 URL，Keycloak 会以此为基础生成其他相对路径。 --- #### ✅ Home URL ``` https://padws.lanmao168.heiyu.space ``` **作用**: 用户登录后的默认跳转页面。 --- #### ⭐ Valid redirect URIs（最重要！） ``` https://padws.lanmao168.heiyu.space/* ``` **详细说明**: - 这是 **OAuth 回调地址** - 登录成功后，Keycloak 会重定向到这个地址 - `/*` 通配符允许所有子路径 - 实际回调地址是：`https://padws.lanmao168.heiyu.space/api/auth/callback` --- #### ✅ Valid post logout redirect URIs ``` https://padws.lanmao168.heiyu.space/* ``` **作用**: 用户登出后允许重定向的地址。 --- #### ✅ Web origins ``` https://padws.lanmao168.heiyu.space ``` **作用**: - CORS（跨域资源共享）配置 - 允许从这个域名发起请求到 Keycloak - **不需要** `/*` 通配符 - **不需要** 尾部斜杠 `/` --- ## 🔑 第4步：获取 Client Secret 1. 保存后，点击 "Credentials" 标签 2. 查看 **Client secret** 字段 3. 点击复制图标（📋）复制 secret 4. **保存这个值**！示例格式： ``` aBcD1234eFgH5678iJkL9012mNoPqRsT ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/3da06b44-9ddb-4e53-829d-a7bdaf0cd92d.png "image.png") --- ## 🎨 第5步：配置 Audience Mapper（必须！）这一步很重要，否则 token 验证会失败。 1. 在 `padws-client` 详情页面，点击 "Client scopes" 标签 ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/b64de790-0881-49c9-898f-348b7c7259b3.png "image.png") 3. 找到 `padws-client-dedicated` 并点击 4. 点击 "Add mapper" → "configure a new mapper" ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/8d3e57c7-6476-4c5e-a34e-1c20e290b5bb.png "image.png") 6. 选择 "Audience" ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/3f446ef8-0cd7-47cf-9f7d-bf2d930f269a.png "image.png") 8. 填写： ``` Name: audience-mapper Included Client Audience: padws-client Add to ID token: ON Add to access token: ON ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/1df67642-2879-429c-a5d4-9a108b4d487e.png "image.png") 6. 点击 "Save" --- ## 👤 第6步：创建测试用户 1. 点击左侧菜单 "Users" 2. 点击 "Add user" ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/9ede704d-e81d-4a1a-9326-fe6f4fa456b6.png "image.png") 4. 填写： ``` Username: testuser Email: test@padws.local Email verified: ✅ 勾选（重要！） First name: Test Last name: User ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/31601771-2edf-4ad3-a8ca-8c30ff27cb49.png "image.png") 4. 点击 "Create" 5. 点击 "Credentials" 标签 ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/7a931817-4f00-43a8-9689-2d9971ef9732.png "image.png") 7. 点击 "Set password" 8. 填写： ``` Password: test123 Password confirmation: test123 Temporary: OFF（关闭临时密码） ``` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/89199b38-b22d-4487-881d-43488a921f06.png "image.png") 8. 点击 "Save" 9. 确认对话框点击 "Save password" --- ## 配置完成后的下一步 1. 复制 Client secret 2. 更新应用环境变量 `OIDC_CLIENT_SECRET` 3. 重启应用 4. 测试登录：`https://padws.lanmao168.heiyu.space/api/auth/login` ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/7c164db2-7c64-44e2-b3eb-4665cdc37b81.png "image.png") ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/6c221655-948a-4bf3-8dbc-e19a2effb649.png "image.png") 登录后即可看到界面了 ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/4bf3a9e5-05a5-4941-a011-b4a4ab0d5020.png "image.png") 也可以重新打开应用，点击 google登录，用刚才的 testuser用户授权即可 ![image.png](https://dl.playground.lazycat.cloud/guidelines/496/20a8afe0-0e37-4e09-910a-8886f6f9e4a7.png "image.png") **享受创作的乐趣吧！** ✨ ---