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

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, // Author
});

전체 역할 체계는 주 인증 가이드에 문서화되어 있습니다.

허용 목록

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에 설정한 역할을 받습니다. 설정을 완료하는 첫 사용자만 Admin으로 고정됩니다. Atmosphere 계정에 대한 그룹/역할 매핑은 없습니다. 더 세밀한 역할이 필요하면 한 번 로그인한 뒤 설정 → 사용자에서 변경하세요.

첫 사용자 설정

Atmosphere 프로바이더를 구성한 채로 새 사이트를 시작하면 설정 마법사에서 초기 관리자 계정 생성 옵션으로 제공됩니다.

이후 모든 로그인도 같은 흐름입니다 — 핸들 입력, 프로바이더로 리다이렉트, 돌아오면 로그인 완료.

로컬 개발

AT Protocol OAuth 프로필은 루프백 리다이렉트 URI에 localhost가 아닌 IP 리터럴(127.0.0.1 또는 [::1])을 요구합니다. EmDash는 리다이렉트 URI를 만들 때 ://localhost를 투명하게 ://127.0.0.1로 바꾸므로, 개발 세션도 127.0.0.1에서 시작해야 합니다. 그렇지 않으면 localhost에 설정된 세션 쿠키가 리다이렉트 후 127.0.0.1에서 보이지 않습니다.

Astro 개발 서버는 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 뒤의 내부 전용 배포는 사용자 인증 서버가 메타데이터 문서를 가져올 수 없어 로그인을 완료할 수 없습니다.

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”

콜백은 성공했지만 허용 목록이 없고 첫 사용자도 아닙니다. allowedDIDs/allowedHandles에 자신을 추가하거나, 기존 관리자가 초대해 로그인 시 사용자가 이미 존재하도록 하세요.

오류 없이 로그인 페이지로 리다이렉트됨

거의 항상 로컬 개발에 설명된 루프백 쿠키 문제입니다. server.host: "127.0.0.1"을 설정한 뒤 관리자를 http://127.0.0.1:4321에서 여세요.

자체 호스팅 핸들에서 핸들 확인 실패

프로바이더는 DNS over HTTPS(Cloudflare DoH)와 HTTP /.well-known/atproto-did 조회를 경쟁시켜 핸들을 검증합니다. 자체 호스팅 핸들에는 다음 중 하나 이상이 필요합니다.

• DNS TXT 레코드 _atproto.<handle>에 did=<your-did> 포함, 또는
• https://<handle>/.well-known/atproto-did 파일에 DID 포함.

둘 다 실패하면 기본 계정이 유효해도 핸들 일치는 거부됩니다. allowedDIDs의 DID는 영향받지 않으며 직접 비교됩니다.