일반 OAuth 통합

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

개요

Better Auth는 잘 작동합니다. @capgo/capacitor-social-login 장치에서 원시 로그인 기능을 원하지만 백엔드에서 세션을 생성하고 관리하고 싶다면.

이 페이지는 가장 적합한 두 가지 통합 패턴에 초점을 맞추고 있습니다.

Google, Apple, Facebook의 네이티브 토큰 전달
Auth0, Okta, Keycloak, 커스텀 OIDC 서버와 같은 제공자에 대한 Better Auth Generic OAuth

어떤 패턴을 사용할 것인가

네이티브 토큰 전달 사용

먼저, 반환된 토큰을 Better Auth에 보내주세요. SocialLogin.login() 다음과 같은 경우에 사용합니다. authClient.signIn.social() Google

Google
애플
페이스북

일반 OAuth 사용하기

__CAPGO_KEEP_0__

Auth0
Okta
Keycloak
GitHub
사용자 정의 OAuth2 또는 OIDC 제공자
이러한 경우 Better Auth가 전체 OAuth 리다이렉트 흐름을 관리하도록 하세요.

세션 교환을 Better Auth 쪽에 유지하고 두 시스템 간에 리다이렉트 로직을 중복하지 않도록 합니다.

인증 서버 설정

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

인증 클라이언트 설정

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

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

인증 서버 설정

Google 예시

native 모바일 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',
});

Apple 예시

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: nonce를 전달하십시오. idToken
Access-token flow: access token을 양쪽에 전달하세요. token and accessToken

This works with the response shape from @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',
});

Generic OAuth providers with Better Auth

For Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID, and similar providers, Better Auth’s Generic OAuth plugin is usually the better fit than passing tokens from SocialLogin.login({ provider: 'oauth2' }).

Better Auth server

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 client

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' 이 핸드오버 흐름에 적합하지 않은 올바른 선택은 아닙니다.
Apple nonce을 재사용하세요 Apple native 로그인에 한번만 생성한 후 Better Auth로 동일한 값을 전송하세요.
플랫폼에 따라 Facebook을 다르게 처리하세요 iOS에서 Limited Login은 ID 토큰을 제공합니다. 다른 흐름은 접근 토큰만 제공할 수 있습니다.
일반 OAuth 흐름을 혼합하지 마세요. 이유가 있다면 제외합니다. Better Auth가 OAuth 제공자 구성에 소유권을 가지고 있다면, Better Auth가 리다이렉트 흐름도 소유권을 가지고 있도록 해보세요.

추가 읽기

Better Auth와 함께 계속 진행

Capgo를 사용하고 있다면 Capgo와의 통합 인증 및 계정 흐름을 계획하고 연결하세요. @capgo/capacitor-social-login을 사용하여 @capgo/capacitor-social-login의 원시 기능을 사용하여 @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 정보를 사용하여 @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 정보를 사용하여 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 정보를 사용하여 두 가지 인증 방법을 사용합니다. 두 단계 인증 두 단계 인증의 구현 세부 정보를 사용하여