OAuth2.0 login

Access requirement

1. The customer system supports OAuth 2.0 Authentication Code authentication
2. The client system can provide user information (account number, role in the corresponding project in the system) based on the Access Token.

What is OAuth

OAuth(Open Authorization) is an authorization standard that allows the authorization system to obtain user information, but the user does not need to provide the account password to the authorization system.

For example: today, I want to log in to Zhix with my micro-X account. When I click the Micro-X icon, a new window will pop up and let me input my account password. After entering the account password, Zhix can get my nickname, profile picture and other information on micro-X, but I did not provide the account password to Zhix during this process.

Note: The URL of the new window is Micro X domain name, not known X domain name, soMicroX account password is provided to MicroX，not ZhiX

The same is true with the switch to the Sensors system, only the identity has changed.

ZhiX → Sensors System (want to know what role the user who wants to log in belongs to)

MicroX → Customer system (The system saves the user's account password)

The role is used for authorization, so that the system knows what the account can and cannot do

Therefore, the OAuth of Sensors is: the user uses the account password of the customer's system to log in to the customer's own system, but the Sensors system can obtain the corresponding role of the user.

What configurations are available?

To configure OAuth2.0 login, you need to provide the following configuration information:

A complete configuration example is as follows:

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"}}

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"}}

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

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"

After the configuration is completed, the web needs to be restarted to take effect:

spadmin restart -m web -p sbp

spadmin restart -m web -p sa

Login process

Overall process diagram

User login

The user enters the OAuth login page of the Shenze system, clicks the login button, and jumps to the address configured by oauth_authorize_url.

The OAuth button is available only after the configuration is complete.

After the jump, the user should see the login page of the customer system, where the user should enter their account password in the customer system.

The specific forward address is oauth_authorize_url, followed by the redirect_uri parameter, which indicates the 302 forward address after the user successfully logs in.

For example：

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

Only oauth_client_secret will be included here, not oauth_client_secret, because the user will see the address directly, and oauth_CLIENT_secret will cause the password to leak

produce code

When the user enters the account password and clicks login on the customer system, if the customer system verifies the user's account password successfully, it will bring a random code parameter, jump to the redirect_uri on the request parameter, and code will be used as the mark of the user.

For example：

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

If the user account and password fail to be verified, do not jump.

The code must be randomly generated by the customer system as the identifier of the user, and the system will send the code to request the access_token of the user

produce access_token

Sensors System use POST method Call the oauth_access_token_request_uri address of the customer system, and attach the code, client_id, and client_secret as tags to obtain the access_token.

For example:

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

By default, getaccess_token request will put all the request parameters in the URI, if needed to put the request parameters request body, you need to run the following command:

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

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

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

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

If a customer's interface protocol in the header is not application/json for the content-type, this configuration needs to be used to change the parameters of the content-type:

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

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

If there is a specified parameter content-type and also a validation requirement, additional parameters for validation oauth_access_token_request_authorization, need to be configured. At this time, the header will add Authorization parameter：

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

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

Customer system needs to return access_token

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

According to the official OAuth specification, refresh_token and expires_in fields should also be returned. However, in the SenSor Analytics OAuth system, only the access_token field is required. Whether the other two fields are returned or not does not affect the result.

return UserInfo

Sensors System use POST method Call default_fetcher_request_uri of the customer system and attach access_token as an identifier to obtain the corresponding role of the user.

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

If the customer's request for obtaining userInfo only supports GET method, sbp >= 1.1.0 is required, and the following configuration command should be executed:

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

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

When requesting to obtain userInfo with POST method, all request parameters will be placed in the URI. If you need to place the request parameters in the request body, sbp >= 1.1.0 is required, and the following configuration command should be executed:

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

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

The customer system needs to returnUserInfo

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

If not returned role field, if the account already exists in the system, then use its previous role; If the account does not exist, the role is a common user.

If not returned username field, the account does not exist. If the account does not have permission in the system, you can directly return empty JSON.

If there is no username in the UserInfo data of the customer system response, but there is a related field for the unique identification of the user, you can configure the mapping as follows.

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

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

For the description of user roles, please refer to the "Permission Management" page.

Login succeeded

The user logs in to the Sensors Data system successfully and uses the account and role returned by the UserInfo interface to use the Sensors Data system.

Special requirements

OpenID standard UserInfo interface format

API format reference: OpenID UserInfo interface

The difference between the UserInfo interface defined by Sensors Analytics and the requested UserInfo interface is that the request does not distinguish project information in Sensors Analytics and the returned response does not contain role information, for example:

{ 	"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" }

Sensors Analytics will use the preferred_username field as the username (also as the display name), and use the default role (i.e. ordinary user) for login.

If you need to use the UserInfo interface in this format, you need to enable the following configuration:

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

spadmin config set product_global -p sbp -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

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

Synchronize UserInfo interface response data from OAuth to Sensors Analytics (SBP >= 1.1.0)

When sbp >= 1.1.0: Synchronize the response data ofUserInfo interface from OAuth to Sensors Analytics, currently supporting information includes: user name, phone number, email
Configuration example:

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

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

Note: Configured in key-value form, where userCname, phone, and email correspond to user name, phone number, and email respectively and cannot be modified. user_cname_field, phone_field, and email_field are the user information fields in the UserInfo interface response.

Enable Login and Select items (SBP > = 1.4.0)

Introduction: can enable the first login and then select the project, to avoid the selection of unauthorized projects and error and oauth strict verification need to configure the project and product parameter values.

Prerequisites:

• sbp >= 1.4.0
• Currently only platform accounts are allowed to log in
• If oauth turns on strong validation, you need to remove the validation for project and product

Standard process for using this feature:

1. Read the documentation to understand the basic oauth configuration process and configure it.
2. Configure the items associated with a user by default after it is created.oauth_login_projectsorenable_oauth_auto_login_all_projectseither.
3. Use the tool to enable Select Items after Login.

Additional configurations that may be used:

When modifying the above configuration, the following is an example:

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"

Note:

• When you select items after login, you need to configure as long as you enable automatic account creation configurationoauth_login_projectsorenable_oauth_auto_login_all_projects.
• Because you log in first and then select the project, it is no longer requiredoauth_client_config_mapconfiguration.

Use the tool to enable "Select Items after Login":

sbpadmin oauth_config -t open