登入與密碼

設定

決定大家如何登入：密碼長度、家用網路的免登入捷徑，以及外部登入。只有擁有者可以在 Settings > Sign-in and security（設定 > 登入與安全性）變更這些項目。

設定最短密碼長度

開啟 Settings > Sign-in and security > Passwords（密碼）。
輸入 4 到 64 之間的數字。預設是 8。
按下 Save（儲存）。重新載入後，你應該會看到新的數字仍然保留。

這個最小長度適用於每一個新密碼：第一位擁有者、接受邀請的成員、在 My account（我的帳號）所做的變更，以及 holyarrs reset-owner。現有的密碼會繼續有效，直到下次變更。密碼最長是 1024 個字元。

在我的區域網路免登入

家用網路上的裝置開啟 HolyArrs 時，會直接以擁有者身分進入，不需要密碼。預設為關閉。

開啟 Settings > Sign-in and security > Local network（區域網路）。
列出你的網路，一行一個，最多 32 個。可以用範圍（192.168.1.0/24、fd00::/8），也可以用單一位址（192.168.1.20）。
開啟開關並儲存。你應該會在卡片上看到自己的位址。

清單是空的時候，或是存在任何兒童帳號時，都無法開啟這個開關。建立 API 金鑰、變更登入設定、讀取或替換機密資料，以及還原 backup，仍然需要輸入密碼。

先檢查位址

有些環境會讓每台裝置看起來都來自同一個閘道位址：Docker Desktop、rootless Docker 或 Podman，以及 Kubernetes NodePort。常見的有 172.17.0.1、172.18.0.1 及更高、10.88.0.1、10.89.x.1、10.0.2.2 和 192.168.65.x。

如果你列出其中一個，任何能連到 HolyArrs 的人都會以擁有者身分進入。當某個項目看起來像這類位址時，卡片會顯示警告。用第二台裝置開啟這個頁面：如果顯示的位址相同，就關閉開關，並移除那個項目。

在 reverse proxy 後面時，HolyArrs 只會讀取來自 HOLYARRS_TRUSTED_PROXIES 內 proxy 的轉送位址。否則卡片不會顯示位址，並說明這個 proxy 不受信任。

Single Sign-on

可以讓一個 OpenID Connect 提供者負責登入。它會在登入頁面顯示為一個按鈕。

開啟 Settings > Sign-in and security > Single sign-on（單一登入）。
輸入提供者的 issuer，然後按下 Test（測試）。測試不會傳送任何機密資料。
輸入 client id 和 client secret。如果提供者不使用 secret，請勾選 Public client（公開 client）。
複製 Callback address（回呼位址），並在提供者那邊註冊這個完全相同的位址。
輸入你的密碼，如果你有使用兩步驟驗證，也輸入驗證碼，然後按下 Save。每次變更都會要求這個步驟。

接著連結你自己的帳號：用密碼登入，開啟 My account，在 Linked sign-ins（已連結的登入方式）下按下 Link（連結），確認你的密碼，然後選擇 Single sign-on。

選項

讓新使用者透過 Single Sign-on 加入

預設為關閉。開啟後，只要是提供者讓登入的人都會得到一個帳號，所以 HolyArrs 會要你確認。新加入的人是只能提出請求的成員。Single Sign-on 絕不會產生擁有者或管理員。

變更 issuer 或 client id

你要重新輸入 secret。舊的連結會被移除，所有用過 Single Sign-on 的人都會登出。他們要從 My account 重新連結。關閉 Single Sign-on 也會讓他們登出。

解除連結登入方式

自己的：My account > Linked sign-ins > Unlink（解除連結）。需要最近確認過密碼，如果這是你唯一的登入方式，就會被拒絕。
任何人的：擁有者使用 Settings > Users and roles（設定 > 使用者與角色）。如果這是對方唯一的登入方式，HolyArrs 會再問一次。

解除連結會讓用過它的裝置登出。如果開放加入，同一個人可以再以新成員的身分回來。關閉加入功能就能擋住他們。

如果沒有成功

症狀： HolyArrs 再次要求輸入密碼。 原因： 變更帳號、金鑰和設定，需要最近 10 分鐘內確認過密碼，如果有設定兩步驟驗證也要通過。外部登入和區域網路捷徑不算在內。 解決方式： 用你的密碼確認。登出和結束裝置的登入從來不會要求確認。

