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로 거부됩니다.

허용 목록이 하나 이상 설정되어 있으면 기존 사용자를 포함해 모든 로그인이 그 목록과 일치해야 합니다. 기존 사용자의 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 프로바이더가 구성된 상태로 새 사이트를 시작하면, 설정 마법사가 초기 관리자 계정을 만드는 옵션으로 이를 제공합니다.

  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 개발 서버는 기본적으로 localhost에 바인딩되는 Vite를 사용합니다. 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 사용자에 연결되지 않습니다.

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

이는 거의 항상 로컬 개발에서 설명한 루프백 쿠키 문제입니다. 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는 직접 일치시키므로 영향을 받지 않습니다.