인증

인증 및 승인은 웹사이트 또는 앱에 대한 액세스를 관리하는 두 가지 보안 프로세스입니다. 인증은 방문자의 신원을 확인하는 반면, 승인은 보호 구역 및 자원에 대한 접근 권한을 부여합니다.

인증을 사용하면 사이트의 특정 영역을 로그인한 개인에 맞춰 사용자 정의할 수 있으며 개인 정보 또는 비공개 정보를 최대한 보호할 수 있습니다. 인증 라이브러리 (예: Lucia Auth, Auth.js, Clerk)는 이메일 로그인 및 OAuth 공급자와 같은 다양한 인증 방법을 위한 유틸리티를 제공합니다.

팁

Astro에 대한 공식 인증 솔루션은 없지만 통합 디렉터리에서 커뮤니티 “인증” 통합을 찾을 수 있습니다.

이러한 백엔드 서비스에 대한 전용 가이드에서 Supabase로 인증을 추가하거나 Firebase로 인증을 추가하는 방법을 알아보세요.

Auth.js

섹션 제목: Auth.js

Auth.js는 프레임워크에 구애받지 않는 인증 솔루션입니다. Astro용 커뮤니티 프레임워크 어댑터 auth-astro를 사용할 수 있습니다.

설치

섹션 제목: 설치

선호하는 패키지 관리자로 astro add 명령을 사용하여 auth-astro 통합을 추가하세요.

npm

npx astro add auth-astro

pnpm

pnpm astro add auth-astro

Yarn

yarn astro add auth-astro

수동 설치

섹션 제목: 수동 설치

auth-astro를 수동으로 설치하려면 패키지 관리자로 필요한 패키지를 설치하세요.

npm

npm install auth-astro @auth/core@^0.18.6

pnpm

pnpm add auth-astro @auth/core@^0.18.6

Yarn

yarn add auth-astro @auth/core@^0.18.6

그런 다음 integrations 속성을 사용하여 astro.config.* 파일에 통합을 적용합니다.

astro.config.mjs

import { defineConfig } from 'astro/config';
import auth from 'auth-astro';

export default defineConfig({
  // ...
  integrations: [auth()],
});

구성

섹션 제목: 구성

프로젝트의 루트 디렉터리에 auth.config.mjs 파일을 생성합니다. 필요한 환경 변수와 함께 지원하려는 인증 공급자 또는 메서드를 추가하세요.

auth.config.mjs

import GitHub from '@auth/core/providers/github';
import { defineConfig } from 'auth-astro';

export default defineConfig({
  providers: [
    GitHub({
      clientId: import.meta.env.GITHUB_CLIENT_ID,
      clientSecret: import.meta.env.GITHUB_CLIENT_SECRET,
    }),
  ],
});

아직 존재하지 않는 경우 프로젝트 루트에 .env 파일을 생성합니다. 다음 두 가지 환경 변수를 추가합니다. AUTH_SECRET은 최소 32자의 비공개 문자열이어야 합니다.

.env

AUTH_TRUST_HOST=true
AUTH_SECRET=<my-auth-secret>

사용

섹션 제목: 사용

script 태그 또는 클라이언트 측 프레임워크 컴포넌트에서 auth-astro/client 모듈을 사용하여 로그인 및 로그아웃 버튼을 추가할 수 있습니다.

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
---
<Layout>
  <button id="login">Login</button>
  <button id="logout">Logout</button>

  <script>
    const { signIn, signOut } = await import("auth-astro/client")
    document.querySelector("#login").onclick = () => signIn("github")
    document.querySelector("#logout").onclick = () => signOut()
  </script>
</Layout>

getSession 메서드를 사용하여 사용자 세션을 가져올 수 있습니다.

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
import { getSession } from 'auth-astro/server';

const session = await getSession(Astro.request);
---
<Layout>
  {
    session ? (
      <p>Welcome {session.user?.name}</p>
    ) : (
      <p>Not logged in</p>
    )
  }
</Layout>

다음 단계

섹션 제목: 다음 단계

• GitHub의 auth-astro
• Auth.js 문서

다음 단계

섹션 제목: 다음 단계

• auth-astro on GitHub
• Auth.js documentation

Better Auth

섹션 제목: Better Auth

Better Auth는 프레임워크에 구애받지 않는 TypeScript용 인증 (및 권한 부여) 프레임워크입니다. 기본적으로 포괄적인 기능 세트를 제공하며 고급 기능을 간편하게 추가할 수 있는 플러그인 생태계가 포함되어 있습니다.

Astro를 즉시 지원하며, 이를 사용하여 Astro 프로젝트에 인증을 추가할 수 있습니다.

설치

섹션 제목: 설치

npm

npm install better-auth

pnpm

pnpm add better-auth

Yarn

yarn add better-auth

자세한 설정 지침은 Better Auth 설치 가이드를 참조하세요.

구성

섹션 제목: 구성

Better Auth 설치 가이드에 설명된 대로 사용자 데이터와 선호하는 인증 방법을 저장하도록 데이터베이스 테이블을 구성합니다. 그런 다음 Astro 프로젝트에 Better Auth 핸들러를 마운트해야 합니다.

page/api/auth/[...all].ts

import { auth } from "../../../lib/auth"; // Better Auth 인스턴스를 가져옵니다.
import type { APIRoute } from "astro";

export const ALL: APIRoute = async (ctx) => {
  return auth.handler(ctx.request);
};

자세한 내용은 Better Auth Astro 가이드를 참조하세요.

사용

