Atmosphere 登入

@emdash-cms/auth-atproto 套件會為 EmDash 新增以 Atmosphere 帳號 登入的選項。Atmosphere 帳號是可攜的、使用者擁有的身分，可在 Bluesky 及 AT 協定網路上的其他應用程式間通用。使用者以控點（handle，例如 alice.bsky.social）登入，並在其身分提供者處完成驗證 —— EmDash 永遠不會看到密碼。

下列情境特別適合：

• 你的貢獻者已經擁有 Atmosphere 帳號。
• 你希望控管組織名下的網域（*.yourcompany.com），又不想維護 OAuth 應用程式或邀請制。
• 你正在建置屬於更廣泛 Atmosphere 生態的一部分，並希望與堆疊其餘部分維持一致的身分體系。

安裝

pnpm add @emdash-cms/auth-atproto

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { atproto } from "@emdash-cms/auth-atproto";

export default defineConfig({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // 本機開發必要 —— 見下方「本機開發」
			},
		}),
	],
});

上述設定便足以在登入頁與設定精靈顯示 以 Atmosphere 登入。若未設定任何允許清單，第一位註冊的使用者會成為管理員，之後對其他所有人關閉自助註冊 —— 請參閱允許清單以放寬限制。

無需設定環境變數、用戶端密鑰或註冊 OAuth 應用程式。此提供者為公開的 OAuth 用戶端，並在 /.well-known/atproto-client-metadata.json 提供自身的詮釋資料文件。

設定

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // 作者
});

完整角色階梯請見主要 驗證指南。

允許清單

若既未設定 allowedDIDs 也未設定 allowedHandles，則只有第一位使用者可以註冊 —— 任何其他人嘗試登入都會收到 signup_not_allowed 而被拒絕。已存在的使用者一律可以再次登入，與目前允許清單無關（因此把自己從清單移除不會把你鎖在外面，但也不會讓新使用者加入）。

當至少設定了一項允許清單時，使用者符合任一清單條件即可准入：

• DID 相符。 使用者的 DID 列於 allowedDIDs 中。DID 是密碼學識別碼，無法遷移或冒充，因此是最嚴格的門禁方式。
• 控點相符。 使用者的控點與 allowedHandles 中的某一項完全相同，或符合前導萬用字元模式（*.example.com 可同時符合 alice.example.com 與 bob.team.example.com）。

儘管控點可變更，控點允許清單仍然是安全的。在因控點相符而允許使用者進入之前，EmDash 會獨立解析該控點的 DNS/HTTP 紀錄，並驗證其是否指向身分提供者所聲稱的同一個 DID。行為異常的提供者不能憑空聲稱擁有 [email protected]。

預設角色

獲准使用者會取得你在 defaultRole 中設定的角色。只有完成網站初始設定的第一位使用者會被強制設為管理員。Atmosphere 帳號沒有群組／角色對應；若需要更細的角色，請在使用者至少登入一次後，到 設定 → 使用者 中調整。

第一位使用者設定

當你在全新網站上啟用了 Atmosphere 提供者，設定精靈會提供此選項以建立初始管理員帳號。

之後每次登入都走同一流程 —— 輸入控點、前往你的提供者、再跳回，即完成登入。

本機開發

AT 協定 OAuth 設定檔要求回環（loopback）重新導向 URI 必須使用 IP 字面量（127.0.0.1 或 [::1]），不能使用 localhost。EmDash 在產生重新導向 URI 時會透明地將 ://localhost 改寫為 ://127.0.0.1，但這表示你的開發工作階段也必須在 127.0.0.1 上啟動 —— 否則在 localhost 上設定的工作階段 cookie 在重新導向落到 127.0.0.1 後將無法被讀取。

Astro 的開發伺服器以 Vite 為基礎，而 Vite 預設繫結 localhost。請讓開發伺服器也監聽回環 IP：

export default defineConfig({
	server: {
		host: "127.0.0.1",
	},
	// ...
});

然後全程使用 http://127.0.0.1:4321/_emdash/admin 開啟管理後台。

生產環境

生產環境無需額外設定。此提供者在下列位址提供自身的用戶端詮釋資料：

https://your-site.example.com/.well-known/atproto-client-metadata.json

授權伺服器在登入過程中會擷取該 URL，以校驗用戶端的重新導向 URI。請確保部署站點的網站 URL 可透過公網 HTTPS 存取 —— 僅在 VPN 後的內網部署無法完成登入，因為使用者的授權伺服器無法取得該詮釋資料文件。

若 EmDash 執行在終止 TLS 的反向代理之後，請設定 siteUrl，以便 EmDash 產生正確的重新導向 URI。否則請求可能顯示為 http://internal-host:4321，詮釋資料將與授權伺服器所見不一致。

疑難排解

「帳號不在允許清單中」

你用於登入的控點或 DID 不在 allowedDIDs / allowedHandles 中。檢查萬用字元模式（必須以 *. 開頭），並記住控點相符會針對 DNS/HTTP 校驗 —— 若控點的 DID 紀錄目前解析到的 DID 與提供者回傳的不一致，相符會被拒絕。

「不允許自助註冊」

你已順利到達回呼，但未設定允許清單且你不是第一位使用者。請把自己加入 allowedDIDs/allowedHandles，或由現有管理員邀請你，使在你登入前使用者紀錄已存在。

登入後又跳回登入頁且沒有錯誤訊息

幾乎總是 本機開發 一節所述的回環 cookie 問題。在設定 server.host: "127.0.0.1" 後，使用 http://127.0.0.1:4321 開啟管理後台再試。

自架控點解析失敗

提供者會透過競速 DNS-over-HTTPS（Cloudflare 的 DoH 端點）與 HTTP /.well-known/atproto-did 查詢來驗證控點。自架控點至少需要滿足以下之一：

• _atproto.<控點> 的 DNS TXT 紀錄，內容為 did=<你的-did>，或
• https://<控點>/.well-known/atproto-did 檔案，內容為該 DID。

若兩種方式都失敗，即使底層帳號有效，控點相符也會被拒絕。allowedDIDs 中的 DID 不受影響 —— 它們直接相符。