接入要求
- 客户系统支持 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