[v2]网瑞达统一认证对接手册-OAuth2.0方式-20190110

1网瑞达OAuth2.0开放平台对接手册北京网瑞达科技有限公司一、文档目的本文档作为OAuth2.0开放平台对接手册，指导第三方网站对接服务器，在用户授权的情况下获取服务器上的数据。二、什么是OAuth2.0开放平台概述OAuth2.0（开放授权）是一个开放标准，允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而不需要将用户名和密码提供给第三方网站或分享他们数据的所有内容。登录OAuth2.0开放平台：对于用户相关的数据（例如获取用户信息，动态同步，照片，日志，分享等），为了保护用户数据的安全和隐私，第三方网站访问用户数据前都需要显式的向用户征求授权。登录OAuth2.0采用OAuth2.0标准协议来进行用户身份验证和获取用户授权，相对于之前的OAuth1.0协议，其认证流程更简单和安全。三、OAuth2.0基本流程简介使用OAuth2.0开放平台总体处理流程如下：Step1：申请接入，获取client_id；Step2：放置OAuth2.0开放平台登录按钮；Step3：通过用户登录验证和授权，获取Authorization_Grant；Step4：使用Authorization_Grant向开放平台换取Access_token及Refresh_Token；Step5：使用Access_token调用OpenAPI，来请求访问或修改用户授权的资源。更多细节在下文进行详细介绍。3.1向开放平台注册申请client_id在使用OAuth2.0开放平台进行登录授权之前，需要提供第三方网站的名称和url来申请获取client_id。client_id：访问用户资源时用来验证应用的合法性。申请注册步骤：登录统一认证系统，进入应用管理-OAuth列表-添加-输入第三方网站的名称和url-系统自动生成client_id-将client_id返回给第三方网站3.2放置OAuth2.0开放平台登录按钮OAuth2.0登录3.3使用Authorization_Code获取Access_Token3.3.1简介即server-side模式，是OAuth2.0认证的一种模式，又称WebServerFlow；适用于需要从webserver访问的应用，例如Web网站。其授权验证流程示意图如下（图片来源：OAuth2.0协议草案V21的4.1节）对于第三方网站而言，需要进行两步：1.获取AuthorizationCode；2.通过AuthorizationCode获取AccessToken3.3.2过程详解Step1：获取AuthorizationCode请求地址：请求方法：GET请求参数：参数是否必须含义client_id必须申请注册成功后，分配给网站的client_id。response_type必须授权类型，此值固定为“code”。redirect_uri必须成功授权后的回调地址，必须是注册client_id时填写的主域名下的地址，建议设置为网站首页或网站的用户中心。例如：端的状态值。用于第三方网站防止CSRF攻击，成功授权后回调时会原样带回。返回说明：1.如果用户成功登录并授权，则会跳转到指定的回调地址，并在redirect_uri地址后带上AuthorizationCode和原始的state值。例如：=test&code=9A5F*********************06AF2.如果用户成功登录并授权，但是请求参数没有state,则会跳转到指定的回调地址，并在redirect_uri地址后只带上AuthorizationCode。例如：=9A5F*********************06AF注意：此code会在10分钟内过期。错误码说明：接口调用有错误时，会在页面上显示相应得错误信息。Step2：通过AuthorizationCode获取AccessToken请求地址：PC网站：请求方法：POST请求参数：参数是否必须含义client_id必须申请注册成功后，分配给网站的client_id。grant_type必须授权类型，此值固定为“authorization_code”redirect_uri必须与上面一步中传入的redirect_uri保持一致。code必须上一步返回的authorizationcode。返回说明：如果成功返回，即可在返回包中获取到AccessToken。如：access_token=FE04************************CCE2&expires_in=7776000&refresh_token=88E4************************BE14参数说明描述access_token申请注册成功后，分配给网站的client_id。expires_in该accesstoken的有效期，单位为秒。refresh_token在授权自动续期步骤中，获取新的Access_Token时需要提供的参数。错误码说明：接口调用有错误时，会返回json格式的response其中包含了error_code和message字段。错误码详细信息请参见下图：Step3：权限自动续期，获取AccessTokenAccess_Token的有效期默认是1个小时，过期后需要用户重新授权才能获得新的Access_Token。本步骤可以实现授权自动续期，避免要求用户再次授权的操作，提升用户体验。请求地址：PC网站：请求方法：POST请求参数：参数是否必须含义client_id必须申请注册成功后，分配给网站的client_id。grant_type必须授权类型，在本步骤中，此值为“refresh_token”。redirect_uri必须与上面一步中传入的redirect_uri保持一致。返回说明：如果成功返回，即可在返回包中获取到AccessToken。如：access_token=FE04************************CCE2&expires_in=7776000&refresh_token=88E4************************BE14。参数说明描述access_token申请注册成功后，分配给网站的client_id。expires_in该accesstoken的有效期，单位为秒。refresh_token在授权自动续期步骤中，获取新的Access_Token时需要提供的参数。3.4调用OpenAPI来获取用户授权的资源。请求地址第三方网站：开放平台网站：请求方法GET请求参数参数是否必须含义access_token必须在Step2/3中获取到的accesstoken。返回说明第三方网站接入时，通过调用开放平台的接口获取到用户授权的信息，返回包如下：json{error_code:0message:获取的资源}当access_token过期或者用户未授权该资源时，返回错误信息。