菜单

OAuth2.0 登录

接入要求

  1. 客户系统支持 OAuth 2.0 Authentication Code 方式授权
  2. 客户系统可以根据 Access Token 提供使用者信息（帐号、在神策系统中对应项目的角色）

OAuth 是什么

OAuth (Open Authorization 开放授权) 是一个授权标准，可以让神策系统获取到使用者的信息，但使用者却不需要提供帐号密码给神策系统。

举个例子：今天我想要用 微X 帐号登录 知X，点击 微X 图示的时候，会跳出一个新的视窗让我输入帐号密码，输入完帐号密码之后，知X 就能拿到我在 微X 上的昵称、头像等信息，但这过程中我并没有将帐号密码提供给 知X。

注意：新视窗的网址是 微X 的域名，而不是 知X 的域名，所以 微X 的帐号密码是提供给 微X，而非 知X

 

而换到 神策系统 也是同理，只是其中的身分发生了改变。

知X → 神策系统（想知道要登录的 使用者 是属于什么角色）

微X → 客户系统（系统保存了 使用者 的帐号密码）

角色用作授权使用，让神策系统知道该帐号可以做什么及不可以做什么

所以神策的 OAuth 就是：使用者使用客户系统的帐号密码，登录到客户自己的系统，但神策系统可以获取到使用者对应的角色。

有哪些配置

如需配置 OAuth2.0 登录，需要提供如下配置信息：

配置项 配置说明 范例
oauth_authorize_url

使用者在神策的 OAuth 登录页面，点击登录按钮后，会跳转到的地址。

通常为客户系统的登录页面。

 https://openapi.example.com/oauth/2.0/authorize
oauth_client_id

客户系统分配给神策的账号。

因为客户系统可能不只有让神策接入 OAuth，这是给客户系统去区分请求来源。

 SensorsData
oauth_client_secret

与上方 oauth_client_id 配合的密码。

因为账号、密码是给客户系统来区分请求来源的，所以客户可以随意制定，客户系统能辨识即可。

后续神策系统请求客户系统的 oauth_access_token_request_uri 时，会带上账号和密码。

 a1234567
oauth_redirect_uri

在客户系统上认证成功后的回调地址。

通常为神策系统的地址。

 https://www.sensorsdata.cn/
oauth_access_token_request_uri 在客户系统上，获取访问令牌的地址。 https://openapi.example.com/oauth/2.0/token
default_fetcher_request_uri 在客户系统上，获取用户对应角色的地址。 https://openapi.example.com/userinfo
oauth_scope 获取用户信息的权限列表，可选配置 profile
oauth_client_config_map 为不同项目配置不同的 oauth_client_id 和 oauth_client_secret {"default":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"},"production":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"}}

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

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k oauth_authorize_url -v "https://openapi.example.com/oauth/2.0/authorize"
sbpadmin business_config set -p sbp -k oauth_client_id -v "SensorsData"
sbpadmin business_config set -p sbp -k oauth_client_secret -v "a1234567"
sbpadmin business_config set -p sbp -k oauth_redirect_uri -v "https://www.sensorsdata.cn/"
sbpadmin business_config set -p sbp -k oauth_access_token_request_uri -v "https://openapi.example.com/oauth/2.0/token"
sbpadmin business_config set -p sbp -k default_fetcher_request_uri -v "https://openapi.example.com/userinfo"
sbpadmin business_config set -p sbp -k oauth_scope -v "openid email profile"
// 需要配置不同项目的 oauth_client_id 和 oauth_client_secret 使用
sbpadmin business_config set -p sbp -k oauth_client_config_map -v "{"default":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"},"production":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"}}"

sbp >= 1.1.0+

