E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

Atmosphere ログイン

このページ

@emdash-cms/auth-atproto パッケージは、EmDash に Atmosphere アカウント でのログインオプションを追加します。Atmosphere アカウントは、Bluesky をはじめとする AT Protocol ネットワーク上のさまざまなアプリで使用される、ポータブルでユーザー所有のアイデンティティです。ユーザーはハンドル（例：alice.bsky.social）でサインインし、自分のプロバイダーで認証します — EmDash がパスワードを目にすることはありません。

次のような場合に適しています。

  • コントリビューターがすでに Atmosphere アカウントを持っている。
  • OAuth アプリや招待を管理せずに、組織が管理するドメイン（*.yourcompany.com）へのアクセスを制限したい。
  • より広い Atmosphere の一部となるものを構築していて、スタックの他の部分と一貫したアイデンティティを使いたい。

インストール

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

pnpm add @emdash-cms/auth-atproto

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

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()],
		}),
	],
});

これだけで、ログインページとセットアップウィザードに Sign in with Atmosphere が表示されます。許可リストが設定されていない場合、最初のユーザーが Admin になり、それ以降は全員のセルフサインアップが閉じられます — 開放するには許可リストを参照してください。

このプロバイダーはパブリック OAuth クライアントであり、自身のメタデータドキュメントを /.well-known/atproto-client-metadata.json で提供します。そのため、上記の設定だけで動作します — 設定すべき環境変数、クライアントシークレット、OAuth アプリの登録はありません。

アクセスの設定

atproto() プロバイダーは、許可リストとデフォルトロールを受け取ります。

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // Author
});
オプション型デフォルト説明
allowedDIDsstring[]なしDID の完全一致による許可リスト。
allowedHandlesstring[]なしハンドルの許可リスト。先頭のワイルドカード（*.example.com）に対応します。
defaultRolenumber10（Subscriber）最初のユーザー以降の許可されたユーザーに割り当てられるロール。最初のユーザーは常に Admin です。

完全なロール階層は、メインの認証ガイドに記載されています。

許可リスト

allowedDIDs も allowedHandles も設定されていない場合、サインアップできるのは最初のユーザーだけです。すでに EmDash ユーザーにリンクされているアカウントは引き続きサインインできますが、新しいアカウントは signup_not_allowed で拒否されます。

少なくとも 1 つの許可リストが設定されている場合、既存ユーザーを含むすべてのログインがそのリストに一致する必要があります。既存ユーザーの DID とハンドルを設定済みのリストから削除すると、そのアカウントはサインインできなくなります。ユーザーは、いずれかのリストに一致すれば許可されます。

  • DID の一致。 ユーザーの安定したアカウント識別子が、allowedDIDs の値と完全に一致する。
  • ハンドルの一致。 ユーザーのハンドルが、allowedHandles のエントリと完全一致、または先頭ワイルドカードのパターンで一致する（*.example.com は alice.example.com と bob.team.example.com に一致します）。

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

デフォルトロール

許可されたユーザーには、defaultRole で設定したロールが付与されます。強制的に Admin になるのは、最初のユーザー（セットアップを完了したユーザー）だけです。Atmosphere アカウントにはグループとロールのマッピングがありません。より細かいロールが必要な場合は、ユーザーが一度ログインした後に、管理画面のサイドバーにある Users ページでそのユーザーのロールを変更してください。

最初のユーザーのセットアップ

Atmosphere プロバイダーを設定した状態で新しいサイトを起動すると、セットアップウィザードで、最初の管理者アカウントを作成するオプションとして Atmosphere が表示されます。

  1. /_emdash/admin にアクセスします。Set up your site で、サイトタイトルと、必要に応じてキャッチフレーズを入力し、続行します。

  2. Create your account で、EmDash ユーザーに保存するメールアドレスと、必要に応じて名前を入力します。

  3. Secure your account で Atmosphere を選択し、ハンドル（例：alice.bsky.social）を入力して続行します。

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

  5. プロバイダーから EmDash にリダイレクトされます。EmDash は最初のユーザーを Admin として作成し、手順 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 に設定します。

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 の内側にある社内専用のデプロイでは、ユーザーの認可サーバーがメタデータドキュメントを取得できないため、ログインを完了できません。

TLS を終端するリバースプロキシの背後で EmDash を実行している場合は、siteUrl を設定して、EmDash が正しいリダイレクト URI を構築できるようにします。これがないと、リクエストは http://internal-host:4321 のように見え、メタデータは認可サーバーが見るものと一致しません。

トラブルシューティング

”Account is not in the allowlist”

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

“Self-signup is not allowed”

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

エラーなしでログインページにリダイレクトされる

これはほとんどの場合、ローカル開発で説明されているループバック Cookie の問題です。http://127.0.0.1:4321（server.host: "127.0.0.1" を設定した後）で管理画面を開いて再試行してください。

セルフホストハンドルのハンドル解決が失敗する

プロバイダーは、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 は影響を受けません — 直接照合されるためです。