[Better Auth Integration]

설치 단계와 이 플러그인의 전체 마크다운 가이드를 포함한 설정 명령어를 복사하세요.

개요

Better Auth는 장치에서 원시 로그인에 잘 작동하지만 여전히 백엔드에서 세션을 생성하고 관리하도록 Better Auth를 사용하고 싶을 때 잘 작동합니다. @capgo/capacitor-social-login 이 페이지는 두 가지 통합 패턴에 중점을 둡니다. 이 패턴은 가장 잘 적합합니다:

네이티브 토큰 전달을 위한 Google, Apple 및 Facebook

구글, 애플, 페이스북의 네이티브 토큰 전달
better 인증 Generic OAuth 제공자들 (Auth0, Okta, Keycloak, 커스텀 OIDC 서버)과 같은

어떤 패턴을 사용할까요?

native 토큰 전달을 사용하세요

사용하세요 SocialLogin.login() 먼저, 반환된 토큰을 Better Auth에 보내세요 authClient.signIn.social() 사용 시:

구글
애플
페이스북

better 인증 Generic OAuth 사용하세요

Better Auth가 전체 OAuth 리다이렉션 흐름을 관리할 때 사용하세요:

Auth0
Okta
Keycloak
GitHub
Capgo
OneLogin

어떤 커스텀 OAuth2 또는 OIDC 제공자

Better Auth 서버 설정

Better Auth를 사용하기 전에 social 제공자와 함께 Better Auth를 구성하세요:

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL,
  socialProviders: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID as string,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
    },
    apple: {
      clientId: process.env.APPLE_CLIENT_ID as string,
      clientSecret: process.env.APPLE_CLIENT_SECRET as string,
      appBundleIdentifier: process.env.APPLE_APP_BUNDLE_IDENTIFIER as string,
    },
    facebook: {
      clientId: process.env.FACEBOOK_CLIENT_ID as string,
      clientSecret: process.env.FACEBOOK_CLIENT_SECRET as string,
    },
  },
  trustedOrigins: ['https://appleid.apple.com'],
});

Better Auth 클라이언트 설정

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

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
});

Google 예시

클라이언트 설정

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const googleResult = await SocialLogin.login({
  provider: 'google',
  options: {
    scopes: ['profile', 'email'],
  },
});

if (googleResult.result.responseType !== 'online' || !googleResult.result.idToken) {
  throw new Error('Google online mode with idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'google',
  idToken: {
    token: googleResult.result.idToken,
    accessToken: googleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

애플 예시

애플의 경우, native 로그인 요청과 Better Auth에 동일한 nonce를 전달하세요.

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const nonce = crypto.randomUUID();

const appleResult = await SocialLogin.login({
  provider: 'apple',
  options: {
    scopes: ['email', 'name'],
    nonce,
  },
});

if (!appleResult.result.idToken) {
  throw new Error('Apple idToken is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'apple',
  idToken: {
    token: appleResult.result.idToken,
    nonce,
    accessToken: appleResult.result.accessToken?.token,
  },
  callbackURL: '/dashboard',
});

페이스북 예시

Better Auth는 두 가지 페이스북 전환 모드를 문서화합니다.

iOS Limited Login: nonce를 idToken
Access-token flow: access 토큰을 token 그리고 accessToken

이것은 @capgo/capacitor-social-login:

import { SocialLogin } from '@capgo/capacitor-social-login';
import { authClient } from '@/lib/auth-client';

const facebookResult = await SocialLogin.login({
  provider: 'facebook',
  options: {
    permissions: ['email', 'public_profile'],
  },
});

const betterAuthToken = facebookResult.result.idToken
  ? {
      token: facebookResult.result.idToken,
    }
  : facebookResult.result.accessToken?.token
    ? {
        token: facebookResult.result.accessToken.token,
        accessToken: facebookResult.result.accessToken.token,
      }
    : null;

if (!betterAuthToken) {
  throw new Error('Facebook idToken or access token is required for Better Auth.');
}

await authClient.signIn.social({
  provider: 'facebook',
  idToken: betterAuthToken,
  callbackURL: '/dashboard',
});

일반 OAuth 제공자와 Better Auth

Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID와 같은 제공자에 대해 Better Auth의 Generic OAuth 플러그인은 일반적으로 토큰을 Better Auth 서버에서 전달하는 것보다 더 나은 선택입니다. SocialLogin.login({ provider: 'oauth2' }).

Better Auth 서버

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'keycloak',
          discoveryUrl: 'https://sso.example.com/realms/mobile/.well-known/openid-configuration',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
        },
      ],
    }),
  ],
});