spadmin config set product_global -p sbp -n oauth_authorize_url -v "https://openapi.example.com/oauth/2.0/authorize"
spadmin config set product_global -p sbp -n oauth_client_id -v "SensorsData"
spadmin config set product_global -p sbp -n oauth_client_secret -v "a1234567"
spadmin config set product_global -p sbp -n oauth_redirect_uri -v "https://www.sensorsdata.cn/"
spadmin config set product_global -p sbp -n oauth_access_token_request_uri -v "https://openapi.example.com/oauth/2.0/token"
spadmin config set product_global -p sbp -n default_fetcher_request_uri -v "https://openapi.example.com/userinfo"
spadmin config set product_global -p sbp -n oauth_scope -v "openid email profile"
// 需要配置不同项目的 oauth_client_id 和 oauth_client_secret 使用
spadmin config set product_global -p sbp -n oauth_client_config_map -v {"default":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"},"production":{"oauth_client_id":"SensorsData","oauth_client_secret":"a1234567"}}

sca>=0.4 或 sbp0.5+

spadmin config set server -p sbp -m web -n oauth_authorize_url -v "https://openapi.example.com/oauth/2.0/authorize" 
spadmin config set server -p sbp -m web -n oauth_client_id -v "SensorsData" 
spadmin config set server -p sbp -m web -n oauth_client_secret -v "a1234567" 
spadmin config set server -p sbp -m web -n oauth_redirect_uri -v "https://www.sensorsdata.cn/" 
spadmin config set server -p sbp -m web -n oauth_access_token_request_uri -v "https://openapi.example.com/oauth/2.0/token" 
spadmin config set server -p sbp -m web -n default_fetcher_request_uri -v "https://openapi.example.com/userinfo" 
spadmin config set server -p sbp -m web -n oauth_scope -v "openid email profile

神策分析版本 >= 1.14

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 "SensorsData"
spadmin config set server -p sa -m web -n oauth_client_secret -v "a1234567"
spadmin config set server -p sa -m web -n oauth_redirect_uri -v "https://www.sensorsdata.cn/"
spadmin config set server -p sa -m web -n oauth_access_token_request_uri -v "https://openapi.example.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 生效：

sca>=0.4 或 sbp0.5+

spadmin restart -m web -p sbp

神策分析版本 >= 1.14

spadmin restart -m web -p sa

登录流程

整体流程图

使用者登录

使用者进入到神策系统的 OAuth 登录页面，点击登录按钮后，将跳转到 oauth_authorize_url 配置的地址。

仅配置完成后才会有 OAuth 的按钮。

跳转之后，使用者应该看到客户系统的登录页面，在此页面使用者需要输入自己在客户系统的账号密码。

具体的跳转地址会是 oauth_authorize_url，后面带上 redirect_uri 参数，该参数为使用者登录成功后，要 302 跳转的地址。

例如：

https://openapi.example.com/oauth/2.0/authorize?
redirect_uri=https://www.sensorsdata.cn/api/oauth/auth?project=default&oauth_type=oauth&status=&client_id=SensorsData

这里只会带上 oauth_client_id 而不会带上 oauth_client_secret，因为使用者会直接看到这个地址，这里带上 oauth_client_secret 会导致密码泄漏

产生 code

当使用者在客户系统上，输入完账号密码并点击登录后，如果客户系统校验使用者的账号密码成功，则带上一个随机 code 参数，跳转到请求参数上的 redirect_uri，code 则作为该使用者的标记。

例如：

HTTP/1.1 302 Found

https://www.sensorsdata.cn/api/oauth/auth?
project=default&
oauth_type=oauth&
status=&
client_id=SensorsData&
code=example-code

如果校验使用者的账号、密码失败，请不要进行跳转。

code 需由客户系统随机产生，作为该使用者的标识，后续神策系统会发送该 code 来请求该使用者的 access_token

产生 access_token

神策系统使用 POST 方式调用客户系统的 oauth_access_token_request_uri 地址，并带上 code、client_id、client_secret 作为标识，获取访问令牌 access_token。

例如：

https://openapi.example.com/oauth/2.0/token?
code=example-code&
grant_type=authorization_code&
client_secret=a1234567&
oauth_type=oauth&
client_id=SensorsData

默认情况下，获取 access_token 的请求会将所有的请求参数放在 URI 中，如果需要将请求的参数放在 request body 中，需要执行以下命令：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k oauth_token_request_impl -v param_in_request_body

sbp >= 1.1.0+

spadmin config set product_global -p sbp -n oauth_token_request_impl -v param_in_request_body

神策分析版本 >= 1.14

spadmin config set server -p sa -m web -n oauth_token_request_impl -v param_in_request_body

神策分析版本 < 1.14

monitor_tools set_config -t server -m web -n oauth_token_request_impl -v param_in_request_body

如果客户的接口协议在 header 的 content-type 不是 application/json，需要用这个配置改变 content-type 的参数：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k oauth_access_token_request_content_type -v 客户指定的content-type

sbp >= 1.1.0+

spadmin config set product_global -p sbp -n oauth_access_token_request_content_type -v 客户指定的content-type

如果有指定 content-type 的参数，且同时也有验证的需求，需要额外再配置验证用的参数 oauth_access_token_request_authorization，此时会在 header 加上 Authorization 参数：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k oauth_access_token_request_authorization -v 客户指定的授权码

sbp >= 1.1.0+

spadmin config set product_global -p sbp -n oauth_access_token_request_authorization -v 客户指定的授权码

客户系统需返回 access_token

{
    "access_token": "example-access-token"
}

按照正式的 OAuth 规范，应该也要返回 refresh_token、expires_in 字段，但神策的 OAuth 系统，仅需要 access_token 字段即可，另外两个字段是否返回都不影响结果。

返回 UserInfo

神策系统默认用 POST 方式呼叫客户系统的 default_fetcher_request_uri，并带上 access_token 作为标示，获取使用者对应的角色

https://openapi.example.com/userinfo?
access_token=example-access-token&
project=default

如果客户获取 userInfo 的请求只支持 GET 方式，需要 sbp >= 1.1.0，并执行以下配置命令：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k open_id_user_info_request_method -v GET

sbp >= 1.1.0

spadmin config set product_global -p sbp -n open_id_user_info_request_method -v GET

当以 POST 方式请求时，获取 userInfo 的请求会将所有的请求参数放在 URI 中，如果需要将请求的参数放在 request body 中，需要 sbp >= 1.1.0，并执行以下配置命令：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k user_info_fetcher_request_impl -v param_in_request_body

sbp >= 1.1.0

spadmin config set product_global -p sbp -n user_info_fetcher_request_impl -v param_in_request_body

客户系统需返回 UserInfo

{
 	"username":"xiaoming", 	// 使用者帐号（必选，不能存在中文字符及其他特殊字符，可以为邮箱格式或纯数字）
 	"user_cname":"小明",		// 使用者中文名称（可选，不返回时与 username 一致）
 	"role":"analyst"		// 使用者角色（可选，admin（管理员），analyst（分析师） 和 guest（普通用户）, 若取其他值则按普通用户处理）
}

如果没有返回 role 字段，若该帐号在神策系统中已存在，那么使用其之前的角色；若该帐号不存在，则角色为普通用户。

如果没有返回 username 字段，则认为该帐号不存在。如果该帐号在神策系统没有权限，可以直接返回空 JSON 即可。

如果客户系统响应的 UserInfo 数据中没有 username，但是有相关的字段用于用户的唯一标识，可通过以下配置映射。

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k default_user_info_user_name_field -v 客户UserInfo接口响应的账号唯一标识字段

sbp >= 1.1.0

spadmin config set product_global -p sbp -n default_user_info_user_name_field -v 客户UserInfo接口响应的账号唯一标识字段

用户角色描述请见 权限管理

登录成功

使用者登录神策系统成功，并以 UserInfo 接口返回的帐号和角色使用神策系统。

特殊需求

使用 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 接口，需要开启如下配置：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k use_open_id_user_info_fetcher -v true

sbp >= 1.1.0+

spadmin config set product_global -p sbp -n use_open_id_user_info_fetcher -v true

神策分析版本 >= 1.14

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

神策分析版本 < 1.14

monitor_tools set_config -t server -m web -n use_open_id_user_info_fetcher -v true

OAuth 的 UserInfo 接口响应数据信息同步到神策系统（SBP >= 1.1.0）

sbp >= 1.1.0 时：将 OAuth 的 UserInfo 接口的响应数据同步信息到神策系统，目前支持的信息有：用户姓名，手机号，邮箱

配置示例：

sbp >= 1.3.0

sbpadmin business_config set -p sbp -k oauth_user_mapping_map -v "{\"userCname\":\"user_cname_field\",\"phone\":\"phone_field\",\"email\":\"email_field\"}"

sbp >= 1.1.0

spadmin config set product_global -p sbp -n oauth_user_mapping_map -v "{\"userCname\":\"user_cname_field\",\"phone\":\"phone_field\",\"email\":\"email_field\"}"

说明：以 k-v 的形式配置，其中 userCname、phone、email 分别对应用户姓名，手机号和邮箱，不可修改。user_cname_field，phone_field，email_field 为 UserInfo 接口响应的用户信息字段

开启先登录后选择项目（SBP >= 1.4.0）

简介： 可开启先登录后选择项目，避免选择无权限的项目而报错以及 OAuth 严格校验时需要配置 project 与 product 参数值的问题。

前置条件：

  • SBP >= 1.4.0
  • 当前仅允许平台账号登录
  • 如果 OAuth 开启强校验需要去除对 project 和 product 的校验

使用此功能的标准流程：

  1. 阅读文档，了解 OAuth 的基本配置流程并进行配置。
  2. 配置创建用户后其默认关联的项目。oauth_login_projects 或 enable_oauth_auto_login_all_projects 二选一。
  3. 使用工具开启 登录后选择项目功能。

可能会用到的额外配置：

配置项 配置说明 范例
oauth_custom_redirect_uri

自定义回调地址，可选配置。

登录成功后携带 cookie 信息跳转到指定的登录地址以进行选择项目。

没有此配置时，回调地址为：在 oauth_redirect_uri 配置后拼接 /login/index.html

 https://www.sensorsdata.cn/login/index.html
enable_oauth_auto_create_user

自动创建账号，可参考：自动创建用户

此配置默认为 true。

开启自动创建账号配置时，需要配置其默认关联的项目。即 oauth_login_projects 与 enable_oauth_auto_login_all_projects 配置二选一即可。

 true
oauth_login_projects

自动创建用户时，创建出来的用户关联的项目。（逗号分隔）

默认为空字符串。

 default,production
enable_oauth_auto_login_all_projects

自动创建用户时，创建出来的用户关联所有项目。

默认为 false。

 true

修改上述配置时，示例如下：

sbp >= 1.4.0

sbpadmin business_config -a set -p sbp -k oauth_custom_redirect_uri -v "https://www.sensorsdata.cn/login/index.html"
sbpadmin business_config -a set -p sbp -k enable_oauth_auto_create_user -v "true"
sbpadmin business_config -a set -p sbp -k oauth_login_projects -v "default,production"
sbpadmin business_config -a set -p sbp -k enable_oauth_auto_login_all_projects -v "true"

注意：

  • 使用登录后选择项目功能时，只要开启自动创建账号配置，就需要配置 oauth_login_projects 或 enable_oauth_auto_login_all_projects。
  • 因为先登录后选择项目，所以不再需要 oauth_client_config_map 配置。

使用工具开启 登录后选择项目功能：

sbp >= 1.4.0

sbpadmin oauth_config -t open
上一个
第三方登录
下一个
LDAP 登录
最近修改: 2025-05-22