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", // 로컬 개발에 필수; 아래 참조
	},
	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, // 저자
});
옵션타입기본값설명
allowedDIDsstring[]없음정확한 DID 허용 목록.
allowedHandlesstring[]없음핸들 허용 목록. 선행 와일드카드(*.example.com)를 지원.
defaultRolenumber10 (Subscriber)첫 번째 이후 허용된 사용자에게 할당되는 역할. 첫 번째 사용자는 항상 Admin.

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

허용 목록

allowedDIDs와 allowedHandles 모두 설정되지 않으면 첫 번째 사용자만 가입할 수 있습니다. 이미 EmDash 사용자에 연결된 계정은 계속 로그인할 수 있지만, 새 계정은 signup_not_allowed로 거부됩니다.

하나 이상의 허용 목록이 설정되면, 기존 사용자의 로그인을 포함하여 모든 로그인이 일치해야 합니다. 설정된 목록에서 기존 사용자의 DID와 핸들을 제거하면 해당 계정의 로그인이 차단됩니다. 사용자는 어느 하나의 목록이 일치하면 허용됩니다:

  • DID 일치. 사용자의 안정적인 계정 식별자가 allowedDIDs의 값과 정확히 일치.
  • 핸들 일치. 사용자의 핸들이 allowedHandles의 항목과 정확히 또는 선행 와일드카드 패턴(*.example.com은 alice.example.com과 bob.team.example.com에 일치)으로 일치.

핸들 허용 목록은 핸들이 변경 가능해도 안전합니다. 핸들 일치로 사용자를 허용하기 전에, EmDash는 핸들의 DNS/HTTP 레코드를 독립적으로 확인하고 프로바이더가 주장하는 것과 동일한 DID를 가리키는지 검증합니다. 악의적인 프로바이더는 you.yourcompany.com을 소유하고 있다고 단순히 주장할 수 없습니다.

기본 역할

허용된 사용자는 defaultRole에 설정된 역할로 들어옵니다. 설정을 완료한 첫 번째 사용자만 Admin으로 강제됩니다. 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 세션을 설정하고 대시보드를 엽니다.

이후 로그인은 핸들로 시작하여 계정 프로바이더에서 계속되고 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에 설정된 세션 쿠키가 리디렉트로 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로 확인되지 않으면 일치가 거부됩니다.

”Self-signup is not allowed”

콜백에 성공적으로 도달했지만, 허용 목록이 설정되지 않았고 첫 번째 사용자가 아닙니다. 계정의 DID를 allowedDIDs에 추가하거나 확인된 핸들을 allowedHandles에 추가하세요. 이메일 초대는 Atmosphere DID를 EmDash 사용자에 연결하지 않습니다.

로그인이 오류 없이 로그인 페이지로 리디렉션됨

이는 거의 항상 로컬 개발에서 설명된 루프백 쿠키 문제입니다. http://127.0.0.1:4321(server.host: "127.0.0.1" 설정 후)에서 관리자를 열고 다시 시도하세요.

셀프 호스팅 핸들의 핸들 확인 실패

프로바이더는 DNS-over-HTTPS(Cloudflare의 DoH 엔드포인트)와 HTTP /.well-known/atproto-did 조회를 경쟁시켜 핸들을 확인합니다. 셀프 호스팅 핸들은 최소한 다음 중 하나가 필요합니다:

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

두 방법 모두 실패하면, 기본 계정이 유효하더라도 핸들 일치가 거부됩니다. allowedDIDs의 DID는 영향을 받지 않습니다 — 직접 대조됩니다.