섹션 제목: 사용

Better Auth는 Vanilla JS, React, Vue, Svelte, Solid를 포함한 다양한 프레임워크를 위한 createAuthClient 헬퍼를 제공합니다.

예를 들어, React용 클라이언트를 생성하려면 better-auth/react에서 헬퍼를 가져옵니다:

React

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/react';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Solid

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/solid';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Svelte

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/svelte';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

Vue

src/lib/auth-client.ts

import { createAuthClient } from 'better-auth/vue';

export const authClient = createAuthClient();

export const { signIn, signOut } = authClient;

클라이언트가 설정되면 이를 사용하여 Astro 컴포넌트 또는 프레임워크별 파일에서 사용자를 인증할 수 있습니다. 다음 예시에서는 구성된 signIn() 및 signOut() 함수를 사용하여 로그인 또는 로그아웃 기능을 추가합니다.

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
---
<Layout>
  <button id="login">Login</button>
  <button id="logout">Logout</button>

  <script>
    const { signIn, signOut } = await import("./lib/auth-client")
    document.querySelector("#login").onclick = () => signIn.social({
      provider: "github",
      callbackURL: "/dashboard",
    })
    document.querySelector("#logout").onclick = () => signOut()
  </script>
</Layout>

그런 다음 auth 객체를 사용하여 서버 측 코드에서 사용자의 세션 데이터를 가져올 수 있습니다. 다음 예시는 인증된 사용자의 이름을 표시하여 페이지 콘텐츠를 개인화합니다:

src/pages/index.astro

---
import { auth } from "../../../lib/auth"; // Better Auth 인스턴스를 가져옵니다.

const session = await auth.api.getSession({
  headers: Astro.request.headers,
});
---

<p>{session.user?.name}</p>

미들웨어와 auth 객체를 사용하여 경로를 보호할 수도 있습니다. 다음 예시는 로그인한 대시보드 경로에 액세스하려는 사용자가 인증되었는지 확인하고 인증되지 않은 경우 홈 페이지로 리디렉션합니다.

src/middleware.ts

import { auth } from "../../../auth"; // Better Auth 인스턴스를 가져옵니다.
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  const isAuthed = await auth.api
    .getSession({
      headers: context.request.headers,
    })
  if (context.url.pathname === "/dashboard" && !isAuthed) {
    return context.redirect("/");
  }
  return next();
});

다음 단계

섹션 제목: 다음 단계

• Better Auth Astro Guide
• Better Auth Astro Example
• Better Auth Documentation
• Better Auth GitHub Repository

Clerk

섹션 제목: Clerk

Clerk는 임베드 가능한 UI, 유연한 API, 관리자 대시보드로 구성된 완벽한 제품군으로 사용자를 인증하고 관리할 수 있습니다. Astro용 공식 Clerk SDK를 사용할 수 있습니다.

설치

섹션 제목: 설치

원하는 패키지 관리자를 사용하여 @clerk/astro를 설치합니다.

npm

npm install @clerk/astro

pnpm

pnpm add @clerk/astro

Yarn

yarn add @clerk/astro

구성

섹션 제목: 구성

Clerk의 자체 Astro 빠른 시작 가이드를 따라 Astro 프로젝트에서 Clerk 통합 및 미들웨어를 설정하세요.

사용

섹션 제목: 사용

Clerk는 사용자의 인증 상태에 따라 페이지의 표시 여부를 제어할 수 있는 컴포넌트를 제공합니다. 로그아웃한 사용자에게는 로그인한 사용자에게 제공되는 콘텐츠 대신 로그인 버튼을 표시합니다:

src/pages/index.astro

---
import Layout from 'src/layouts/Base.astro';
import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components';
---
<Layout>
    <SignedIn>
        <UserButton />
    </SignedIn>
    <SignedOut>
        <SignInButton />
    </SignedOut>
</Layout>

또한 Clerk를 사용하면 미들웨어를 통해 서버에서 경로를 보호할 수 있습니다. 보호할 경로를 지정하고 인증되지 않은 사용자에게 로그인하라는 메시지를 표시할 수 있습니다:

src/middleware.ts

import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server';

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/forum(.*)',
]);

export const onRequest = clerkMiddleware((auth, context) => {
  if (!auth().userId && isProtectedRoute(context.request)) {
    return auth().redirectToSignIn();
  }
});

다음 단계

섹션 제목: 다음 단계

• 공식 @clerk/astro 문서를 읽어보세요.
• Clerk + Astro 빠른 시작 프로젝트 템플릿으로 시작하세요.

Lucia

섹션 제목: Lucia

Lucia는 Astro를 비롯한 여러 프레임워크에서 세션 기반 인증을 구현하기 위한 리소스입니다.

가이드

섹션 제목: 가이드

1. 선택한 데이터베이스로 기본 세션 API를 생성합니다.
2. 엔드포인트와 미들웨어를 사용하여 세션 쿠키를 추가합니다.
3. 구현한 API를 사용하여 GitHub OAuth를 구현합니다.

예시

섹션 제목: 예시

• Astro에서 GitHub OAuth를 구현하는 예시
• Astro에서 Google OAuth를 구현하는 예시
• Astro에서 2FA를 사용하여 이메일 및 비밀번호를 구현하는 예시 example
• Astro에서 2FA와 WebAuthn를 사용하여 이메일 및 비밀번호를 구현하는 예시

커뮤니티 자료

섹션 제목: 커뮤니티 자료

• Astro 및 Azure Static Web App에서 Microsoft Entra Id EasyAuth 사용