給要把 Advantech 登入整合進既有系統、或要上正式環境的工程師：架構、要設定的項目、這個網站提供的所有函式庫與 API，以及哪些部分一定要自己開發。
登入由 SSO 負責，但「誰已經登入」是你的網站自己的 session 決定的。Client Secret 只能在你的後端。
| 元件 | 在哪裡 | 負責什麼 |
|---|---|---|
| 瀏覽器 | 使用者的電腦 | 顯示登入頁 / 按鈕 / 使用者名片 (advantech-sso.js)，只呼叫你網站的 /auth/*，拿不到任何密鑰。 |
| 你的後端 | 你的伺服器 | 保管 Client Secret、處理 /auth/login 與 /auth/callback、建立並檢查自己的 session、保護頁面與 API。 |
| Advantech SSO | https://ae-sso.advantech.com | 與 Microsoft 登入、跨服務單一登入、白名單 / 黑名單、整理使用者資料與大頭照、記錄登入。 |
| Microsoft Entra ID | login.microsoftonline.com | 驗證帳號密碼、MFA、條件式存取。你的網站不會直接接觸它。 |
你的網站發現他還沒登入。
你的後端 (/auth/login) 把瀏覽器導到 SSO，順便帶一個隨機的檢查碼 (state)。
SSO 檢查他是否已登入；沒有的話，才請 Microsoft 讓他輸入公司帳號密碼。
SSO 把瀏覽器導回 /auth/callback，附上一張一次性的「票」(code) 和剛才的檢查碼。
你的後端確認檢查碼一致，再用「票 + Client Secret」向 SSO 換到姓名、Email、部門等資料。這一步看不到瀏覽器，所以密碼是安全的。
你的後端把使用者資料存進自己的 session。之後的每個請求，只要看 session 就知道他是誰，不用再問 SSO。
advantech-sso.js 呼叫你的 /auth/me 取得目前使用者並顯示出來。
使用者實際上只會看到：打開網站 → (第一次) Microsoft 登入畫面 → 回到網站。其他步驟都在幾毫秒內自動完成。
| 項目 | 必要性 | 說明 |
|---|---|---|
| 新增服務 | 必要 | 取得 Client ID 與 Client Secret。服務者可以在後台「我的服務」自行申請。 |
| Redirect URI | 必要 | 每個會用到的網址都要登錄，正式與本機測試分開登錄，例如 https://myapp.advantech.world/auth/callback 與 http://localhost:5000/auth/callback。必須完全一致。 |
| 可存取的資料 | 建議 | 只開放網站真正需要的欄位 (例如部門、主管)。預設不含同主管成員與原始資料。 |
| 資料隱碼 | 選用 | 管理員可以把某些人的某些欄位用 * 遮住 (例如高階主管的手機)。欄位仍在，每一位使用者都附 masked 與 masked_fields 讓程式判斷；前端套件會自動把被遮的值標示為「已隱藏」。登入的本人看自己的資料不會被遮。 |
| 白名單 (允許) / 黑名單 (禁止) | 選用 | 限制哪些帳號或網域可以登入；被拒絕的人不會進到你的網站。 |
| 人員與群組 API 設備 | 選用 | 伺服器要在沒有人登入時查詢使用者 (排程、同步) 才需要，由最高管理者開啟與註冊設備。 |
| 項目 | 必要性 | 說明 |
|---|---|---|
| SSO_CLIENT_ID SSO_CLIENT_SECRET | 必要 | 從 SSO 取得。Secret 只放環境變數或密鑰管理服務，不放進程式碼、HTML 或 Git。 |
| APP_URL | 必要 | 你網站對外的網址 (協定 + 主機 + 連接埠)，用來組出 Redirect URI。使用者必須用這個網址開網站。 |
| FLASK_SECRET_KEY / SESSION_SECRET | 必要 | 簽署 session cookie 的金鑰，長度 32 位元組以上、固定不變；每次重啟都換會讓所有人被登出並出現 error=state。 |
| HTTPS | 必要 | 正式環境必須 https，session cookie 才能設成 Secure。本機測試只允許 http://localhost。 |
| Session 儲存位置 | 建議 | 範本的 Node / Go 版把 session 放記憶體，重啟就消失、多台伺服器不共用。正式環境請用 Redis 或資料庫。 |
| Cookie 設定 | 建議 | HttpOnly、Secure (https)、SameSite=Lax。不要用 SameSite=Strict，否則從 SSO 導回時帶不到 cookie。 |
| 對外連線 | 必要 | 你的後端要能用 https 連到 https://ae-sso.advantech.com (呼叫 /token、/userinfo)。 |
| Content-Security-Policy | 選用 | 有設定 CSP 時：script-src / style-src 加入 https://ae-sso.advantech.com (或自行存放檔案)，img-src 加入 https://ae-sso.advantech.com 以顯示大頭照。 |
| 時間同步 (NTP) | 選用 | 使用人員與群組 API 時，設備簽的 JWT 有效期間很短，伺服器時間誤差要在 1 分鐘內。 |
# .env (never commit this file) SSO_CLIENT_ID=svc_xxxxxxxx SSO_CLIENT_SECRET=xxxxxxxx APP_URL=https://myapp.advantech.world SESSION_SECRET=<64 random characters: openssl rand -hex 32>
以下檔案都可以直接用網址引用，或下載後放到自己的網站。網址固定、不會改名。
| 檔案 | URL | 說明 | |
|---|---|---|---|
| advantech-sso.js | https://ae-sso.advantech.com/assets/js/advantech-sso.js | 下載 | 登入按鈕、使用者名片、欄位顯示、未登入自動導向、多語言。無相依套件，約 10 KB。 |
| advantech-sso.css | https://ae-sso.advantech.com/assets/css/advantech-sso.css | 下載 | 登入頁、按鈕、使用者名片的樣式。所有 class 都以 adv-sso- 開頭，不會影響你的樣式。 |
| logo.svg | https://ae-sso.advantech.com/static/logo.svg | 下載 | Advantech 標誌 (藍底白字)。 |
| login.html | https://ae-sso.advantech.com/developers/files/login.html | 下載 | 完整的登入頁範本。 |
| index.html | https://ae-sso.advantech.com/developers/files/index.html | 下載 | 受保護頁面範本 (顯示姓名、部門、大頭照)。 |
正式環境建議下載 JS / CSS 放在自己的網站，避免 SSO 維護時影響你的頁面；直接引用則永遠是最新版。
| 語言 | 檔案 | 完整範本 | |
|---|---|---|---|
| Python / Flask | flask_app.py | 下載 | .zip |
| Node.js / Express | express_app.mjs | 下載 | .zip |
| PHP | sso.php | 下載 | .zip |
| C# / ASP.NET Core | Program.cs | 下載 | .zip |
| Java / Spring Boot | SsoController.java | 下載 | .zip |
| Go | main.go | 下載 | .zip |
後端不需要安裝 SSO 專用套件，只用各語言標準的 HTTP 與 session 功能 (Flask、Express、PHP curl、ASP.NET Core、Spring Boot、Go 標準函式庫)。
| API | 誰呼叫 | 驗證方式 | 說明 |
|---|---|---|---|
| GET /authorize | 瀏覽器 | — | 參數：client_id、redirect_uri (需與後台登錄的完全相同)、response_type=code、state (請用隨機值並在回來時比對) prompt → |
| POST /token | 你的後端 | Client ID + Secret | 表單參數：grant_type=authorization_code、code、redirect_uri、client_id、client_secret (也可用 HTTP Basic)。code 只能用一次，60 秒內有效。 |
| GET /userinfo | 你的後端 | Bearer access_token | 帶 Authorization: Bearer <access_token>，回傳使用者資料。access token 效期 1 小時。 |
| GET /userinfo/photo | 你的後端 | Bearer access_token | 使用者大頭照 (服務還需開放「大頭照」欄位)。 |
| GET /photo/{token} | 瀏覽器 | 網址內含簽章 (7 天) | 大頭照網址，可直接放進 <img src> (使用者沒有照片時不會出現) |
| GET /logout | 瀏覽器 | — | 登出 SSO。可加 ?redirect_uri= 回到已登錄網站的網址。 |
| GET /api/directory/… | 已註冊的設備 | 設備私鑰簽的 JWT | 用 Azure 物件 ID、UPN 或 Email 查詢一位使用者 (格式同 /userinfo，含服務可取得的主管、部屬、群組等)。 → |
在 /authorize 加上 prompt 參數，可以決定使用者這次登入要不要看到畫面、要不要重新輸入密碼。範本的 /auth/login?silent=1 就是 prompt=none。
| prompt | 使用者會看到什麼 | 什麼時候用 |
|---|---|---|
| (不加) | 已在任一服務登入過：直接通過，看不到任何畫面。沒登入過：Microsoft 登入畫面 (若 Microsoft 還記得他，可能也直接通過)。 | 一般的「登入」按鈕。 |
| none | 永遠不顯示畫面。已登入 SSO 就直接帶 code 回來；沒登入則回 error=login_required，沒有權限回 error=access_denied。 | 使用者打開網站時自動嘗試單一登入；失敗才顯示你的登入頁。 |
| select_account | Microsoft 的「選擇帳戶」畫面，可以選既有帳號 (通常不用打密碼) 或「使用其他帳戶」。 | 「切換帳號」按鈕、同一台電腦多人共用。 |
| login | 一定要重新輸入帳號密碼 (以及公司規定的 MFA)，就算已經登入過 SSO 或 Microsoft 也一樣。 | 敏感操作前再次確認身分 (例如簽核、修改權限、查看薪資)，或高敏感度的系統。 |
consent) 會被忽略，視同沒有加。select_account，避免直接變回同一個人。login_required / access_denied 只會在 prompt=none 時以錯誤回到你的 callback；其他情況使用者會在 SSO 或 Microsoft 的畫面上處理。# 不顯示畫面、只試試看能不能自動登入
https://ae-sso.advantech.com/authorize?client_id=svc_xxxxxxxx&redirect_uri=…&response_type=code&state=RANDOM&prompt=none
# 強制重新輸入密碼
https://ae-sso.advantech.com/authorize?client_id=svc_xxxxxxxx&redirect_uri=…&response_type=code&state=RANDOM&prompt=login
# 在範本的 /auth/login 加上 prompt
q["prompt"] = "login" # Python (/auth/login)
q.set("prompt", "login"); // Node.js
$q['prompt'] = 'login'; // PHP
| 參數 | 說明 |
|---|---|
| redirect_uri | 登出後要回到的網址，必須是已登錄服務的網址 (同一個網域)。 |
| microsoft=1 | 這次同時登出 Microsoft 帳號，下次一定要重新輸入密碼 (也會登出同瀏覽器的 Outlook、Teams 網頁版)。 |
| microsoft=0 | 這次只登出網站與 SSO，即使管理員開啟了「同時登出 Microsoft」。 |
| (不加) | 依管理員在「Azure AD 設定 → 登出行為」的設定 (預設只登出 SSO)。 |
SSO 與前端套件已經處理掉大部分工作；剩下的一定要在你的後端完成，原因是 Client Secret 與「誰能做什麼」只能由你的伺服器判斷。
| 功能 | 誰負責 | 說明 |
|---|---|---|
| 帳號密碼、MFA | SSO 提供 | 由 Microsoft 處理，你的網站永遠拿不到密碼。 |
| 跨服務單一登入 | SSO 提供 | 在任一服務登入後，其他服務自動通過 (範本的 /auth/login?silent=1)。 |
| 使用者資料、大頭照、主管 / 部屬 | SSO 提供 | 登入時一併回傳，欄位依服務的資料權限。 |
| 登入按鈕、登入頁、使用者名片 | 前端套件提供 | advantech-sso.js / .css 與 login.html。 |
| /auth/login | 你要開發 (範本已有) | 產生隨機 state、導到 SSO。 |
| /auth/callback | 你要開發 (範本已有) | 比對 state、用 code + Client Secret 呼叫 /token、建立 session。這一步一定在後端，因為需要 Client Secret。 |
| /auth/me | 你要開發 (範本已有) | 回傳目前使用者 JSON 給前端套件，未登入回 401。 |
| /auth/logout | 你要開發 (範本已有) | 清除你的 session，再導到 SSO 的 /logout。 |
| Session 管理 | 你要開發 (範本已有) | 有效期間、儲存位置、登入後換新 session id。 |
| 保護頁面與 API | 你要開發 (範本已有) | 每個需要登入的頁面與 API 都要在後端檢查 session；前端隱藏按鈕不算保護。 |
| 權限 (誰能做什麼) | 一定要自己開發 | SSO 只告訴你「他是誰」與部門、群組等屬性；例如「只有 AE 部門能編輯」這類規則必須在你的系統判斷。 |
| 你系統裡的使用者資料 | 一定要自己開發 | 若要存使用者 (例如設定、訂單)，用 sub 當主鍵，不要用 Email (會改名)。 |
| 更新使用者資料 | 選用 | 登入時的資料會留在 session；需要最新資料時，在 access_token 有效的 1 小時內呼叫 /userinfo，或讓使用者重新登入 (會自動通過)。 |
| 全部服務一起登出 | 選用 | 目前不支援。SSO 登出只結束 SSO 的狀態，各網站的 session 會在自己的期限後失效。 |
| 伺服器查詢使用者 (人員與群組 API) | 選用 | 需要時自行在設備上產生金鑰、簽 JWT 呼叫 /api/directory/*，範例在基本版的「人員與群組 API」。 |
Advantech Single Sign-On