VKontakte

RootAuth 支持接入 VKontakte（VK）登录。开启后，用户可以在登录/注册页选择「VK」，通过 VK 授权完成登录或注册。

路径：登录 RootAuth 控制台 → 进入目标应用 → 点击顶部导航栏的「配置」→「应用管理 - 认证配置」→ 选择「提供方」。

 

1. 开始前准备

配置 VK 登录前，请先完成以下准备：

• 拥有一个 VK 个人账号。
• 已在 VK 开发者平台创建 Website 类型的应用。
• 已获取 VK 应用的 应用ID（Application ID）和 安全密钥（Secure Key）。
• 已准备好应用域名，用于配置 OAuth 回调地址。

VK 会校验 OAuth 跳转 URI。请将 RootAuth 后台展示的「回调地址」配置到 VK 应用的 OAuth 客户端授权设置中，并确保两处地址完全一致。

 

2. 在 RootAuth 后台开启 VK

在「提供方」列表中找到「VKontakte (VK)」，点击右侧「启用」。

打开配置弹窗后，开启 VK 登录开关，并填写以下信息：

配置项	说明
应用 ID	VK 应用的 Application ID（App ID），必填。
安全密钥	VK 应用的 Secure Key，必填。
回调地址	系统自动生成，只读且可复制。请将此地址配置到 VK OAuth 客户端授权设置中。
域名	当前应用使用的域名，可复制后用于 VK 应用配置。
授权范围	basic_profile 为必选项，不可取消，用于获取姓名、性别、用户 ID、头像等身份信息。 email 为可选项，默认勾选，用于获取用户邮箱地址。如需获取，请务必勾选此项，并在 VK 应用中开启邮箱权限，否则无法返回用户邮箱信息。
登录模式	固定为「可用于登录注册」。
账号绑定	默认开启。开启后可选择「自动关联」或「强制关联」；关闭后不进行账号关联。

填写完成后，点击「保存」。保存成功后，VK 会显示为「已启用」，右侧按钮变为「管理」。后续如需修改配置，可点击「管理」重新编辑。

 

3. 账号绑定设置

VK 以 VK 用户 ID 作为平台内的唯一身份标识。若在授权时获取到邮箱，邮箱会作为辅助匹配标识。

3.1 未获取邮箱时

当未勾选 email 授权范围，或用户授权后未返回邮箱时，系统只使用 VK 用户 ID 匹配账号：

• 已存在相同 VK 用户 ID：直接登录对应账号。
• 不存在相同 VK 用户 ID：创建新账号并绑定该 VK 身份。

此场景不会出现账号关联或身份验证弹窗。

 

3.2 获取邮箱时

当 VK 返回的邮箱与系统已有账号匹配时，系统会根据「账号绑定」设置执行以下逻辑：

设置	处理逻辑
自动关联	自动将 VK 身份关联到同邮箱的已有账号并登录；若未匹配到已有账号，则创建新账号。整个过程无需用户操作。
强制关联	仅在邮箱匹配时显示确认和邮箱身份验证流程。用户验证成功后，VK 身份会关联到已有账号并完成登录；用户取消或未通过验证时，本次 VK 登录/注册不成功。若未匹配到已有账号，则创建新账号。
关闭账号绑定	不自动关联同邮箱账号。即使 VK 邮箱与系统已有账号邮箱相同，也会作为独立账号处理。

选择「强制关联」时，还可以配置关联后的回调地址。系统默认提供回调地址；如使用自定义地址，请确保该页面能够继续完成账号关联和身份验证流程。

 

4. 用户如何使用 VK 登录

开启后，登录/注册页会展示 VK 图标按钮。用户点击「VK」后，会跳转到 VK 授权页面。

用户确认授权后，RootAuth 会自动完成以下操作：

1. 获取 VK 返回的用户资料及已授权的邮箱信息。
2. 使用 VK 用户 ID 查找已有 VK 身份绑定。
3. 根据邮箱获取情况和账号绑定设置，判断是否关联已有账号。
4. 登录已有账号，或创建新账号并绑定 VK 身份。

 

5. 绑定与解绑 VK 账号

除登录/注册流程外，应用也可以通过 API 让已登录用户主动绑定或解绑 VK 账号：

• 绑定 VK：应用前端完成 VK OAuth 授权后，向 RootAuth 提交授权得到的 code 或 access_token。RootAuth 验证通过后，将 VK 用户 ID 和可用邮箱绑定到当前账号。
• 解绑 VK：已登录用户调用解绑接口后，RootAuth 清除该账号的 VK 绑定记录。

RootAuth 控制台不提供管理员手动绑定或解绑 VK 的操作入口。应用应通过 API 实现用户主动绑定和解绑。

 

6. 查看用户的 VK 认证方式

用户通过 VK 登录、注册或绑定 VK 后，可在「用户管理」中打开对应用户详情，在「认证方式」区域查看 VK 记录。

字段	说明
认证方式	VK 或 VKontakte，并显示 VK 图标。
标识	优先显示 VK 返回的邮箱；未获取邮箱时显示 VK 用户 ID。
最后使用时间	最近一次使用 VK 登录的时间。

应用通过 API 解绑 VK 后，该用户详情中的 VK 认证方式会被移除。

 

7. 日志与标识展示

RootAuth 会在「审计日志」→「用户行为日志」中记录 VK相关操作。

事件类型	说明
VK注册	用户通过 VK登录创建新账号。
VK登录	用户通过 VK登录已有账号。
绑定 VK	已登录用户通过应用绑定 VK。
解绑 VK号	已登录用户通过应用解绑 VK。

8. 接入方式

VK 登录支持两种接入方式：

接入方式	说明
Hosted 接入	使用 RootAuth 托管的登录/注册页面。开启 VK 后，页面会自动展示 VK 登录按钮。
API 接入	应用自行实现 VK 登录入口，并通过 RootAuth API 完成登录、绑定或解绑。

具体的接入指引，请参考开发集成文档。

 

9. 关闭 VK 登录

如需关闭 VK 登录，进入 VK 管理弹窗，关闭开关并保存。

关闭后：

• 登录/注册页不再展示 VK 登录按钮。
• 已保存的 VK 应用凭证会保留。
• 已有用户的 VK 绑定记录不会被删除。
• 后续重新开启时，可继续使用原有配置。

如果用户看到缓存中的旧登录页并继续点击 VK 登录，系统会拦截请求并提示登录失败。用户刷新页面后，即可获取最新登录配置。