Integrasi Autentikasi Lebih Baik

Ringkasan

Auth yang Lebih Baik berfungsi dengan baik dengan @capgo/capacitor-social-login ketika Anda ingin sign-in asli di perangkat tetapi masih ingin Auth yang Lebih Baik untuk membuat dan mengelola sesi di backend Anda.

Halaman ini berfokus pada dua pola integrasi yang paling sesuai:

• Penyerahan token asli untuk Google, Apple, dan Facebook
• Autentikasi Lebih Baik Generic OAuth untuk penyedia seperti Auth0, Okta, Keycloak, dan server OIDC kustom

Mana pola yang harus digunakan

Pakai pengalihan token asli

Pakai SocialLogin.login() terlebih dahulu, kemudian kirimkan token yang dikembalikan ke Autentikasi Lebih Baik dengan authClient.signIn.social() ketika Anda menggunakan:

• Google
• Apple
• Facebook

Pakai Generic OAuth Autentikasi Lebih Baik

Biarkan Autentikasi Lebih Baik mengambil alih alur redirect OAuth penuh ketika Anda menggunakan:

• Auth0
• Okta
• Keycloak
• GitHub
• OneLogin
• Jenis penyedia OAuth2 atau OIDC apa pun yang diatur sendiri

Yang menjaga pertukaran sesi di sisi Autentikasi Lebih Baik dan menghindari duplikasi logika redirect antara dua sistem.

Konfigurasi Server Autentikasi Lebih Baik

Mulai dengan mengonfigurasi Autentikasi Lebih Baik dengan penyedia sosial yang ingin Anda dukung:

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

Catatan

Untuk Apple pada iOS native, Dokumen Better Auth menyatakan bahwa Anda harus menyediakan appBundleIdentifier sehingga token ID Apple yang dihadirkan sesuai dengan identifikasi paket yang digunakan oleh iOS.

Pengaturan klien Better Auth

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

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

Jika Anda menggunakan React, gunakan paket klien Better Auth React yang digunakan oleh aplikasi Anda. Pola penyerahan token tetap sama.

Contoh Google

Integrasi ini adalah jalur yang paling bersih untuk sign-in Google mobile native:

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

Contoh Apple

Untuk Apple, kirim nonce yang sama ke kedua permintaan login native dan Better Auth:

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

Contoh Facebook

Better Auth mendokumentasikan dua mode handoff Facebook:

• iOS Limited Login: kirimkan idToken
• Aliran token akses: kirimkan token akses sebagai token dan accessToken

ini berfungsi dengan bentuk respons dari @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',
});

Pemasok OAuth umum dengan Better Auth

Untuk Auth0, Okta, Keycloak, GitHub, Microsoft Entra ID, dan penyedia lainnya yang mirip, plugin OAuth Generic Better Auth biasanya lebih baik daripada melewati token dari SocialLogin.login({ provider: 'oauth2' }).

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

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

Contoh penyedia untuk Better Auth OAuth Generic

Better Auth membawa bantuan konfigurasi yang sudah siap untuk beberapa penyedia. Bantuan ini adalah yang paling dekat dengan contoh penyedia tambahan yang Anda lihat di dokumen plugin social-login.

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 dengan konfigurasi OAuth Generic manual

GitHub tidak memiliki bantuan Autentikasi Lebih Baik pada halaman OAuth Generic, jadi gunakan konfigurasi manual:

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

Catatan dan peringatan

1. Gunakan Mode Online Google Better Auth membutuhkan idToken, jadi google.mode: 'offline' tidak cocok untuk aliran tukar gantian ini.

2. Ulangi Nonce Apple Generate sekali, kirim ke login native Apple, kemudian kirim nilai yang sama ke Better Auth.

3. Handling Facebook berbeda-beda tergantung platform Login Terbatas di iOS memberikan Anda token ID. Aliran lain mungkin hanya memberikan token akses.

4. Jangan campur aduk Aliran OAuth Generic kecuali Anda memiliki alasan Jika Better Auth mengelola konfigurasi provider OAuth, biarkan Better Auth mengelola aliran redirect juga.

Baca lebih lanjut

• Autentikasi Lebih Baik Dokumen Provider Google
• Autentikasi Lebih Baik Dokumen Provider Apple
• Autentikasi Lebih Baik Dokumen Provider Facebook
• Dokumen Plugin OAuth Generic Autentikasi Lebih Baik
• Provider Autentikasi Login Sosial OAuth2 dan OIDC

Teruskan dari Integrasi Autentikasi Lebih Baik

Jika Anda menggunakan Integrasi Autentikasi Lebih Baik untuk merencanakan autentikasi dan alur akun, hubungkannya dengan Menggunakan @capgo/capacitor-social-login untuk kemampuan native di Menggunakan @capgo/capacitor-social-login, @capgo/capacitor-login Sosial untuk detail implementasi di @capgo/capacitor-login Sosial, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-biometrik Nativ untuk detail implementasi di @capgo/capacitor-biometrik Nativ, dan Autentikasi Dua Faktor untuk detail implementasi di Autentikasi Dua Faktor.