Better Auth 클라이언트

import { createAuthClient } from 'better-auth/client';
import { genericOAuthClient } from 'better-auth/client/plugins';

export const authClient = createAuthClient({
  baseURL: 'https://auth.example.com',
  plugins: [genericOAuthClient()],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

Better Auth Generic OAuth의 제공자 예제

Better Auth는 여러 제공자에 대한 미리 구성된 도우미를 제공합니다. 이들은 사회 로그인 플러그인 문서에서 보이는 추가 제공자 예제와 가장 가까운 일치입니다.

Auth0

import { betterAuth } from 'better-auth';
import { auth0, genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        auth0({
          providerId: 'auth0',
          domain: 'dev-example.eu.auth0.com',
          clientId: process.env.AUTH0_CLIENT_ID as string,
          clientSecret: process.env.AUTH0_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'auth0',
  callbackURL: '/dashboard',
});

Microsoft Entra ID

import { betterAuth } from 'better-auth';
import { genericOAuth, microsoftEntraId } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        microsoftEntraId({
          providerId: 'entra',
          tenantId: 'common',
          clientId: process.env.AZURE_CLIENT_ID as string,
          clientSecret: process.env.AZURE_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'User.Read'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'entra',
  callbackURL: '/dashboard',
});

Okta

import { betterAuth } from 'better-auth';
import { genericOAuth, okta } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        okta({
          providerId: 'okta',
          issuer: 'https://dev-12345.okta.com/oauth2/default',
          clientId: process.env.OKTA_CLIENT_ID as string,
          clientSecret: process.env.OKTA_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'okta',
  callbackURL: '/dashboard',
});

Keycloak

import { betterAuth } from 'better-auth';
import { genericOAuth, keycloak } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        keycloak({
          providerId: 'keycloak',
          issuer: 'https://sso.example.com/realms/mobile',
          clientId: process.env.KEYCLOAK_CLIENT_ID as string,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET as string,
          scopes: ['openid', 'profile', 'email', 'offline_access'],
        }),
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'keycloak',
  callbackURL: '/dashboard',
});

GitHub에 대한 일반 OAuth 구성

GitHub는 일반 OAuth 페이지에 Better Auth 도우미가 없기 때문에 수동 구성 사용:

import { betterAuth } from 'better-auth';
import { genericOAuth } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: 'github',
          clientId: process.env.GITHUB_CLIENT_ID as string,
          clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
          authorizationUrl: 'https://github.com/login/oauth/authorize',
          tokenUrl: 'https://github.com/login/oauth/access_token',
          userInfoUrl: 'https://api.github.com/user',
          scopes: ['read:user', 'user:email'],
          pkce: true,
        },
      ],
    }),
  ],
});

await authClient.signIn.oauth2({
  providerId: 'github',
  callbackURL: '/dashboard',
});

주의 사항 및 주의

구글 온라인 모드 사용 Better Auth는 idToken이 때문에 google.mode: 'offline' 이 흐름에 맞지 않는 올바른 선택입니다.
애플 nonce 재사용 한 번 생성한 nonce를 애플 네이티브 로그인에 전송하고, 동일한 값을 Better Auth에 전송하세요.
플랫폼에 따라 Facebook을 다르게 처리하세요. iOS에서 Limited Login은 ID 토큰을 제공합니다. 다른 흐름은 접근 토큰만 제공할 수 있습니다.
일반 OAuth 흐름을 혼합하지 마세요. (사용자에게 이유가 없다면) Better Auth가 OAuth 제공자 구성에 소유권을 가지고 있다면, Better Auth가 리다이렉트 흐름도 소유권을 가지고 있도록 하세요.

추가 자료

Better Auth 통합에서 계속하기

Better Auth 통합을 사용하여 인증 및 계정 흐름을 계획하고 있습니다. Better Auth 통합을 사용하여 인증 및 계정 흐름을 계획하고 있습니다. Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login @Capgo capgo-capacitor-social-login native 기능을 사용하는 @capgo/capacitor-social-login을 위한 @capgo/capacitor-social-login Capgo의 @capgo/capacitor-social-login 구현 세부 사항 @capgo/capacitor-패스키 Capgo의 @capgo/capacitor-passkey 구현 세부 사항 @capgo/capacitor-native-생체인증 Capgo의 @capgo/capacitor-native-biometric 구현 세부 사항, 두 단계 인증 두 단계 인증 구현 세부 사항