目录概述... 2 基本流程... 2 接口文档... 3 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth code... 3 使用 auth code 换取 access token... 4 使用 refresh_token 换取 acc

Size: px

Start display at page:

Download "目录概述... 2 基本流程... 2 接口文档... 3 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth code... 3 使用 auth code 换取 access token... 4 使用 refresh_token 换取 acc"

燕慈郁
5 years ago
Views:

1 目录概述... 2 基本流程... 2 接口文档... 3 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth... 3 使用 auth 换取 access token... 4 使用 refresh_token 换取 access_ token... 6 使用 acess_token 调用 dr-api... 7

2 概述百度凤巢商业开放平台允许第三方软件商使用凤巢平台上的用户广告数据和基础服务来开发各种工具和软件它采用国际标准 OAuth2.0, 此标准提供一种让第三方客户端访问受限资源的方法, 只需要资源拥有者同意, 就可以在不暴露用户名密码的条件下让第三方客户端使用受限资源目前一期就使用者都是网站的情况, 只先开放出 grant 型授权, 后续客户端形式更多时, 开放更多形式的授权基本流程以上图片来自 ietf-oauth-v2 草稿, 等待流程成为正式 RFC ( 注 :Client 指第三方应用,Resource Owner 指用户, 第一步虽然画出是应用向用户请求授权, 实际上用户是通过百度开放平台授权服务器作为中介完成授权的,Authorization Server 是我们的授权服务器, Resource Server 是现在的凤巢 dr-api 服务器 ) 1. A-B: 用户从百度开放平台工具目录页中点击工具图标或者从第三方网站点击链接跳转到百度开放平台授权 URI(auth URI), 并提供必要的参数此 URI 要求用户登录百度 www2, 未登陆的会打去登陆页面登陆后跳回登录后如果尚未授权, 会出现授权页面提示用户进行授权, 用户点击授权且一切正常, 即以 302 返回 auth 到应用 callback URI 如果用户是已经授权过此应用且一切正常, 则不出现页面, 直接以 302 返回 auth 到应用 callback URI

3 2. C-D:callback URI 的 action 中, 在后端发起一个 https 请求, 使用获得到的去百度开放平台授权服务另一个 URI(token URI) 换取 token 一切正常的话, 百度授权服务在返回的内容中会提供 access token( 短期有效 ),refresh token( 长期有效 ),identifier( 带操作人上下文去重 ), username( 被操作人用户名 ) 3. E-F: 后续第三方软件使用 access token 调用 dr-api 来使用凤巢平台的数据和服务, 具体 soap 头的形式后面会给出, 也会提供升级过的 dr-api SDK 支持这种调用接口文档接口说明用来给用户授权, 目前支持 grant 用来请求 access token 的接口, 目前可支持用 auth 以及 refresh token 来换 access token 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth 接口 url: 安全特性 :https 协议, 通过用户浏览器请求, 且此 url 防 ddos, 有可能封禁某用户或者某 ip, 所以请注意请求的频率例如 : e&redirect_uri=...&state=xyz 详细 GET 请求参数说明 : query 参数名参数值说明必选 client_id 一个唯一标示客户端比如 autobid38237, 目是的字符串前暂由百度分配 response_type 目前只能为目前只支持, 后是续可能扩展支持更多 redirect_uri utf8 的 urlend 的必须和该产品注册的是回调页面, 用于接收错误信息或者 auth callback uri 一致, 可以带 query string, 但 callback URI 使用的参数名请不要和本文档后面说明的返回参数名冲突 state 一个随意串用来将这个过程串联起来, 如使用, 则后续 oauth 过程请求和返回都会带上此内容

4 返回 : 返回的形式是一个 http 302, 会重定向到上面 redirect_uri 指定 URI 上返回的参数详细说明 : query 参数名参数值说明必选如果成功, 一个临比如仅成功时必选时有效的可换取 access token 的字符串 SplxlOBeZQQYbYS6WxSbIA, 只有成功了才返回这个参数 state 刚才传递过来的随用来串联整个过程意串 error 如果不成功, 由这具体列表请看下面仅失败时必选个参数告知第三方错误信息 error_description 具体错误描述可选的 error_uri 一个描述错误的 uri 可选的, 目前不一定提供, 如果提供了, 第三方可以考虑提供此链接给用户查看错误字符串详细说明 error 说明 invalid_request 参数缺失, 参数值非法, 参数重复出现, 格式有问题 unauthorized_client 这个客户端没有被开放平台许可, 例如没有获取到 client_id,client_secret access_denied 用户拒绝授权 unsupported_response_type 使用了不支持的 response_type 参数, 例如目前只支持, 其他都会返回此错误 invalid_scope 目前没啥用, 用来表示请求授权的范围不合法, 以后可能会用, 准备好提示吧 server_error 处理请求时, 服务器内部出现了异常 temporarily_unavailable 被系统限制, 例如现在并发太大, 开放平台不予受理了, 等扩容或者恶意并发降下来才能恢复 error_redirect_uri 错误的 callback url access_prisoned 请求被封禁, 因为不合理的请求方式或者恶意枚举尝试破解各种数据被封禁使用 auth 换取 access token 接口 url: 安全特性 :https, 后台请求, 需要带密码过来取,auth 临时有效也有防 ddos 的攻击

