獨立登入

login 能力讓 App 擁有自己的工作階段。當同一個主機名稱有可用的 DSM id cookie 時，App 會把它換成 App 工作階段。否則會顯示登入頁，向 DSM 檢查帳號、密碼與 OTP 驗證碼。App 不會儲存密碼或 OTP 驗證碼。它不需要管理員設定，NAS 上也不需要 Node.js。

它用來辨識使用者，並不會讓 App 取得 File Station 工作階段：請見檔案。

加入

新專案（預設 UI 為 Vue）：

synopkgland init -t native-go --with login my-login

既有專案：

synopkgland add login

兩者都會在 dsm-package.yaml 設定：

capabilities:
  identity: standalone

standalone 是唯一可用的值。

組合	結果
Plain UI（`--ui plain`，沒有 `ui.build`）	不支援。`check` 會回報 `CAPABILITY_COMBINATION_INVALID`，`init` 會拒絕
binary 後端	`CAPABILITY_UNSUPPORTED`
`armv7`	允許

登入開啟且沒有工作階段時，產生的 Vue App 會顯示登入頁。該頁面在瀏覽器中需要 HTTPS。

使用

使用者如何進入

DSM cookie。 若瀏覽器送出有效的 DSM id cookie，後端會透過 DSM 原生的 authenticate.cgi 驗證，保留瀏覽器的用戶端位址，並發出 App 工作階段。這需要 HTTPS。cookie 屬於主機名稱而不是連接埠，所以同一主機名稱其他連接埠上的 App 也會收到 cookie。IP 位址與 DNS 名稱是不同的主機名稱。不能假設跨站的 frame 會收到 DSM cookie。
登入頁。 沒有可用的 DSM cookie 時，使用者輸入 DSM 帳號與密碼。若 DSM 要求第二道驗證，頁面會要求輸入 OTP 驗證碼，並再次送出請求。後端會登入 DSM 一次以證明身分，然後立即結束該 DSM 工作階段，絕不保留。

帳號被停用、密碼錯誤，以及不被允許登入的帳號，會以不同的錯誤碼拒絕，請見疑難排解。

App 工作階段允許什麼

App 工作階段用來辨識使用者。除了 app.status 與 greeting.get 之外，後端對每個方法都會再次檢查：同一位使用者必須帶有有效的 DSM id cookie。沒有它的請求會以 session_revalidation_required 失敗，檔案與背景工作匯入方法則是 dsm_session_required。屬於其他使用者的 cookie 會結束工作階段。所以只用密碼登入時，只能使用那兩個方法。要使用其他方法，使用者還必須在相同的主機名稱登入 DSM。

每次成功的檢查，都會把工作階段延長整個存活時間。

呼叫

全部都是 public route，且需要同源的 JSON POST。

方法	參數	結果
`identity.status`	`{}`	`{ enabled: true }`
`identity.session`	`{ bootstrap?: boolean }`	`{ user, uid, expiresAt }`。有 `bootstrap` 且沒有 App cookie 時，會交換 DSM cookie（僅限 HTTPS）。原生工作階段驗證也會轉送 DSM 視窗提供的 `X-SYNO-TOKEN`
`identity.login`	`{ account, password, otp? }`	`{ user, uid, expiresAt }`（僅限 HTTPS）
`identity.logout`	`{}`	`{ loggedOut: true }` 並清除 cookie

@synopackageland/sdk/vue 的 createSession(ctx) 包裝了它們，會回傳 enabled、ready、subject、notice、start、call、login、bootstrap、logout 與 dispose。呼叫你自己的方法時，請像產生的 App.vue 一樣，使用 session.call(method, params) 而不是 ctx.call。

限制

項目	值
傳輸	`identity.login` 與 DSM cookie 交換需要 HTTPS
工作階段存活時間	15 分鐘，每次成功的 DSM cookie 檢查會延長
工作階段 cookie	`spl_session_<16 位十六進位數字>`，HttpOnly、Secure、SameSite=Lax，限定在 App 的路徑
登入嘗試	每分鐘每個帳號 5 次、每個用戶端位址 20 次。每次嘗試都會計入
工作階段數	最多 4096
DSM 回應時間	10 秒
接受的憑證長度	帳號最多 1024 個字元、密碼 4096、OTP 128
請求	僅限同源。Origin 的配置、主機與連接埠必須相符

若帳號或其 DSM 資料變更，使得使用者名稱不再解析到相同的 UID，工作階段就會結束。

疑難排解

錯誤碼	原因	解法
`https_required`	在一般 HTTP 下登入或交換 DSM cookie	以 HTTPS 開啟 App
`invalid_credentials`	帳號或密碼錯誤	再試一次
`account_disabled`	DSM 帳號已停用	使用其他帳號
`otp_required`	DSM 要求第二道驗證	在 `otp` 傳送 OTP 驗證碼
`login_not_permitted`	DSM 因其他原因拒絕登入	檢查帳號與其在 DSM 的登入設定
`rate_limited`	一分鐘內該帳號已嘗試 5 次，或該位址已嘗試 20 次	等待一分鐘
`cross_origin`	請求來自其他來源	從 App 頁面呼叫，不要從其他網站
`origin_required`	POST 請求沒有 `Origin` 也沒有 `Referer`	用目前版本的瀏覽器重新開啟 App
`session_required`	沒有 App 工作階段、已過期，或 DSM cookie 不相符	重新登入
`session_revalidation_required`	方法需要 DSM `id` cookie，而瀏覽器沒有送出	在相同的主機名稱登入 DSM，然後重試
`dsm_session_required`	同上，適用於 `nas.*`、`bg.browse` 與 `bg.jobs.submit`	在相同的主機名稱登入 DSM
`auth_unavailable`	無法詢問 DSM，或已有 4096 個工作階段	稍後重試

錯誤碼的說明請見錯誤碼。若要讓某些使用者無法進入 App，請依原生 App所述使用 entry。

獨立登入

加入

使用

使用者如何進入

App 工作階段允許什麼

呼叫

限制

疑難排解

相關