症狀： 回呼失敗，出現一段簡短的錯誤，而你仍是登出狀態。 原因： 提供者那邊的回呼位址和 HolyArrs 的不一樣。 解決方式： 再複製一次 Callback address，並原封不動貼到提供者那邊。

症狀： 透過 Single Sign-on 建立的帳號無法設定密碼。 原因： 這個版本不支援。 解決方式： 先建立本機擁有者，再把 Single Sign-on 連結到它。

症狀： 從 HolyArrs 登出後，你在提供者那邊仍是登入狀態。 原因： HolyArrs 只會結束它自己的登入。 解決方式： 在共用的裝置上，也要在提供者那邊登出。

忘了擁有者密碼？請見工作階段與密碼。

給進階使用者

受信任 proxy 登入

如果 reverse proxy 已經負責讓人登入，HolyArrs 會接受它傳來的名稱。只能在環境變數中設定。它會在登入頁面顯示為一個按鈕；只憑 header，單純造訪頁面絕不會讓任何人登入。

proxy 要移除傳入的 Remote-User 和 Remote-Name，並在登入後設定它自己的。
Remote-User：一個固定不變的名稱，最多 255 bytes。Remote-Name：選用的顯示名稱，最多 200 bytes。
重複、以逗號串接或含有控制字元的值都會被拒絕。角色 header 會被忽略。

請讓 HolyArrs 只能透過那個 proxy 連線。信任一個 proxy 位址，就等於信任它傳來的每一個名稱。從 My account > Link trusted proxy sign-in（連結受信任 proxy 登入）把它連結到帳號。

環境變數

請在啟動前設定這些變數。兩種方式預設都是關閉，需要開啟才會生效。設定錯誤會讓 HolyArrs 無法啟動；提供者當機時，密碼登入仍可使用。只要設定了 HOLYARRS_OIDC_ENABLED，即使設成 false，Single Sign-on 就由環境變數掌管，Settings 只會顯示內容。

變數	作用	預設
`HOLYARRS_OIDC_ENABLED`	開啟 Single Sign-on	`false`
`HOLYARRS_OIDC_ISSUER`	提供者確切的 HTTPS issuer	無
`HOLYARRS_OIDC_CLIENT_ID`	已註冊的 client id	無
`HOLYARRS_OIDC_CLIENT_SECRET_FILE`	存放 client secret 的檔案，最多 4096 bytes。公開 client 請省略	無
`HOLYARRS_OIDC_REDIRECT_URL`	確切的 HTTPS 回呼位址：你的位址、URL base（如果有），然後是 `/api/v1/auth/oidc/callback`	無
`HOLYARRS_OIDC_ALLOW_JOIN`	新使用者以只能提出請求的成員身分加入	`false`
`HOLYARRS_OIDC_ALLOW_LOCAL_NETWORK`	允許位於你私有網路的提供者	`false`
`HOLYARRS_OIDC_ALLOW_LOOPBACK_HTTP`	允許在 loopback 使用純 HTTP，供測試用	`false`
`HOLYARRS_FORWARD_AUTH_ENABLED`	開啟受信任 proxy 登入	`false`
`HOLYARRS_FORWARD_AUTH_ISSUER`	這個 proxy 固定不變的 HTTPS 名稱。換成新的值會被視為新的來源	無
`HOLYARRS_FORWARD_AUTH_TRUSTED_PEERS`	以逗號分隔的 proxy 位址或範圍。必填。涵蓋所有位址的範圍會被拒絕	無
`HOLYARRS_FORWARD_AUTH_ALLOW_JOIN`	新的 proxy 名稱以只能提出請求的成員身分加入	`false`

ALLOW_LOCAL_NETWORK 和 ALLOW_LOOPBACK_HTTP 這兩個設定，也適用於在 Settings 中設定的 Single Sign-on。

Single Sign-on 如何運作

提供者必須支援使用 PKCE S256 和 RS256 token 的 authorization code 登入，而且每個 endpoint 都在 issuer 的 origin 上。
帳號以提供者自己的帳號 id 比對，絕不用 email。
不會使用提供者的角色和群組。
client secret 會加密儲存，之後不會再顯示。欄位留空就是保留原本的。