菜单

OAuth2.0 登录

接入要求

客户系统支持 OAuth 2.0 Authentication Code 方式授权
客户系统可以根据 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 的校验

使用此功能的标准流程：

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

可能会用到的额外配置：

配置项	配置说明	范例
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

最近修改: 2025-05-22