Generic OAuth

Generic OAuth 플러그인은 모든 OAuth 제공자와 인증을 통합하는 유연한 방법을 제공합니다. OAuth 2.0 및 OpenID Connect(OIDC) 플로우를 모두 지원하여 애플리케이션에 소셜 로그인이나 사용자 정의 OAuth 인증을 쉽게 추가할 수 있습니다.

설치

auth 설정에 플러그인 추가

Generic OAuth 플러그인을 사용하려면 auth 설정에 추가합니다.

auth.ts
import { betterAuth } from "better-auth"
import { genericOAuth } from "better-auth/plugins"

export const auth = betterAuth({
    // ... 기타 설정 옵션
    plugins: [
        genericOAuth({ 
            config: [ 
                { 
                    providerId: "provider-id", 
                    clientId: "test-client-id", 
                    clientSecret: "test-client-secret", 
                    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration", 
                    // ... 기타 설정 옵션
                }, 
                // 필요에 따라 더 많은 제공자 추가
            ] 
        }) 
    ]
})

클라이언트 플러그인 추가

인증 클라이언트 인스턴스에 Generic OAuth 클라이언트 플러그인을 포함합니다.

auth-client.ts
import { createAuthClient } from "better-auth/client"
import { genericOAuthClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [
        genericOAuthClient()
    ]
})

사용법

Generic OAuth 플러그인은 OAuth 플로우를 시작하고 콜백을 처리하는 엔드포인트를 제공합니다. 사용 방법은 다음과 같습니다:

OAuth 로그인 시작

OAuth 로그인 프로세스를 시작하려면:

