快速开始
在 OAuth 伙伴控制台 提交产品用途、隐私政策和服务条款。审核通过后创建应用。Confidential 应用的所有者可在控制台查看和轮换 Client Secret,并应将密钥保存在服务端。安装在用户设备上的应用使用 Public Client。
- 注册应用选择客户端类型,登记完整 Redirect URI 和权限范围。
- 生成 PKCE随机生成 code_verifier,并发送其 S256 code_challenge。
- 选择发起方式iOS/iPadOS 优先唤起 VmTalk;macOS/tvOS/网站显示二维码;浏览器场景使用标准授权页。
- 确认并交换用户确认后兑换一次性授权码,或在扫码发起端轮询 Token。
- 调用 UserInfo使用短期 Bearer access token,按已授权 scope 读取字段。
服务发现
客户端应优先读取这个标准 OIDC Discovery 地址,不要把端点路径写死在业务代码里:
https://vmtalk.us/.well-known/openid-configuration ↗
该地址返回标准 JSON,响应头为 application/json; charset=utf-8,包含标准端点以及 VmTalk 原生 App-to-App 授权端点、设备二维码端点和 PKCE 能力声明。可短期缓存元数据,并检查 issuer 与已配置的 https://vmtalk.us 一致。
curl -fsS https://vmtalk.us/.well-known/openid-configuration | jq .应用注册
控制台支持两种客户端:Confidential 用于能安全保存密钥的服务端应用;Public / PKCE 用于 iOS、iPadOS、macOS、tvOS、Android 和其他桌面应用。所有应用直接进入生产环境,原生应用不应把 Client Secret 写入包内。
| 字段 | 要求 |
|---|---|
| 环境 | 统一为生产环境;创建后直接使用 live Client ID。 |
| Confidential Redirect URI | 必须是 HTTPS,并且与登记值完全一致。 |
| Public Redirect URI | 可使用 HTTPS、Universal Link 或已登记的自定义 Scheme;禁止片段、用户信息和通配符。 |
| 原生应用信息 | 回调所属域名、自定义 Scheme、Bundle ID 或包名在合作方 App 与其关联站点配置。VmTalk 控制台只登记完整回调 URI,无须填写 Bundle ID 或 Team ID。 |
| 应用 Logo | 可选。可在应用资料中填写 HTTPS 图片地址。 |
| 权限范围 | 只能选择实际需要的 openid、profile、email、vmtalk_basic_profile。 |
iOS / iPadOS App-to-App 联合登录
当合作应用和 VmTalk 都安装在同一台 iPhone 或 iPad 上时,推荐由合作应用发起一次性授权请求,优先唤起 VmTalk 原生确认页。该流程不会把密码、Client Secret 或 Token 放进 URL。
vmtalk:// Scheme → ASWebAuthenticationSession 网页降级。VmTalk 未安装或系统无法打开链接时提供网页授权。用户拒绝或取消后结束本次尝试,由用户主动重新发起。授权边界VmTalk 只负责展示合作方名称、应用名称和 scope,并由用户明确允许或拒绝;合作方仍须用 PKCE 兑换 code。回调边界回调只携带一次性 authorization code 和原始 state,Token 只能通过 HTTPS Token 端点获取。1. 合作应用生成 PKCE 和授权请求
let verifier = randomBase64URL(32)
let challenge = sha256Base64URL(verifier)
let state = randomBase64URL(24)
let nonce = randomBase64URL(24)
// redirect_uri 必须提前登记,例如:
// com.example.app:/oauth/callback
let launchURL = URL(string: "vmtalk://oauth/authorize?" +
query([
"client_id": clientID,
"redirect_uri": redirectURI,
"response_type": "code",
"scope": "openid profile email",
"state": state,
"nonce": nonce,
"code_challenge": challenge,
"code_challenge_method": "S256"
]))!合作应用保存 state、nonce 和 code_verifier 到当前授权会话,然后尝试打开上面的 App URL。不要把 code_verifier 写进 URL。
2. VmTalk 原生确认
VmTalk 收到 URL 后,应从服务端读取并展示授权详情。下面的原生授权接口只供 VmTalk 第一方 App 在用户已登录后调用,合作方不能匿名调用它来绕过确认页。合作方只负责生成 PKCE 请求并等待自己的回调:
POST https://vmtalk.us/VmTalkAPI/oauth/native_authorize.php
Authorization: Bearer VMTALK_SESSION_TOKEN
Content-Type: application/json
{
"action": "prepare",
"client_id": "YOUR_CLIENT_ID",
"redirect_uri": "com.example.app:/oauth/callback",
"response_type": "code",
"scope": "openid profile email",
"state": "RANDOM_STATE",
"nonce": "RANDOM_NONCE",
"code_challenge": "BASE64URL_SHA256_CODE_VERIFIER",
"code_challenge_method": "S256"
}prepare 返回 app_name、partner_name、scope_labels 和 needs_consent。如果需要同意,VmTalk 必须显示确认页面;如果用户拒绝,使用 action=deny;如果用户同意,使用 action=approve。VmTalk App 通过自己的已登录会话调用该接口,服务端会再次校验合作方状态、Redirect URI、PKCE 和用户状态。
3. 回调并兑换 Token
// VmTalk 返回给合作应用的 redirect_url:
com.example.app:/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
// 合作应用先校验 state,再兑换 code
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/token.php \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode client_id=YOUR_CLIENT_ID \
--data-urlencode grant_type=authorization_code \
--data-urlencode code=AUTHORIZATION_CODE \
--data-urlencode redirect_uri=com.example.app:/oauth/callback \
--data-urlencode code_verifier=ORIGINAL_RANDOM_CODE_VERIFIER合作应用收到回调后必须先验证 state,再调用 Token 端点。code 只能兑换一次,成功后立即清理本地授权临时状态。
4. 网页降级
App 未安装或唤起失败时,合作应用使用标准 /oauth/authorize.php,iOS/iPadOS 推荐通过 ASWebAuthenticationSession 打开,而不是直接把登录页长期留在 Safari。
vmtalk Scheme 和 applinks:vmtalk.us;合作应用在自己的工程和域名配置回调,并在 VmTalk 控制台登记完整 Redirect URI。使用 canOpenURL 前,把 vmtalk 放入合作应用的 LSApplicationQueriesSchemes。兼容性Universal Link 是首选,Scheme 仅作为回退;Android 可用经过验证的 App Link 或 Custom Tabs,macOS 可使用 Scheme 或二维码,tvOS 使用设备二维码。跨设备二维码登录(网站、macOS、tvOS 等发起端)
需要在电视、另一台电脑或网站上登录时,使用标准 Device Authorization Grant。发起设备先创建一次性 device session,只把 verification_uri_complete 渲染成二维码;二维码不包含 device_code、Client Secret、Access Token 或密码。
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/device_authorization.php \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode scope='openid profile email'响应包含 device_code(只保留在发起设备)、user_code、verification_uri_complete、expires_in=300 和 interval=5。二维码应同时显示 8 位确认码,提示用户在 VmTalk 中核对。
verification_uri_complete 交给系统或现有 QR 组件生成二维码;页面同时展示应用名称、伙伴名称、确认码、倒计时和“等待 VmTalk 确认”状态。不要把 device_code、Client Secret 或 Token 放入二维码,也不要把二维码内容写入日志。平台实现macOS/tvOS 可使用系统 Core Image 的 CIQRCodeGenerator;网站可使用现有 QR 组件或平台原生能力。VmTalk 扫码后会打开第一方 /device.php?user_code=… 确认页,用户明确同意后发起设备才可轮询换取 Token。curl -X POST https://vmtalk.us/VmTalkAPI/oauth/token.php \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=urn:ietf:params:oauth:grant-type:device_code \
--data-urlencode device_code=DEVICE_CODE{
"device_code": "…",
"user_code": "ABCD-EFGH",
"verification_uri": "https://vmtalk.us/device.php",
"verification_uri_complete": "https://vmtalk.us/device.php?user_code=ABCD-EFGH",
"expires_in": 300,
"interval": 5
}用户确认后,device_code 只可消费一次;成功后返回标准 Access Token、Refresh Token 和 OIDC ID Token。二维码和确认页均禁止缓存,生产客户端应在退出、撤销授权或账号异常时清理本地凭证。
tvOS 合作方接入:显示二维码,使用 iOS VmTalk 扫码
tvOS 通常没有方便的键盘输入,因此推荐使用 Device Authorization Grant:Apple TV 应用负责显示二维码并等待结果,用户使用已登录的 iPhone/iPad VmTalk 扫描二维码并确认。tvOS 应注册为 Public Client,不能把 Client Secret、Access Token 或密码写进应用包。
verification_uri_complete;真正的 device_code 只保留在 tvOS 内存中,并通过 HTTPS 轮询 Token 端点。用户体验tvOS 同时显示合作方名称、应用名称、8 位确认码、剩余时间和“等待 iPhone/iPad 确认”状态。1. tvOS 创建登录会话
Public Client 只发送已登记的 client_id 和 scope,不发送 Client Secret:
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/device_authorization.php \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode client_id=YOUR_TVOS_PUBLIC_CLIENT_ID \
--data-urlencode scope='openid profile email'保存响应中的 device_code、expires_in 和 interval;将 verification_uri_complete 生成二维码。不要把 device_code 放进二维码,也不要写入遥测、日志或截图。
2. iOS VmTalk 扫码确认
- 扫描二维码iOS 扫码器识别第一方
https://vmtalk.us/device.php?user_code=…地址。 - 显示授权详情VmTalk 从服务端读取 tvOS 应用名称、合作方名称、权限和确认码。
- 明确同意用户点击“确认并登录”或“拒绝”,不会静默授权。
- 回到 Apple TVtvOS 轮询成功后进入已登录状态;拒绝或过期时提示重新生成二维码。
3. tvOS 轮询 Token
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/token.php \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode client_id=YOUR_TVOS_PUBLIC_CLIENT_ID \
--data-urlencode grant_type=urn:ietf:params:oauth:grant-type:device_code \
--data-urlencode device_code=DEVICE_CODE首次按响应中的 interval(当前为 5 秒)轮询;收到 authorization_pending 继续等待,收到 slow_down 将间隔增加 5 秒,收到 access_denied 或 expired_token 停止轮询并让用户重新扫码。成功响应包含 Access Token、Refresh Token 和 ID Token。
macOS App-to-App 与二维码登录
macOS 合作应用可以优先尝试打开 VmTalk 原生授权页;如果 VmTalk 未安装、Universal Link 未命中,可继续提供网页授权。用户取消时终止本次授权。需要在另一台设备上操作时,使用 Device QR Login。
https://vmtalk.us/app/oauth/authorize Universal Link → vmtalk://oauth/authorize Scheme → ASWebAuthenticationSession / 浏览器。macOS 配置在应用注册中登记完整 Redirect URI,并在你的 App 配置回调;通过 NSWorkspace.shared.open 发起唤起,不要自行拼接未编码的查询参数。跨设备场景使用 Device Authorization Grant 生成二维码;二维码只包含 verification_uri_complete,macOS 轮询 Token 端点,VmTalk iPhone/iPad 负责确认。// macOS:优先唤起 VmTalk,失败后进入网页授权
let nativeURL = URL(string: "vmtalk://oauth/authorize?" + encodedQuery)!
if NSWorkspace.shared.open(nativeURL) == false {
// 使用 ASWebAuthenticationSession 打开标准 HTTPS authorize 端点
startWebFallback()
}macOS 回调处理必须校验 state,再使用原始 code_verifier 兑换授权码。取消授权时清理临时 PKCE 状态。退出登录或收到授权失效结果时,再清除本地 Token。
Android App Links 与二维码登录
Android 原生应用使用 Public Client + Authorization Code + PKCE。推荐使用已登记的 HTTPS App Link,Custom Scheme 仅作为兼容回退;不要在 APK/AAB 内保存 Client Secret。
// Android:生成 code_verifier / S256 challenge 后构建编码后的 URI
val authorize = Uri.parse("https://vmtalk.us/app/oauth/authorize").buildUpon()
.appendQueryParameter("client_id", clientId)
.appendQueryParameter("redirect_uri", redirectUri)
.appendQueryParameter("response_type", "code")
.appendQueryParameter("scope", "openid profile email")
.appendQueryParameter("state", state)
.appendQueryParameter("nonce", nonce)
.appendQueryParameter("code_challenge", challenge)
.appendQueryParameter("code_challenge_method", "S256")
.build()
startActivity(Intent(Intent.ACTION_VIEW, authorize))https host/path;如需 Scheme 回退,请在 AndroidManifest 配置接收器,并把完整回调 URI 登记到控制台。网页降级Android 推荐使用 Chrome Custom Tabs;如果应用未安装或系统没有匹配的 App Link,继续走标准网页授权,不要显示死链。回调安全回调收到 code 后先校验 state,再在 HTTPS Token 端点兑换;不要把 Token 放到 Intent extras、剪贴板或日志。Android 应用需要展示跨设备登录二维码时,可实现 Device QR Login:发起设备展示确认码并按间隔轮询,用户在另一台设备上扫码确认。
网站与服务端接入
有后端的 Web 应用建议注册为 Confidential Client,使用 HTTPS Redirect URI 和 HTTP Basic 认证兑换 Token。有静态前端的项目也可用轻量后端完成换票,并为前端建立本地会话;不要把 Client Secret 放入 JavaScript。
// 服务端跳转
https://vmtalk.us/VmTalkAPI/oauth/authorize.php?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&response_type=code&scope=openid%20profile%20email&state=RANDOM_STATE&nonce=RANDOM_NONCE&code_challenge=BASE64URL_SHA256_CODE_VERIFIER&code_challenge_method=S256服务端回调只接受登记的完整 URI,校验 state 后立即兑换 code,并用 HttpOnly、Secure、SameSite Cookie 保存本地会话。不要把 VmTalk Access Token 暴露给浏览器脚本。
端点速查
| 用途 | 端点 | 客户端 |
|---|---|---|
| 标准授权 | GET /VmTalkAPI/oauth/authorize.php | 网站、macOS、Android、网页降级 |
| Token 交换 / 刷新 | POST /VmTalkAPI/oauth/token.php | 所有客户端 |
| UserInfo | GET /VmTalkAPI/oauth/userinfo.php | 已获得 Access Token 的客户端 |
| 撤销 Token | POST /VmTalkAPI/oauth/revoke.php | 服务端或客户端退出流程 |
| 设备会话 | POST /VmTalkAPI/oauth/device_authorization.php | tvOS、macOS、网站、跨设备登录 |
| 原生确认 | POST /VmTalkAPI/oauth/native_authorize.php | 仅 VmTalk 第一方 App,需已登录 |
所有 API 使用 HTTPS。生产环境不提供沙箱开关;应用审核、停用、撤销和安全策略由 VmTalk 伙伴控制台统一管理。
交换 Access Token
授权码只能使用一次,有效期为 60 秒。Token 端点只接受 POST;Confidential 客户端推荐使用 HTTP Basic,Public 客户端不发送 Secret。
Confidential Client
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/token.php \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=authorization_code \
--data-urlencode code=AUTHORIZATION_CODE \
--data-urlencode redirect_uri=https://example.com/oauth/callback \
--data-urlencode code_verifier=ORIGINAL_RANDOM_CODE_VERIFIERPublic Client
curl -fsS https://vmtalk.us/VmTalkAPI/oauth/token.php \
--data-urlencode client_id=YOUR_PUBLIC_CLIENT_ID \
--data-urlencode grant_type=authorization_code \
--data-urlencode code=AUTHORIZATION_CODE \
--data-urlencode redirect_uri=com.example.app:/oauth/callback \
--data-urlencode code_verifier=ORIGINAL_RANDOM_CODE_VERIFIER成功响应包含 access_token、refresh_token、token_type、expires_in、refresh_expires_in、scope 和 OIDC id_token。当前 Access Token 有效期为 600 秒、Refresh Token 为 30 天。以每次响应中的有效期为准。
刷新时使用同一个客户端身份和当前有效的 refresh_token。收到新 Token 后原子替换旧值,并对同一会话合并并发刷新请求。再次使用已轮换的 Refresh Token 可能使该用户在此应用下的令牌全部失效;收到 invalid_grant 时重新发起登录。
以下是 Confidential 刷新示例。Public Client 将 -u 一行替换为 --data-urlencode client_id=YOUR_PUBLIC_CLIENT_ID。创建二维码、轮询和撤销 Token 也使用同一客户端认证方式。
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/token.php \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode grant_type=refresh_token \
--data-urlencode refresh_token=CURRENT_REFRESH_TOKEN读取用户资料
UserInfo 使用 Bearer Token,通过已授权的 scope 决定返回字段。用户撤销同意、账号停用或客户端撤销后,Token 会失效。
curl https://vmtalk.us/VmTalkAPI/oauth/userinfo.php \
-H 'Authorization: Bearer ACCESS_TOKEN'| scope | 字段 |
|---|---|
| openid | sub |
| profile | nickname、picture、avatar_url、gender、bio |
| email、email_verified | |
| vmtalk_basic_profile | account_status、updated_at |
本地用户以 (iss, sub) 关联。UserInfo 的 sub 必须与已验证 ID Token 一致。邮箱可能变化或未验证,请勿仅凭邮箱自动合并已有账号。
验证 ID Token
用成熟的 OIDC 库,从 Discovery 的 jwks_uri 取得公钥并按 kid 选键。验证 RS256 签名、iss=https://vmtalk.us、aud 等于本应用 Client ID、exp、iat 和 sub。新 kid 出现时重新获取一次 JWKS。
授权码登录请生成一次性 nonce,并校验它与 ID Token 中的值完全一致。设备授权和刷新请求无 nonce 输入,不应拿最初的 nonce 校验这些响应。Access Token 是不透明的 Bearer 字符串,用来调用 UserInfo。
撤销 Token 与授权
客户端可以撤销自己的 Access Token 或 Refresh Token。用户也可以在 VmTalk 的授权管理中撤销整个应用的同意记录。
curl -X POST https://vmtalk.us/VmTalkAPI/oauth/revoke.php \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode token=TOKEN_TO_REVOKE \
--data-urlencode token_type_hint=refresh_token撤销端点成功时返回 HTTP 200,响应体为空。它一次撤销一个 Token。需要同时撤销 Access Token 与 Refresh Token 时分别调用。用户可以在 VmTalk 的第三方应用授权管理中撤销整个授权。
权限与数据最小化
所有申请都必须包含 openid。只申请你的功能真正需要的范围,并在自己的隐私政策中解释用途。
错误处理
JSON 错误包含 error、error_description 和 request_id。向支持团队反馈时请提供 request_id,不要提供密码、Client Secret 或 Token。
{
"request_id": "...",
"error": "invalid_grant",
"error_description": "authorization code is expired or already used"
}| 错误 | 常见原因 |
|---|---|
| invalid_request | 缺少参数、方法不正确或 PKCE 参数不完整。 |
| invalid_client | 核对 Client ID、应用与伙伴状态,以及 Confidential 密钥是否已轮换。接口通常返回 401。 |
| unauthorized_client | 授权请求与应用状态或客户端类型不符。 |
| invalid_grant | 授权码过期/重放、Redirect URI 不匹配、PKCE 校验失败或 device_code 无效。 |
| authorization_pending | 用户尚未在 VmTalk 中确认设备登录;按 interval 继续轮询。 |
| slow_down | 轮询频率过高;等待更长时间后再请求。 |
| access_denied | 用户拒绝授权。结束本次流程,并提供重新发起入口。 |
| expired_token | device session 已过期或已经消费,必须重新生成二维码。 |
| invalid_token | Access Token 过期、撤销或用户同意已撤销。 |
| invalid_scope | 请求了应用未获批准的 scope。 |
管理应用与上线验收
- 调整配置
- 变更回调时先登记新地址,再发布合作方更新。等待旧版本迁移后再删除旧地址。按用途选择最小 scope。
- 轮换密钥
- 轮换后旧 Secret 立即失效。预先准备服务端配置发布,将新值写入密钥存储,并验证换票和刷新。
- 停用与删除
- 停用会撤销当前 Token,重新启用后用户需要重新登录。删除会移除应用、凭据、授权和关联 Token,操作不可恢复。
- 发布前实测
- 使用自有测试账号在生产环境验证成功回调、用户拒绝、取消、授权过期、刷新轮换和授权撤销。扫码流程额外验证慢轮询、过期与主动退出。
上线前安全清单
- 每次授权都生成不可预测的 state;使用 OIDC 时同时生成 nonce。
- 使用系统安全存储保存 Token;不要写入日志、URL、截图或分析事件。
- 只接受精确匹配的 Redirect URI;不要使用通配符或开放重定向。
- 服务端校验 id_token 的签名、issuer、audience、过期时间和 nonce。
- Access Token 只通过 HTTPS 的 Authorization Bearer 头发送。
- 二维码只编码 verification_uri_complete;不要编码 device_code、Secret 或 Token。
- 设备端按 interval 轮询,遇到 slow_down 必须退避;不要并发轮询。
- 用户注销、撤销授权或修改安全状态后,立即清理本地 Token。
