Better Auth Integration

개요

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

이 플러그인은 장치에서 원시적인 로그인에 잘 작동하지만 여전히 Better Auth가 백엔드에서 세션을 관리하도록 하려는 경우에 잘 작동합니다.

• 구글, 애플, 페이스북과 같은 네이티브 토큰 전달
• Auth0, Okta, Keycloak, 커스텀 OIDC 서버와 같은 Generic OAuth 제공자

어떤 패턴을 사용할까요?

네이티브 토큰 전달 사용

사용 SocialLogin.login() 먼저, Better Auth에 반환된 토큰을 보낼 때 authClient.signIn.social() 구글

• 애플
• 페이스북
• when you use:

Better Auth Generic OAuth 사용

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

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• OIDC 또는 OAuth2를 사용하는 모든 커스텀 제공자

Better Auth 서버 설정

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

참고

Apple을 위한 native iOS에서 Better Auth는 Apple ID 토큰의 대상이 iOS에서 사용하는 패키지 식별자와 일치해야 한다고 문서화합니다. appBundleIdentifier Better Auth 클라이언트 설정

Better Auth 클라이언트 설정

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

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

Google 예시

Google 예시

이것은 네이티브 모바일 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

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

주의 사항 및 주의사항

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가 리다이렉트 흐름도 소유권을 가지고 있도록 하세요.

추가 읽기

• Google 제공자 문서
• Apple 제공자 문서
• Facebook 제공자 인증 Better Auth
• 소셜 로그인 플러그인 - 더 나은 인증
• 소셜 로그인 OAuth2 및 OIDC 제공자

더 나은 인증 통합에서 계속 진행하세요

Capgo를 사용 중이라면 Better 인증 통합 인증 및 계정 흐름을 계획하고 연결하려면 Capgo의 @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 구현 세부 사항을 위해, 두 단계 인증 두 단계 인증 구현 세부 사항을 위해