POST
/sign-in/oauth2
const { data, error } = await authClient.signIn.oauth2({    providerId: "provider-id", // required    callbackURL: "/dashboard",    errorCallbackURL: "/error-page",    newUserCallbackURL: "/welcome",    disableRedirect: false,    scopes: ["my-scope"],    requestSignUp: false,});
PropDescriptionType
providerId
OAuth 제공자의 제공자 ID
string
callbackURL?
로그인 후 리디렉션할 URL
string
errorCallbackURL?
오류 발생 시 리디렉션할 URL
string
newUserCallbackURL?
사용자가 신규인 경우 로그인 후 리디렉션할 URL
string
disableRedirect?
리디렉션 비활성화
boolean
scopes?
제공자 권한 요청에 전달될 스코프
string[]
requestSignUp?
명시적으로 가입 요청. 이 제공자에 대해 disableImplicitSignUp이 true일 때 유용합니다
boolean

OAuth 계정 연결

기존 사용자에게 OAuth 계정을 연결하려면:

POST
/oauth2/link
const { data, error } = await authClient.oauth2.link({    providerId: "my-provider-id", // required    callbackURL: "/successful-link", // required});
PropDescriptionType
providerId
OAuth 제공자 ID
string
callbackURL
계정 연결이 완료되면 리디렉션할 URL
string

OAuth 콜백 처리

플러그인은 OAuth 콜백을 처리하기 위해 /oauth2/callback/:providerId 경로를 마운트합니다. 즉, 기본적으로 ${baseURL}/api/auth/oauth2/callback/:providerId가 콜백 URL로 사용됩니다. OAuth 제공자가 이 URL을 사용하도록 구성되어 있는지 확인하십시오.

구성

auth 설정에 플러그인을 추가할 때 여러 OAuth 제공자를 구성할 수 있습니다. 각 제공자 구성 객체는 다음 옵션을 지원합니다:

interface GenericOAuthConfig {
  providerId: string;
  discoveryUrl?: string;
  authorizationUrl?: string;
  tokenUrl?: string;
  userInfoUrl?: string;
  clientId: string;
  clientSecret: string;
  scopes?: string[];
  redirectURI?: string;
  responseType?: string;
  prompt?: string;
  pkce?: boolean;
  accessType?: string;
  getUserInfo?: (tokens: OAuth2Tokens) => Promise<User | null>;
}

기타 제공자 구성

providerId: OAuth 제공자 구성을 식별하는 고유 문자열입니다.

discoveryUrl: (선택사항) 제공자의 OAuth 2.0/OIDC 구성을 가져올 URL입니다. 제공된 경우 authorizationUrl, tokenUrl, userInfoUrl과 같은 엔드포인트를 자동으로 검색할 수 있습니다.

authorizationUrl: (선택사항) OAuth 제공자의 권한 엔드포인트입니다. discoveryUrl을 사용하는 경우 필요하지 않습니다.

tokenUrl: (선택사항) OAuth 제공자의 토큰 엔드포인트입니다. discoveryUrl을 사용하는 경우 필요하지 않습니다.

userInfoUrl: (선택사항) 사용자 프로필 정보를 가져오는 엔드포인트입니다. discoveryUrl을 사용하는 경우 필요하지 않습니다.

clientId: 제공자가 발급한 OAuth 클라이언트 ID입니다.

clientSecret: 제공자가 발급한 OAuth 클라이언트 시크릿입니다.

scopes: (선택사항) 제공자에게 요청할 스코프 배열입니다(예: ["openid", "email", "profile"]).

redirectURI: (선택사항) OAuth 플로우에 사용할 리디렉션 URI입니다. 설정하지 않으면 앱의 기본 URL을 기반으로 기본값이 구성됩니다.

responseType: (선택사항) OAuth 응답 유형입니다. 권한 코드 플로우의 경우 기본값은 "code"입니다.

responseMode: (선택사항) 권한 코드 요청의 응답 모드입니다. "query" 또는 "form_post"와 같은 값을 사용합니다.

prompt: (선택사항) 인증 경험을 제어합니다(예: 강제 로그인, 동의 등).

pkce: (선택사항) true인 경우 보안 강화를 위해 PKCE(Proof Key for Code Exchange)를 활성화합니다. 기본값은 false입니다.

accessType: (선택사항) 권한 요청의 액세스 유형입니다. 리프레시 토큰을 요청하려면 "offline"을 사용합니다.

getUserInfo: (선택사항) OAuth 토큰이 주어졌을 때 제공자로부터 사용자 정보를 가져오는 사용자 정의 함수입니다. 제공되지 않으면 기본 fetch가 사용됩니다.

mapProfileToUser: (선택사항) 제공자의 사용자 프로필을 앱의 사용자 객체에 매핑하는 함수입니다. 사용자 정의 필드 매핑이나 변환에 유용합니다.

authorizationUrlParams: (선택사항) 권한 URL에 추가할 추가 쿼리 매개변수입니다. 기본 매개변수를 재정의할 수 있습니다. 매개변수를 반환하는 함수를 제공할 수도 있습니다.

tokenUrlParams: (선택사항) 토큰 URL에 추가할 추가 쿼리 매개변수입니다. 기본 매개변수를 재정의할 수 있습니다. 매개변수를 반환하는 함수를 제공할 수도 있습니다.

disableImplicitSignUp: (선택사항) true인 경우 신규 사용자의 자동 가입을 비활성화합니다. 로그인은 가입 의도와 함께 명시적으로 요청해야 합니다.

disableSignUp: (선택사항) true인 경우 신규 사용자의 가입을 완전히 비활성화합니다. 기존 사용자만 로그인할 수 있습니다.

authentication: (선택사항) 토큰 요청의 인증 방법입니다. 'basic' 또는 'post'일 수 있습니다. 기본값은 'post'입니다.

discoveryHeaders: (선택사항) 검색 요청에 포함할 사용자 정의 헤더입니다. 특수 헤더가 필요한 제공자에 유용합니다.

authorizationHeaders: (선택사항) 권한 요청에 포함할 사용자 정의 헤더입니다. 특수 헤더가 필요한 제공자에 유용합니다.

overrideUserInfo: (선택사항) true인 경우 사용자가 로그인할 때마다 데이터베이스의 사용자 정보가 제공자의 정보로 업데이트됩니다. 기본값은 false입니다.

고급 사용법

사용자 정의 사용자 정보 가져오기

특정 제공자 요구사항을 처리하기 위해 사용자 정의 getUserInfo 함수를 제공할 수 있습니다:

genericOAuth({
  config: [
    {
      providerId: "custom-provider",
      // ... 기타 설정 옵션
      getUserInfo: async (tokens) => {
        // 사용자 정보를 가져와 반환하는 사용자 정의 로직
        const userInfo = await fetchUserInfoFromCustomProvider(tokens);
        return {
          id: userInfo.sub,
          email: userInfo.email,
          name: userInfo.name,
          // ... 필요에 따라 다른 필드 매핑
        };
      }
    }
  ]
})

사용자 정보 필드 매핑

제공자가 반환한 사용자 정보가 예상 형식과 일치하지 않거나 추가 필드를 매핑해야 하는 경우 mapProfileToUser를 사용할 수 있습니다:

genericOAuth({
  config: [
    {
      providerId: "custom-provider",
      // ... 기타 설정 옵션
      mapProfileToUser: async (profile) => {
        return {
          firstName: profile.given_name,
          // ... 필요에 따라 다른 필드 매핑
        };
      }
    }
  ]
})

오류 처리

플러그인에는 일반적인 OAuth 문제에 대한 내장 오류 처리가 포함되어 있습니다. 오류는 일반적으로 URL 매개변수에 적절한 오류 메시지와 함께 애플리케이션의 오류 페이지로 리디렉션됩니다. 콜백 URL이 제공되지 않으면 사용자는 Better Auth의 기본 오류 페이지로 리디렉션됩니다.

Edit on GitHub

Previous Page

Passkey

Next Page

One Tap

On this page