EmDash情報局

検索

相談する

Atmosphereログイン

このページで分かること

  • @emdash-cms/auth-atproto をインストールしてAtmosphereアカウントでのログインを追加する方法と、向いている場合
  • DIDとハンドルの許可リスト、既定のロール、最初のユーザーの登録手順
  • ローカル開発で 127.0.0.1 を使う理由、本番で必要な条件、ログインできないときの対処
難易度
実践
読む時間
6分
前提知識
認証
このページの目次

@emdash-cms/auth-atproto パッケージは、EmDashにAtmosphereアカウントでのログインの選択肢を追加します。Atmosphereアカウントは、BlueskyをはじめとするAT Protocolのネットワーク上のアプリで使われる、持ち運べる、ユーザー自身が所有するIDです。ユーザーはハンドル（例：alice.bsky.social）でログインし、自分のプロバイダーで認証します。EmDashがパスワードを目にすることはありません。

この方法は、次のような場合に向いています。

  • 寄稿者がすでにAtmosphereアカウントを持っている。
  • OAuthアプリや招待を管理せずに、組織が管理するドメイン（*.yourcompany.com）で利用者を制限したい。
  • より広いAtmosphereの一部となるものを作っていて、ほかのシステムと一貫したIDを使いたい。

インストール

プロバイダーのパッケージをインストールします。

pnpm add @emdash-cms/auth-atproto

EmDashのインテグレーションにプロバイダーを追加します。

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

