第三方登录

最后更新于：2018-08-02 14:18:08

本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

神策分析从 1.6.5 版开始支持对接第三方身份验证与授权系统。目前支持 OAuth 2.0 Authentication Code 的方式获取 Access Token，再使用 Access Token 请求用户登录信息，大致登录流程如下：

用户打开神策分析登录页面，点击 “OAuth 登录” 按钮（仅配置后才有该按钮），浏览器会跳转到配置的登录页面（第三方登录页面，如企业内的权限系统）;
用户使用该权限系统的用户名密码或其他方式完成验证登录，登录成功后，页面将跳转回神策分析页面并以权限系统上配置的用户信息给予用户在神策分析上的权限;

实现第三方登录有如下要求：

第三方权限系统支持 OAuth 2.0 Authentication Code 方式授权;
第三方权限系统可以根据 Access Token 获取用户信息（用户名和在神策某个项目中的角色）

如需配置第三方登录，需要提供如下信息：

OAuth Authorize Url: OAuth 2.0 的授权地址;
OAuth Request Token Url: OAuth 2.0 使用 Authentication Code 换取 Access Token 的地址;
OAuth Client Id: OAuth 2.0 服务端为神策登录配置的应用 ID;
OAuth Client Secret: OAuth 2.0 服务端为神策登录配置的应用密钥;
OAuth Redirect Uri: 授权回调的 URI，即神策后端登录地址;
OAuth Scope: 获取用户信息需要的权限列表，非必须参数;
User Info API: 使用 Access Token 和神策项目名获取该用户权限信息的 API;

该登录的后端交互流程如下：

用户打开神策分析th 登录” 连接（仅配置后才有该按钮），浏览器会跳转到配置的登录页面（第三方登录页面，如企业内的权限系统）:

例如 OAuth Authorize Url 的地址是 https://openapi.example.com/oauth/2.0/authorize，跳转时会带上以下参数:
1. response_type: 此值固定为 code;
2. client_id: OAuth Client Id，例如该值为 ABCDEFG1234;
3. scope: OAuth Scope，非必须参数，值根据需求配置，例如该值为空;
4. state: 服务端生成的随机码，例如该值为 RWB23NQ1;
5. redirect_uri: OAuth Redirect Uri 并加上 project 和 oauth_type 两个参数，例如该值为 https://SA_HOST:8007/?project=production&oauth_type=oauth;
按样例描述最终会以如下地址访问 OAuth2 Authorize 页面：
```
https://openapi.example.com/oauth/2.0/authorize?
         response_type=code&
         client_id=ABCDEFG1234&
         state=RWB23NQ1&
         redirect_uri=https%3A%2F%2FSA_HOST%3A8007%2F%3Fproject%3Dproduction%26oauth_type%3Doauth
```
如果登录失败不需要进行回掉。
用户使用该权限系统的用户名密码或其他方式完成验证登录，登录成功后，页面将跳转回神策分析页面:

用户登录成功后，用户的浏览器将按如下地址跳转:
```
HTTP/1.1 302 Found
Location: https://SA_HOST:8007/?project=production&oauth_type=oauth&code=ANXxSNjwQDugOnqe
```
跳转地址即 redirect_uri 加上 code 字段，值为 Authorization Code;
以权限系统上配置的用户信息给予用户在神策分析上的权限:
1. 用户浏览器跳转回神策系统页面后，神策系统后端取到 Authorization Code;
2. 神策系统后端通过 Authorization Code 获取 Access Token:
  
  例如 OAuth2 Token 地址为 https://openapi.example.com/oauth/2.0/token，将带上如下参数并使用 POST 方式访问:
  1. grant_type: 此值固定为 authorization_code;
  2. code: 上面获取到的 Authorization Code，例如 ANXxSNjwQDugOnqe;
  3. client_id: OAuth Client Id，例如该值为 ABCDEFG1234;
  4. client_secret: OAuth Client Secret，例如该值为 XYZ00000;
  5. redirect_uri: OAuth Redirect Uri，例如该值为 https://SA_HOST:8007/?project=production&oauth_type=oauth;
  按样例描述最终会以如下地址访问 OAuth2 Token 地址：
```
https://openapi.example.com/oauth/2.0/token?
      grant_type=authorization_code&
      code=ANXxSNjwQDugOnqe&
      client_id=ABCDEFG1234&
      client_secret=XYZ00000&
      redirect_uri=https%3A%2F%2FSA_HOST%3A8007%2F%3Fproject%3Dproduction%26oauth_type%3Doauth
```
  服务端响应数据包应返回 Access Token，例如响应包为:
```
{
    "access_token": "a6b7dbd48f731035f771b8d63f6",
    "refresh_token": "385d55f8615dfd9edb7c4b5ebd",
    "expires_in": 86400,
}
```
  其中会用到的仅有 access_token 字段，该 Access Token 应该仅会使用一次，下面会描述。
3. 神策系统后端通过 Access Token 获取用户信息:
  
  例如 User Info API 地址为 https://openapi.example.com/userinfo，将带上如下参数并使用 POST 方式访问:
  1. access_token: 上面获取到的 Access Token, 例如 a6b7dbd48f731035f771b8d63f6;
  2. project: 登录用户访问的神策项目英文名，例如 production;
  最终将以如下地址发起请求：
```
https://openapi.example.com/userinfo?
        access_token=a6b7dbd48f731035f771b8d63f6&
        project=production
```
  服务端根据 Access Token 和项目名将该用户在这个项目中的用户名和权限返回给神策后端，例如：
```
{
    "username":"xiaoming",
    "role":"analyst"
}
```
  username 的值即为用户在神策中的用户名，是登录的必须字段;
  
  role 字段为在神策中的角色，是可选字段。role 可取值为 admin（管理员）, analyst（分析师）和 normal（普通用户）, 若取其他值则按普通用户处理，用户角色描述请见权限管理。当没有返回 role 字段时，若该用户名在神策中已存在，那么使用其之前的角色，否则默认为普通用户；
  
  如果返回的 JSON 中没有 username 字段，则认为用户不存在，即如果该用户在神策系统没有权限，直接返回空 JSON 即可。
4. 用户登录神策系统成功，并以返回的用户名和角色使用神策系统;