Web 授权
使用场景
需要用户授权后,才能调用相应的权限接口。例如:视频权限、用户权限等。
背景信息
网站应用抖音登录是基于 OAuth2.0 协议标准构建的授权登录系统,让抖音用户可以使用抖音账号身份安全登录第三方应用或网站,在抖音用户授权登录第三方网站应用后,第三方可以获取到用户的接口调用凭证(access_token),通过 access_token 可以进行抖音开放平台授权关系接口调用,从而实现获取抖音用户基本开放信息和帮助用户实现基础开放功能等。目前提供扫码登录和手机号验证码授权登录两种方式。整体流程为:
1.第三方发起抖音授权登录请求,抖音用户允许授权第三方应用后,抖音会重定向到第三方网站,并且带上授权临时票据 code 参数。
2.通过 code,ClientKey 和 ClientSecret 作为参数,调用 API 换取 access_token。
3.通过 access_token 进行接口调用,获取用户基本数据或帮助用户实现基本操作。
前提条件
1.在使用抖音 OAuth2.0 授权接入之前,您需要成功创建一个应用并通过开放平台审核,详细操作流程见创建移动应用和网站应用。
2.在「抖音开放平台首页」>「右上角控制台」>「我的应用」>「网站应用」> 「应用信息」页面获取 ClientKey 和 ClientSecret。
3.在「抖音开放平台首页」>「右上角控制台」>「我的应用」>「网站应用」 >「授权回调」页面配置授权回调重定向URL
操作步骤
步骤一:获取授权码 code
第三方网站应用申请了授权作用域(Scope)后,可以通过在 PC 端打开以下链接:
参数说明:
参数名称 | 参数类型 | 参数描述 | 参数示例 | 是否必填 |
client_key | string | 应用唯一标识 |
| true |
response_type | string | 默认值 code |
| true |
scope | string | 应用授权作用域,多个授权作用域以英文逗号(,)分隔。 | scope=user_info | true |
optionalScope | string | 应用授权可选作用域,多个授权作用域以英文逗号(,)分隔,每一个授权作用域后需要加上一个是否默认勾选的参数, | optionalScope=friend_relation,1,message,0
| false |
redirect_uri | string | 授权成功后的回调地址,必须以https开头,存在(#)等特殊符号时请对回调地址做urlEncode处理。地址必须对应授权回调页面配置的重定向URL,仅校验(#)前的内容。如不清楚请联系应用申请人。
注意:redirect_uri 中不支持携带自定义 query 参数,详情见下方「常见问题」
|
| true |
state | string | 用于保持请求和回调的状态。可用于CSRF校验或者传递参数。 |
| false |
is_call_app | string | 在手机或PAD环境访问时,是否尝试拉起抖音APP进行授权,默认为否 | is_call_app=1 | false |
请求示例:
用户授权支持 PC 端和客户端,授权形式支持抖音扫描二维码授权和手机号验证码授权两种形式。
成功示例:
用户同意授权后,会重定向到 redirect_uri,并且携带 code 、 state 和 scopes 参数,开发者可从 URL 解析出 code。其中 scopes 为最终用户实际授权的权限。
常见问题:
Q:如何在redirect_uri中携带 query 参数?
A:出于安全考虑,对于新添加的重定向URL,不再支持直接携带参数。
如果需要在redirect_uri里携带参数,可以把参数进行encode后存放在state中,用户完成授权后页面重定向到开发者页面,此时再对 state 参数进行 decode 处理,如
function base64UrlEncode(str) {
return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
function base64UrlDecode(str) {
str = str.replace(/-/g, "+").replace(/_/g, "/");
let state = base64UrlEncode(encodeURIComponent('{"id":1,"b":"测试"}'));
let url = `https://open.douyin.com/platform/oauth/connect?client_key=xxx&state=${state}&response_type=xxx...`;
decodeURIComponent(base64UrlDecode(state));
Q:用户授权时提示“非法重定向链接”。
A:授权回调参数 redirect_uri (#前的内容)应与网站应用配置中的"授权回调域"一致。
步骤二:通过授权码 code 获取 access_token
1.完成授权操作后,在拼接页面内查询授权码(code)。
刷新用户授权的 access_token 或续期:
当 access_token 过期(过期时间 15 天)后,可以通过刷新 access_token 接口的 refresh_token(过期时间 30 天)参数进行刷新,刷新 access_token 或续期不会改变 refresh_token 的有效期。 状态说明:
•若 access_token 已过期,调用接口会报错(error_code=10008或 2190008),refresh_token 后会获取一个新的 access_token 以及新的超时时间。
•若 access_token 未过期,refresh_token 不会改变原来的 access_token,但超时时间会更新,相当于续期。
•若 refresh_token 过期,获取 access_token 会报错(error_code=10010),此时需要重新走用户授权流程。
•前提: client_key 需要具备 renew_refresh_token 权限。
•通过旧的 refresh_token 获取新的 refresh_token,调用后旧 refresh_token 会失效,新 refresh_token 有 30 天有效期。最多只能获取 5 次新的 refresh_token,5 次过后需要用户重新授权。
步骤三:通过 access_token 调用接口
通过 access_token 调用相应的接口前,需确认已满足以下条件:
2.抖音用户已授权给第三方应用账号相应的接口作用域(Scope)。例如申请了 user_info,可调用获取用户公开信息获得用户公开信息。