export default defineConfig({
	server: {
		host: "127.0.0.1", // required for local development; see below
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

これだけで、ログインページとセットアップウィザードに「Atmosphereでログイン」が表示されます。許可リストを設定していない場合、最初のユーザーが管理者になり、それ以降は全員の自己登録が閉じられます。登録を開放するには許可リストを参照してください。

このプロバイダーは公開OAuthクライアントで、自身のメタデータのドキュメントを /.well-known/atproto-client-metadata.json で配信します。そのため、上の設定だけで動作します。環境変数、クライアントシークレット、OAuthアプリの登録を用意する必要はありません。

本サイトの補足 やさしい解説

Atmosphereアカウントは、Blueskyなどで使われているアカウントのことです。WordPressの「ソーシャルログイン」のプラグインでは、各サービスでアプリを登録してキーを発行するのが一般的ですが、このプロバイダーではその作業が不要です。パッケージをインストールし、astro.config.mjs の authProviders に atproto() を追加すれば、ログインページに「Atmosphereでログイン」が表示されます。ユーザーは alice.bsky.social のようなハンドルを入力してログインします。

アクセスの設定

atproto() プロバイダーは、許可リストと既定のロールを受け付けます。

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // Author
});
オプション 型 既定値 説明
allowedDIDs string[] なし 完全一致で判定するDIDの許可リスト。
allowedHandles string[] なし ハンドルの許可リスト。先頭のワイルドカード（*.example.com）に対応しています。
defaultRole number 10（閲覧者） 2人目以降の許可されたユーザーに割り当てるロール。最初のユーザーは必ず管理者になります。

ロールの段階の全体は、メインの認証のガイドで説明しています。

許可リスト

allowedDIDs と allowedHandles のどちらも設定されていない場合、登録できるのは最初のユーザーだけです。すでにEmDashユーザーと連携しているアカウントは引き続きログインできますが、新しいアカウントは signup_not_allowed で拒否されます。

許可リストを1つ以上設定すると、既存のユーザーのログインも含め、すべてのログインがリストに一致する必要があります。設定したリストから既存のユーザーのDIDとハンドルを削除すると、そのアカウントはログインできなくなります。ユーザーは、どちらかのリストに一致すれば許可されます。

  • DIDが一致する場合：ユーザーのアカウントの変わらない識別子が、allowedDIDs の値のどれかと完全に一致します。
  • ハンドルが一致する場合：ユーザーのハンドルが、allowedHandles の項目と完全に一致するか、先頭のワイルドカードのパターンに一致します（*.example.com は alice.example.com と bob.team.example.com に一致します）。

ハンドルは変更できますが、ハンドルの許可リストは安全です。ハンドルの一致でユーザーを許可する前に、EmDashはハンドルのDNS／HTTPのレコードを独自に解決し、プロバイダーが主張するのと同じDIDを指していることを確認します。不正な動作をするプロバイダーが、you.yourcompany.com を持っていると主張するだけでは通りません。

既定のロール

許可されたユーザーには、defaultRole で設定したロールが割り当てられます。必ず管理者になるのは、最初のユーザー（セットアップを完了した人）だけです。Atmosphereアカウントには、グループとロールの対応づけの仕組みはありません。ロールを細かく分ける必要がある場合は、ユーザーが一度ログインしたあとで、「設定」→「ユーザー」からそのユーザーのロールを変更します。

本サイトの補足 やさしい解説

許可リストを設定しないと、ログインできるのは最初に登録した管理者（と、すでに連携済みのアカウント）だけです。ほかの人にも使わせるには、個人を指定する allowedDIDs か、*.example.com のように組織のドメインでまとめて指定する allowedHandles を設定します。許可された人は、初期状態では閲覧者（レベル10）として登録されるため、記事を書いてもらう場合は defaultRole を変えるか、ログイン後に管理画面でロールを変更します。

最初のユーザーの設定

Atmosphereプロバイダーを設定した状態で新しいサイトを始めると、セットアップウィザードは、最初の管理者アカウントを作成する選択肢の1つとしてこのプロバイダーを表示します。

  1. /_emdash/admin にアクセスします。「サイトをセットアップ」で、サイトのタイトルと、必要に応じてキャッチフレーズを入力し、先に進みます。

  2. 「アカウントを作成」で、EmDashのユーザーに保存するメールアドレスと、必要に応じて名前を入力します。

  3. 「アカウントを保護」で「Atmosphere」を選び、ハンドル（例：alice.bsky.social）を入力して、先に進みます。

  4. アカウントのプロバイダーの認可ページが開きます。そのプロバイダーが対応している方法でログインし、リクエストを承認します。

  5. プロバイダーがEmDashにリダイレクトします。EmDashは最初のユーザーを管理者として作成し、手順2のメールアドレスを保存し、EmDashのセッションを確立して、ダッシュボードを開きます。

2回目以降のログインは、ハンドルの入力から始まり、アカウントのプロバイダーでの認証を経て、EmDashのセッションを持って戻ってきます。プロバイダーのOAuthの状態とトークンは、そのEmDashのセッションとは別に保存されます。これにより、OAuthのコールバックが完了でき、プロバイダーは自身のセッションを更新できます。

ローカル開発

AT ProtocolのOAuthプロファイルは、ループバックのリダイレクトURIに localhost ではなくIPアドレスそのもの（127.0.0.1 または [::1]）を使うことを求めています。EmDashはリダイレクトURIを生成するときに ://localhost を ://127.0.0.1 に自動で書き換えます。ただしそのため、開発中のセッションも 127.0.0.1 で始める必要があります。そうしないと、localhost で設定されたセッションのCookieが、リダイレクトで 127.0.0.1 に戻ったあとに見えなくなります。

Astroの開発サーバーはViteを使っており、初期状態では localhost で待ち受けます。Astroの最上位の server.host オプションに、ループバックのIPアドレスを設定します。

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

そのうえで、手順全体を通して http://127.0.0.1:4321/_emdash/admin を開きます。

本サイトの補足 やさしい解説

ローカル開発で起きやすいつまずきです。多くのガイドでは開発中のサイトを http://localhost:4321 で開きますが、Atmosphereログインを試すときは http://127.0.0.1:4321 で開きます。localhost と 127.0.0.1 は同じパソコンを指しますが、ブラウザーは別のサイトとして扱うため、ログインの状態を保存するCookieが引き継がれません。astro.config.mjs の server.host を "127.0.0.1" にしておけば、開発サーバーもそのアドレスで起動します。

本番環境

本番環境でも同じ設定で動作します。プロバイダーは、自身のクライアントのメタデータを次の場所で配信します。

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

認可サーバーは、ログイン中にこのURLを取得して、クライアントのリダイレクトURIを確認します。デプロイしたサイトのURLに、公開インターネットからHTTPSでアクセスできることを確認してください。VPNの内側にある内部向けのデプロイでは、ユーザーの認可サーバーがメタデータのドキュメントを取得できないため、ログインを完了できません。

TLSを終端するリバースプロキシの後ろでEmDashを動かす場合は、EmDashが正しいリダイレクトURIを組み立てられるように、siteUrlを設定します。設定しないと、リクエストは http://internal-host:4321 のように見え、メタデータが認証サーバーから見える内容と一致しません。

トラブルシューティング

「Account is not in the allowlist」

ログインに使ったハンドルまたはDIDが、allowedDIDs／allowedHandles にありません。ワイルドカードのパターン（*. で始まる必要があります）を確認します。また、ハンドルの一致はDNS／HTTPで確認される点に注意します。ハンドルのDIDのレコードが、現在プロバイダーが返したものと同じDIDに解決されない場合、一致は拒否されます。

「Self-signup is not allowed」

コールバックまでは正常に到達しましたが、許可リストが設定されておらず、最初のユーザーでもありません。そのアカウントのDIDを allowedDIDs に、または確認済みのハンドルを allowedHandles に追加します。メールでの招待では、AtmosphereのDIDはEmDashのユーザーと連携されません。

ログインするとエラーなしでログインページに戻される

ほとんどの場合、ローカル開発で説明したループバックのCookieの問題です。（server.host: "127.0.0.1" を設定したうえで）http://127.0.0.1:4321 で管理画面を開き、もう一度試します。

自己ホストのハンドルの解決に失敗する

プロバイダーは、DNS-over-HTTPS（CloudflareのDoHのエンドポイント）と、HTTPでの /.well-known/atproto-did の検索を同時に実行し、先に返ったほうでハンドルを確認します。自己ホストのハンドルには、次のうち少なくとも1つが必要です。

  • did=<your-did> を含む、_atproto.<handle> のDNSのTXTレコード
  • DIDを含む、https://<handle>/.well-known/atproto-did のファイル

両方の方法で失敗すると、元のアカウントが有効であっても、ハンドルの一致は拒否されます。allowedDIDs のDIDは直接照合されるため、影響を受けません。

訳の誤りを報告する