SHOPLAZZA帮助中心

搜索

迁移到标准的OAuth流程

本文包含开发者如何迁移到标准OAuth流程的全部信息,请仔细阅读。       

 

本页相关主题


 

为什么要迁移?

         由于一些历史原因,在以前App的OAuth授权流程中,商家添加App或进入App之后,Shoplazza会代表App作为OAuth的使用方(client)来发起了OAuth流程,App来接收OAuth的返回结果,如下图所示:

non-standard-oauth-flow.png

可以看到图中的发起方是Shoplazza,接收方式App, 这样的方式会引起一些问题:

  • 由Shoplazza而非App来发起OAuth流程,让App无法掌握发起OAuth的流程灵活性
  • 由于发起方不是App,接收OAuth返回结果时,App无法确定其来源和安全性,有安全隐患
  • 由于发起方不是App,App无法灵活的变更请求权限列表(scope),而必须通过发邮件的方式变更

因为这些问题,我们希望我们的开发者能够迁移到标准的OAuth流程.

 

标准的OAuth 流程

标准的OAuth流程应该由OAuth的使用方(client)来发起OAuth流程,如下图的 IETF的标准OAuth流程:Client端是发起OAuth流程一方,同时也接收OAuth的返回结果的一方。ietf-oauth-flow.png

 

也就是说,在Shoplazza平台中,标准的OAuth流程,应该由App来发起OAuth流程,所以Shoplazza平台出具以下的Shoplazza平台标准的OAuth流程迁移指南给开发者做迁移的参考,如下:

 

Shoplazza标准的OAuth 流程

standard-oauth-flow.png

如上图的红色区域,我们把OAuth的发起方交还给App,由App来发起OAuth流程,并且由App来接收OAuth的返回结果,有以下好处:

  • 由App发起OAuth流程,让App可以掌握发起OAuth的流程灵活性
  • 由App发起OAuth流程,并由App接收OAuth返回结果,可以确定其来源和安全性,消除安全隐患
  • 由App发起OAuth流程,App可以灵活的变更请求权限列表(scope)

 

如何迁移?

新增App发起OAuth请求的逻辑

    1. 登录进合作伙伴中心.
    2. 选择你想要修改的App
    3. 进入App设置页面
    4. 填写App URL
    5. 保存设置
  • App端处理OAuth的发起流程. 
    • 在填写了App URL之后,你的App会被变更为标准的OAuth流程,当商家点击App图标进入App时,Shoplazza将重定向到App URL,而不是以前的Redirect URL,所以App需要从App URL来开始处理发起OAuth流程的事务,Shoplazza重定向到其中App URL时会携带以下参数,以便App端可以确定来源店铺和Shoplazza的安全签名:

重定向地址:{app_url}/?{params}

携带参数:

参数名

描述

hmac

Shoplazza生成的安全签名串,用于安全确认

shop

店铺域名,用于告知App来源店铺

    • App开始处理OAuth发起流程,如下图:

mceclip0.png

  • 实现OAuth发起流程:
    • 检查OAuth状态
      • App自查是否以前已经经过了OAuth流程,可以检查有没有跟store对应的access token,以及这个access token是不是有效的。 
        • 如果App已经有了一个有效的access token,而且App没有重新申请权限列表的计划,那么App可以直接开始通过跟Shoplazza的Open API互动来为商家提供服务了。
        • 如果App没有有效的access token,或者App需要更换权限列表,那么App可以发起OAuth流程来请求授权。
    • 发起OAuth流程
      • 如果App没有access token,那么App就可以发起OAuth到店铺来请求商家授权。
      • 如果App需要更换权限列表,那么同样App也可以直接发起OAuth到店铺请求商家授权。
      • 请求OAuth,重定向的地址和携带参数如下:

重定向地址:https://{store_domain}/admin/oauth/authorize?{params}

携带参数:

参数名

描述

store_domain

通常是{store_name}.myshoplazza.com,如果店铺有自定义店铺域名,这里也可以是店铺自定义域名,再商家点击应用图标时会通过参数"store"告知

client_id

App的client ID

scope

App所需的权限列表, 由空格分开

redirect_uri