5 例如 : autobid38237&client_secret=kdsf023sdf34&grant_type=authorization_&=.&r edirect_uri=.&state=xyz 后台发 http 请求参数 : query 参数名参数值说明必选 client_id 一个唯一标示产品的比如 autobid38237 是字符串 client_secret 线下发给第三方的 client_secret 一个保密的密码性质的串, 明文是 grant_type 必须设定为也可以是 authorization_ 为 refresh_token, 后面讲到刚才分配给的 auth 授权后跳回来用来换是 access token 的 redirect_uri utf8 的 urlend 的和刚才请求一致的跳是跳转 uri 转 uri state 一个随意串用来将这个过程串联起来, 如果使用, 则后续请求和返回都会带上此内容返回 : 如果成功, 返回的是一段 json HTTP/ OK Content-Type: application/json;charset=utf-8 Cache-Control: no-store Pragma: no-cache { error :, "access_token":"2yotnfzfejr1zcsicmwpaa", "expires_in":3600, "refresh_token":"tgzv3jokf0xg5qx2tlkwia", identifier : 用户标识 ( 带操作人上下文 ) username : ( 后续换成调用 api) "state":"xxxxxx" } state 同上, 请求带过来的就会带回去 expires_in 秒, 表示 access token 目前的过期时间 identifier: 软件商可采用此标识来区分不同用户请求 username: 被操作人用户名, 可能有常数个 identifier 对应一个被操作人用户名, 软件商根据需要可进行一定的数据副本数维持工作 refresh_token 永久有效, 除非用户解除授权, 百度根据安全策略需要解除授权 access_token 暂时有效, 如果失效, 则可以使用 refresh token 换取新的 access token

6 如果失败, 则可能返回 http500, 这个直接定义为服务器错误也可能返回 200, 但是 json 中带有 error 字段, 反应错误信息 : error 说明 unauthorized_client 这个客户端没有被开放平台许可, 例如没有获取到 client_id,client_secret invalid_request 参数缺失, 参数值非法, 参数重复出现, 格式有问题 invalid_password client_secret 错误 invalid_auth_ 已经过期或者已经不符合安全策略, 例如只能获取一次, 但已经被别人窃取 unsupported_grant_type 非法的 grant_type, 目前只能填写 authorization_ 和 refresh_token 两种 server_error 处理请求时, 服务器内部出现了异常 error_redirect_uri redirect_uri 和前面流程不符 temporarily_unavailable 被系统限制, 例如现在并发太大, 开放平台不予受理了, 等扩容或者恶意并发降下来才能恢复使用 refresh_token 换取 access_ token 接口 url: 还是这个安全特性 : 同上例如 : autobid38237&client_secret=kdsf023sdf34&grant_type=refresh_token&token= &state=x yz 详细参数列表 : query 参数名参数值说明必选 client_id 一个唯一标示产品的比如 autobid38237 是字符串 client_secret 线下发给第三方的 client_secret 一个保密的密码性质的串, 明文是 grant_type 必须设定为因为是用是 refresh_token refresh_token 来换, 所以此处必须填 refresh_token token refresh_token 内容无是 redirect_uri utf8 的 urlend 的跳转 uri 和刚才请求一致的跳转 uri, 这里可省

7 state 一个随意串用来将这个过程串联起来, 如果使用, 则后续请求和返回都会带上此内容返回 : 如果成功, 返回的是一段 json HTTP/ OK Content-Type: application/json;charset=utf-8 Cache-Control: no-store Pragma: no-cache { error :, "access_token":"2yotnfzfejr1zcsicmwpaa", "expires_in":3600, state : xyz } state 同上, 请求带过来的就会带回去 expires_in 秒, 表示 access token 目前的过期时间如果失败, 则可能返回 http500, 这个直接定义为服务器错误也可能返回 200, 但是 json 中带有 error 字段, 除了以上错误之外, 增加 : invalid_refresh_token 表示该 refresh_token 已经被废除, 有可能是用户取消了, 有可能是百度后台取消了, 需要重新跳转申请用户授权 invalid_auth_stat 操作人已经不能操作被操作人, 授权已经没有了等 auth_relation_deleted 用户取消了对工具的授权使用 acess_token 调用 dr-api 具体详情可参考会提供升级的 sdk 支持 access_token 的 soap 头, 其格式如下 : <soapenv:envelope xmlns:soapenv=" xmlns:v2=" xmlns:v21=" <soapenv:header> <v2:authheader> <v2:token> your old token</v2:token> <v2:accesstoken> your access token</v2:accesstoken> </v2:authheader> </soapenv:header> <soapenv:body> <v21:getcampaignidrequest/> </soapenv:body> </soapenv:envelope>

8 API 的错误码 : 说明 temporarily_unavailable invalid_access_token access_token_expired invalid_authorize_stat access_prisoned invalid_ip 注 :invalid_ip(you are not allowed to use the accesstoken with the ip you provided), 一个开发者可以在开放平台服务商入口注册 1~10 个安全 ip 点地址

获取 Access Token access_token 是接口的全局唯一票据, 接入方调用各接口时都需使用 access_token 开发者需要进行妥善保存 access_token 的存储至少要保留 512 个字符空间 access_token 的有效期目前为 2 个小时, 需定时刷新, 重复

获取 Access Token access_token 是接口的全局唯一票据, 接入方调用各接口时都需使用 access_token 开发者需要进行妥善保存 access_token 的存储至少要保留 512 个字符空间 access_token 的有效期目前为 2 个小时, 需定时刷新, 重复获取将导致上次获取的 access_token 失效接入方可以使用 AppID 和 AppSecret

目录 概述... 2 基本流程... 2 接口文档... 3 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth code... 3 使用 auth code 换取 access token... 4 使用 refresh_token 换取 acc

目录概述... 2 基本流程... 2 接口文档... 3 引导用户进入开放平台授权用户授权页面, 以 302 到 callback URI 的方式返回 auth code... 3 使用 auth code 换取 access token... 4 使用 refresh_token 换取 acc