OAuth2.0 登录

最后更新于:2019-12-11 17:11:09

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

神策分析从 1.6.5 版开始支持通过 OAuth2.0 进行登录,大致登录流程如下:

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

实现 OAuth2.0 登录有如下要求:

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

1. 配置信息

如需配置 OAuth2.0 登录,需要提供如下配置信息:

配置项 配置说明
oauth_authorize_url OAuth 2.0 的授权地址
oauth_access_token_request_uri 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 获取用户信息需要的权限列表,非必须参数
default_fetcher_request_uri 使用 Access Token 获取该用户信息的 API,即 UserInfo API

一个完整的配置示例如下:

monitor_tools set_config -t server -m web -n oauth_authorize_url -v "https://openapi.example.com/oauth/2.0/authorize"
monitor_tools set_config -t server -m web -n oauth_client_id -v ABCDEFG1234
monitor_tools set_config -t server -m web -n oauth_redirect_uri -v 'https://SA_HOST:8107'
monitor_tools set_config -t server -m web -n oauth_client_secret -v "XYZ00000"
monitor_tools set_config -t server -m web -n oauth_access_token_request_uri -v 'https://openapi.baidu.com/oauth/2.0/token'
monitor_tools set_config -t server -m web -n default_fetcher_request_uri -v 'https://openapi.example.com/userinfo'
monitor_tools set_config -t server -m web -n oauth_scope -v "openid email profile"
spadmin config set server -p sa -m web -n oauth_authorize_url -v "https://openapi.example.com/oauth/2.0/authorize"
spadmin config set server -p sa -m web -n oauth_client_id -v ABCDEFG1234
spadmin config set server -p sa -m web -n oauth_redirect_uri -v 'https://SA_HOST:8107'
spadmin config set server -p sa -m web -n oauth_client_secret -v "XYZ00000"
spadmin config set server -p sa -m web -n oauth_access_token_request_uri -v 'https://openapi.baidu.com/oauth/2.0/token'
spadmin config set server -p sa -m web -n default_fetcher_request_uri -v 'https://openapi.example.com/userinfo'
spadmin config set server -p sa -m web -n oauth_scope -v "openid email profile"

配置完成后需要重启 web 生效:

sa_admin restart -m web
spadmin restart -m web -p sa

2. 登录流程

2.1 用户点击 OAuth 登录后跳转到第三方登录页面

用户打开神策分析登录页面,点击 “OAuth 登录” 链接(仅配置后才有该按钮),浏览器会跳转到配置的登录页面(第三方登录页面,如企业内的权限系统):

例如 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 并加上 projectoauth_type 两个参数,例如该值为 https://SA_HOST:8107/?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%3A8107%2F%3Fproject%3Dproduction%26oauth_type%3Doauth

如果登录失败不需要进行回调。

2.2 用户在第三方认证系统完成登录验证

用户使用该权限系统的用户名密码或其他方式完成验证登录,登录成功后,页面将跳转回神策分析页面:

用户登录成功后,用户的浏览器将按如下地址跳转:

HTTP/1.1 302 Found
Location: https://SA_HOST:8107/?project=production&oauth_type=oauth&code=ANXxSNjwQDugOnqe

跳转地址即 redirect_uri 加上 code 字段,值为 Authorization Code;

2.3 获取 Access Token

第三方权限系统上配置的用户信息给予用户在神策分析上的权限:

  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:8107/?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%3A8107%2F%3Fproject%3Dproduction%26oauth_type%3Doauth
    

    服务端响应数据包应返回 Access Token,例如响应包为:

    {
        "access_token": "a6b7dbd48f731035f771b8d63f6",
        "refresh_token": "385d55f8615dfd9edb7c4b5ebd",
        "expires_in": 86400,
    }
    

    其中会用到的仅有 access_token 字段,该 Access Token 应该仅会使用一次。

    默认情况下,获取 access_token 的请求会将所有的请求参数放在 Uri 中,如果需要将请求的参数放在 request body 中,需要修改如下配置:

       monitor_tools set_config -t server -m web -n oauth_token_request_impl -v param_in_request_body
       spadmin config set server -m web -n oauth_token_request_impl -v param_in_request_body

2.4 获取用户信息

神策分析将使用 Access Token 去获取 UserInfo,默认情况下神策支持两种格式的 UserInfo 接口定义:

  1. 使用神策定义的 UserInfo 接口格式(默认)

    例如 User Info API 地址为 https://openapi.example.com/userinfo,将带上如下参数并使用 POST 方式访问:

    • access_token: 上面获取到的 Access Token, 例如 a6b7dbd48f731035f771b8d63f6;
    • 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 即可。

  2. 使用 OpenID 标准 UserInfo 接口格式

    API 格式参考:OpenID UserInfo 接口

    与神策定义的 UserInfo 接口的区别是请求是请求时不区分神策的项目信息,而且返回的 response 里面没有角色信息,例如:

     {
       "sub": "248289761001",
       "name": "Jane Doe",
       "given_name": "Jane",
       "family_name": "Doe",
       "preferred_username": "j.doe",
       "email": "janedoe@example.com",
       "picture": "http://example.com/janedoe/me.jpg"
      }
    

    神策分析会使用 preferred_username 字段作为 username,同时使用默认的角色(即普通用户)进行登录。

    如需使用该格式的 UserInfo 接口,需要开启如下配置:

       monitor_tools set_config -t server -m web -n use_open_id_user_info_fetcher -v true
       spadmin config set server -p sa -m web -n use_open_id_user_info_fetcher -v true

2.5 登录成功

用户登录神策系统成功,并以 UserInfo 接口返回的用户名和角色使用神策系统