내용으로 건너뛰기
Capgo - Capacitor 앱에 대한 실시간 업데이트 Capgo

Better Auth Integration

GitHub

개요

“개요”라는 제목을 가진 섹션

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

__CAPGO_KEEP_0__

  • Native token handoff for Google, Apple, and Facebook
  • Better Auth Generic OAuth for providers like Auth0, Okta, Keycloak, and custom OIDC servers

어떤 패턴을 사용해야 하나요?

Section titled “어떤 패턴을 사용해야 하나요?”

Native token handoff 사용

Section titled “Native token handoff 사용”

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

  • 구글
  • 애플
  • 페이스북

Better Auth Generic OAuth 사용

Better Auth Generic OAuth 사용하기

Better Auth Generic OAuth를 사용할 때 Better Auth가 전체 OAuth 리다이렉션 흐름을 소유합니다.

  • Auth0
  • Okta
  • Keycloak
  • GitHub
  • OneLogin
  • OIDC 또는 OAuth2 제공업체

Better Auth 서버 설정

Better Auth 서버 설정하기

Better Auth Generic OAuth를 사용할 때 Better Auth가 전체 OAuth 리다이렉션 흐름을 소유하여 두 시스템 간에 리다이렉션 로직을 중복하지 않도록 세션 교환을 Better Auth 쪽에 유지합니다.

Better Auth를 사용하기 위해 먼저 social 제공자들을 설정하세요:

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 예시

Google 예시

Better Auth 클라이언트 설정

이것은 네이티브 모바일 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 login 요청과 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: pass the idToken
  • Access-token flow: access token을 both token 그리고 accessToken

이 기능은 Better Auth의 Generic OAuth 플러그인에서 사용하는 응답 형태와 함께 작동합니다. @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

제목이 "일반 OAuth 제공자와 함께 Better Auth"인 섹션

Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID와 같은 제공자에 대해 Better Auth Generic OAuth 플러그인이 보통 토큰을 Better Auth에서 받는 것보다 더 적합한 선택일 때, Generic OAuth 플러그인이 사용됩니다. SocialLogin.login({ provider: 'oauth2' }).

Better Auth 서버

제목이 "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 클라이언트

제목이 "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 Generic OAuth

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

Auth0

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

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

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

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 구성 섹션

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

주의 사항 및 주의사항

Section titled “Notes and caveats”

  1. 구글 온라인 모드를 사용하세요 Better Auth는 idToken, 그래서 google.mode: 'offline' 이 핸드오버 흐름에 맞지 않는 올바른 선택이 아닙니다.

  2. 애플 nonce를 재사용하세요 한 번 생성한 nonce를 애플 네이티브 로그인에 전송하고, 동일한 값을 Better Auth로 전송하세요.

  3. 플랫폼에 따라 Facebook을 다르게 처리하세요 iOS에서 Limited Login은 ID 토큰을 제공합니다. 다른 흐름은 접근 토큰만 제공할 수 있습니다.

  4. 일반 OAuth 흐름을 혼합하지 마세요. 이유가 있다면 제외합니다. Better Auth가 OAuth 제공자 구성에 소유권을 가지고 있다면, Better Auth가 리다이렉트 흐름도 소유권을 가지고 있도록 하세요.

추가 읽기

Further reading

Better Auth 통합으로 계속

Better Auth 통합으로 계속

Better Auth 통합을 사용하여 인증 및 계정 흐름을 계획하고 있습니다. Better Auth 통합과 연결하세요. Using @capgo/capacitor-social-login Capgo의 내장 기능을 사용하기 위해 @capgo/capacitor-social-login을 사용하세요. @capgo/capacitor-social-login Capgo의 구현 세부 정보를 위해 @capgo/capacitor-social-login을 사용하세요. @capgo/capacitor-passkey Capgo의 구현 세부 정보를 위해 @capgo/capacitor-passkey을 사용하세요. @capgo/capacitor-native-biometric Capgo의 구현 세부 정보를 위해 @capgo/capacitor-native-biometric을 사용하세요. 두 단계 인증 두 단계 인증의 구현 세부 정보를 위해 사용하세요.