App用来接收OAuth返回结果的重定向URL

response_type

授权的类型,这里填: code

state

App生成的随机值,用于在接收OAuth接收返回结果时,确认OAuth的发起来源

hmac

Shoplazza生成的安全签名串,用于安全确认


 

保留接收OAuth的返回结果逻辑

    • 接收OAuth返回结果
      • 从这一步开始,流程跟之前的OAuth流程就一致了,开发者不需要做太多改动,只需要确认OAuth返回结果的来源即可
      • 当商家授权了App的OAuth请求后,将会重定向到App的Redirect URL,将会携带OAuth的返回参数,如下

重定向地址:{redirect_url}/?{params}

携带参数:

参数名

描述

code

OAuth授权码

state

App发起OAuth时附带的随机值,此时可以检查其来源

hmac

Shoplazza生成的安全签名串,用于安全确认

shop

店铺域名

      • 获取OAuth授权码
      • 检查state值是否是其发起时生成的值,以确保安全
    • 获取Access Token
      • 跟之前的流程一样,在拿到OAuth授权码之后,向Shoplazza发起获取Access token请求,请求地址和参数如下:

 

请求地址:

POST: https://{store}/admin/oauth/token

请求参数:

参数名

描述

store

通常是{store_name}.myshoplazza.com,如果店铺有自定义店铺域名,这里也可以是店铺自定义域名,再商家点击应用图标时会通过参数"store"告知

client_id

App的client ID

client_secret

App的私钥

code

OAuth授权码

grant_type

授权类型,这里填写:authorization_code

redirect_uri

App配置的重定向地址(Redirect URl)

 

返回参数:

参数名

描述

token_type

Token类型,返回固定值:Bearer

access_token

用于Shoplazza Open API鉴权的token

expires_at

token过期时间

refresh_token

用于刷新access token的刷新token

store_id

店铺ID

store_name

店铺名称

    • 刷新Access Token
        • 跟之前的流程一样,如果Access token过期,可以向Shoplazza发起刷新Access token请求,请求地址和参数如下:

请求地址:

POST: https://{store}/admin/oauth/token

请求参数:

参数名

描述

store

通常是{store_name}.myshoplazza.com,如果店铺有自定义店铺域名,这里也可以是店铺自定义域名,再商家点击应用图标时会通过参数"store"告知

client_id

App的client ID

client_secret

App的私钥

refresh_token

刷新token

grant_type

授权类型,因为是请求刷新token,这里填写:refresh_token

redirect_uri

App配置的重定向地址(Redirect URl)

 

返回参数:

参数名

描述

token_type

Token类型,返回固定值:Bearer

access_token

新的Access token

expires_at

token过期时间

refresh_token

用于刷新access token的刷新token

store_id

店铺ID

store_name

店铺名称

 

    • App开始服务上架
      • 有了Access token后,App可以开始和Shoplazza Open API进行互动,并且开始为商家服务了

 

迁移时间计划

我们希望应用开发者能尽早迁移到标准的OAuth流程,以便于方便开发者控制OAuth流程并减少安全隐患,我们将用下表时间规划来执行我们的迁移计划,请开发者尽快在截止日期之前做完OAuth迁移,若超过截止日期,平台将会做应用下架处理,开发者可以做完迁移后再次申请上架。

 

阶段 开始时间 结束时间 时长 事项
迁移时间 2021-12 2022-06-01 6个月

- 开发者入驻并关联App

- 开发者做OAuth迁移

- 迁移期间允许App可以短暂的不迁移,但在设置页会看到警告提示

警告时间 2022-06-01 2022-06-30 1个月

- 开发者未入驻的,6月1号开始,开发者将收到「未完成入驻」警告邮件

- 开发者未完成OAuth迁移的的,6月1号开始,开发者将收到「未完成OAuth迁移」的警告邮件

- 开发者在6月还有一个月时间做完成开发者入驻和OAuth迁移

截止时间 2022-07-01 - -

- 平台将针对未做完「开发者入驻」和「OAuth迁移」的做应用下架处理

- 开发者完成「开发者入驻」和「OAuth迁移」后,可以再次申请上架

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

由 Zendesk 提供技术支持