Better Auth Integration

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

개요

Better Auth는 @capgo/capacitor-social-login 디바이스에서 원생 로그인 기능을 원하지만, Better Auth가 백엔드에서 세션을 생성하고 관리하고 싶을 때

이 페이지는 두 가지 통합 패턴에 중점을 둡니다.

Native token handoff는 Google, Apple, Facebook과 같은 서비스에 사용할 수 있습니다.
Better Auth Generic OAuth는 Auth0, Okta, Keycloak, OIDC 서버와 같은 서비스에 사용할 수 있습니다.

어떤 패턴을 사용할지 결정하세요

native 토큰 전달을 사용하세요

native 토큰 전달을 사용하세요 SocialLogin.login() 먼저 native 토큰 전달을 사용하고, 반환된 토큰을 Better Auth에 보내세요. authClient.signIn.social() when you use:

Google
Apple
Facebook

Better Auth Generic OAuth를 사용하세요

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

__CAPGO_KEEP_0__
Auth0
Okta
GitHub
__CAPGO_KEEP_0__
Any custom OAuth2 or OIDC provider

__CAPGO_KEEP_0__

Better Auth 서버 설정

__CAPGO_KEEP_0__

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 client setup

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

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

React를 사용하는 경우,

Google example

This is the cleanest integration path for native mobile Google sign-in:

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',
});

Apple example

Apple의 경우, 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',
});

Facebook 예시

Better Auth는 두 가지 Facebook 전환 모드를 문서화합니다.

iOS Limited Login: native 로그인 요청에 idToken
Access-token flow: access token을 both에 token and 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 플러그인은 보통 토큰을 전달하는 것보다 보다 나은 인증의 일반 OAuth 플러그인이 더 적합합니다. 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,
        },
      ],
    }),
  ],
});

__CAPGO_KEEP_0__

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',
});

Auth0

__CAPGO_KEEP_0__

Better Auth Generic OAuth의 제공자 예제

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',
});

__CAPGO_KEEP_0__

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',
});

__CAPGO_KEEP_0__

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는 일반 OAuth 페이지에 필요합니다. idToken이것은 이 전달 흐름에 적합하지 않습니다. google.mode: 'offline' Apple nonce을 다시 사용하세요.
Apple 원래 로그인에 한번만 생성하여 전송하고, 동일한 값을 Better Auth로 전송하세요. Facebook은 플랫폼에 따라 다르게 처리하세요.
iOS에서만 Limited Login은 ID 토큰을 제공합니다. 다른 흐름은 접근 토큰만 제공할 수 있습니다. 일반 OAuth 흐름을 혼합하지 마세요. 이유가 있다면.
Better Auth가 OAuth 제공자 구성에 소유권을 가지고 있다면, Better Auth가 리다이렉트 흐름도 소유권을 가지고 있도록 하세요. 추가 읽기

제목이 '추가 읽기'인 섹션

Capgo Better Auth 통합에서 계속

Capgo Better Auth 통합을 사용 중이라면 Capgo Better Auth 통합 인증 및 계정 흐름을 계획하고 연결하려면 Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login Using @capgo/capacitor-social-login @capgo/capacitor-passkey implementation 세부 정보를 위한 @capgo/capacitor-passkey @capgo/capacitor-native-biometric implementation 세부 정보를 위한 @capgo/capacitor-native-biometric, 그리고 두 단계 인증 두 단계 인증의 implementation 세부 정보를 위한