本文件所描述的內容屬於神策分析的高級使用功能，涉及較多技術細節，適用於對相關功能有經驗的用戶參考。如果對文件內容有疑惑，請諮詢您的數據諮詢顧問取得一對一的協助。

神策分析從 1.6.5 版開始支援透過 OAuth2.0 進行登入，大致登入流程如下：

1. 用戶打開神策分析登入頁面，點擊 “OAuth 登入” 按鈕（僅設定後才有該按鈕），瀏覽器會跳轉到設定的登入頁面（第三方登入頁面，如企業內的權限系統）
2. 用戶使用該權限系統的用戶名密碼或其他方式完成驗證登入，登入成功後，頁面將跳轉回神策分析頁面並以權限系統上設定的用戶資訊給予用戶在神策分析上的權限

實作 OAuth2.0 登入有如下要求：

1. 第三方權限系統支援 OAuth 2.0 Authentication Code 方式授權
2. 第三方權限系統可以根據 Access Token 取得用戶資訊（用戶名和在神策某個專案中的角色）

1. 設定資訊

如需設定 OAuth2.0 登入，需要提供如下設定資訊：

一個完整的設定範例如下：

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 並加上 project 和 oauth_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 介面定義：

2.4.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",
 "user_cname":"小明",
 "role":"analyst"
}

username 的值為用戶在神策中的登入用戶名，是登入時的必須欄位，該值不能存在中文字元及其他特殊字元，可以為信箱格式或純數字；

user_cname 的值為用戶在神策中的顯示用戶名，是可選值，如果不回傳時會和 username 保持一致。

role 欄位為在神策中的角色，是可選欄位。role 可取值為 admin（管理員），analyst（分析師） 和 guest（普通用戶）, 若取其他值則依普通用戶處理，用戶角色描述請見 成員與角色。若回傳欄位有值，那麼設定該用戶角色為該值對應角色，然後登入；

當沒有回傳 role 欄位時：若該用戶名在神策中已存在，那麼使用其之前的角色；若該用戶不存在，則角色是普通用戶。

如果回傳的 JSON 中沒有 username 欄位，則認為用戶不存在，即如果該用戶在神策系統沒有權限，直接回傳空 JSON 即可。

2.4.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 介面回傳的用戶名和角色使用神策系统